2 _dnl__ Copyright (c) 1991 1992 Free Software Foundation, Inc.
4 \input texinfo @c -*-Texinfo-*-
5 @c Copyright (c) 1991 1992 Free Software Foundation, Inc.
7 @c Set a bunch of variables; this should go into a separate config file
53 @c Other miscellaneous parameters.
61 @set have-diff-table-kludge
73 @c Get around lameness in texinfo conditional constructs.
92 @c Some string definitions.
98 @set gdb-init _GDBINIT__
101 @set mach-dep _MACH_DEP__
104 @c %**start of header
105 @setfilename @value{as}.info
107 @settitle Using @value{as}
110 @settitle Using @value{as} (@value{host})
112 @setchapternewpage odd
120 * As: (as). The GNU assembler.
130 NOTE: this manual is marked up for preprocessing with a collection
131 of m4 macros called "pretex.m4".
133 THIS IS THE FULL SOURCE. The full source needs to be run through m4
134 before either tex- or info- formatting: for example,
135 m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
136 will produce (assuming your path finds either GNU or SysV m4; Berkeley
137 won't do) a file, configured for the M680x0 version of GAS, suitable for
138 formatting. See the text in "pretex.m4" for a fuller explanation (and
139 the macro definitions).
144 This file documents the GNU Assembler "@value{as}".
146 Copyright (C) 1991, 1992 Free Software Foundation, Inc.
148 Permission is granted to make and distribute verbatim copies of
149 this manual provided the copyright notice and this permission notice
150 are preserved on all copies.
153 Permission is granted to process this file through Tex and print the
154 results, provided the printed document carries copying permission
155 notice identical to this one except for the removal of this paragraph
156 (this paragraph not being relevant to the printed manual).
159 Permission is granted to copy and distribute modified versions of this
160 manual under the conditions for verbatim copying, provided also that the
161 section entitled ``GNU General Public License'' is included exactly as
162 in the original, and provided that the entire resulting derived work is
163 distributed under the terms of a permission notice identical to this
166 Permission is granted to copy and distribute translations of this manual
167 into another language, under the above conditions for modified versions,
168 except that the section entitled ``GNU General Public License'' may be
169 included in a translation approved by the Free Software Foundation
170 instead of in the original English.
174 @title Using @value{as}
175 @subtitle The GNU Assembler
177 @subtitle for the _HOST__ family
180 @subtitle November 1992
183 The Free Software Foundation Inc. thanks The Nice Computer
184 Company of Australia for loaning Dean Elsner to write the
185 first (Vax) version of @code{as} for Project GNU.
186 The proprietors, management and staff of TNCCA thank FSF for
187 distracting the boss while they got some work
190 @author Dean Elsner, Jay Fenlason & friends
191 @c edited by: pesch@cygnus.com
194 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
195 \xdef\manvers{\$Revision$} % For use in headers, footers too
197 \hfill {\it Using {\tt @value{as}}} \manvers\par
198 \hfill \TeX{}info \texinfoversion\par
199 \hfill Edited by Roland Pesch for Cygnus Support\par
201 %"boxit" macro for figures:
202 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
203 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
204 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
205 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
206 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
209 @vskip 0pt plus 1filll
210 Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
212 Permission is granted to make and distribute verbatim copies of
213 this manual provided the copyright notice and this permission notice
214 are preserved on all copies.
216 Permission is granted to copy and distribute modified versions of this
217 manual under the conditions for verbatim copying, provided also that the
218 section entitled ``GNU General Public License'' is included exactly as
219 in the original, and provided that the entire resulting derived work is
220 distributed under the terms of a permission notice identical to this
223 Permission is granted to copy and distribute translations of this manual
224 into another language, under the above conditions for modified versions,
225 except that the section entitled ``GNU General Public License'' may be
226 included in a translation approved by the Free Software Foundation
227 instead of in the original English.
232 @top Using @value{as}
234 This file is a user guide to the GNU assembler @code{@value{as}}.
236 This version of the file describes @code{@value{as}} configured to generate
237 code for @value{host} architectures.
240 * Overview:: Overview
241 * Invoking:: Command-Line Options
243 * Sections:: Sections and Relocation
245 * Expressions:: Expressions
246 * Pseudo Ops:: Assembler Directives
247 * _MACH_DEP__:: Machine Dependent Features
248 * Copying:: GNU GENERAL PUBLIC LICENSE
256 This manual is a user guide to the GNU assembler @code{@value{as}}.
258 This version of the manual describes @code{@value{as}} configured to generate
259 code for @value{host} architectures.
263 @cindex invocation summary
264 @cindex option summary
265 @cindex summary of options
266 Here is a brief summary of how to invoke @code{@value{as}}. For details,
267 @pxref{Invoking,,Comand-Line Options}.
269 @c We don't use deffn and friends for the following because they seem
270 @c to be limited to one line for the header.
272 @value{as} [ -a | -al | -as ] [ -D ] [ -f ]
273 [ -I @var{path} ] [ -K ] [ -L ]
274 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
275 @c am29k, h8, z8k have no machine-dependent assembler options
277 @c see md_parse_option in tc-i960.c
278 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
282 [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
284 [ -- | @var{files} @dots{} ]
290 @samp{-ad}, omit debugging pseudo-ops from listing,
291 @samp{-ah}, include high-level source,
292 @samp{-al}, assembly listing,
293 @samp{-an}, no forms processing,
294 @samp{-as}, symbols. These options may be combined; @emph{e.g.},
295 @samp{-aln} for assembly listing without forms processing.
296 By itself, @samp{-a} defaults to @samp{-ahls} --- that is, all listings
300 This option is accepted only for script compatibility with calls to
301 other assemblers; it has no effect on @code{@value{as}}.
304 ``fast''---skip preprocessing (assume source is compiler output)
307 Add @var{path} to the search list for @code{.include} directives
310 _if__((!_GENERIC__) && !_DIFFTABKLUG__)
311 This option is accepted but has no effect on the @value{host} family.
312 _fi__((!_GENERIC__) && !_DIFFTABKLUG__)
313 _if__(_GENERIC__ || _DIFFTABKLUG__)
314 Issue warnings when difference tables altered for long displacements.
315 _fi__(_GENERIC__ || _DIFFTABKLUG__)
318 Keep (in symbol table) local symbols, starting with @samp{L}
320 @item -o @var{objfile}
321 Name the object-file output from @code{@value{as}}
324 Fold data section into text section
327 Announce @code{as} version
330 Suppress warning messages
332 @item -- | @var{files} @dots{}
333 Standard input, or source files to assemble.
338 The following options are available when @value{as} is configured for the
339 Intel 80960 processor.
342 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
343 Specify which variant of the 960 architecture is the target.
346 Add code to collect statistics about branches taken.
349 Do not alter compare-and-branch instructions for long displacements;
356 The following options are available when @value{as} is configured for the
357 Motorola 68000 series.
362 Shorten references to undefined symbols, to one word instead of two.
364 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -mcpu32
365 Specify what processor in the 68000 family is the target. The default
366 is normally the 68020, but this can be changed at configuration time.
368 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
369 The target machine does (or does not) have a floating-point coprocessor.
370 The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
371 the basic 68000 is not compatible with the 68881, a combination of the
372 two can be specified, since it's possible to do emulation of the
373 coprocessor instructions with the main processor.
375 @item -m68851 | -mno-68851
376 The target machine does (or does not) have a memory-management
377 unit coprocessor. The default is to assume an MMU for 68020 and up.
383 * Manual:: Structure of this Manual
384 * GNU Assembler:: @value{as}, the GNU Assembler
385 * Object Formats:: Object File Formats
386 * Command Line:: Command Line
387 * Input Files:: Input Files
388 * Object:: Output (Object) File
389 * Errors:: Error and Warning Messages
393 @section Structure of this Manual
395 @cindex manual, structure and purpose
396 This manual is intended to describe what you need to know to use
397 @sc{gnu} @code{@value{as}}. We cover the syntax expected in source files, including
398 notation for symbols, constants, and expressions; the directives that
399 @code{@value{as}} understands; and of course how to invoke @code{@value{as}}.
402 We also cover special features in the @value{host}
403 configuration of @code{@value{as}}, including assembler directives.
406 This manual also describes some of the machine-dependent features of
407 various flavors of the assembler.
410 This manual also describes how the assembler works internally, and
411 provides some information that may be useful to people attempting to
412 port the assembler to another machine.
416 @cindex machine instructions (not covered)
417 On the other hand, this manual is @emph{not} intended as an introduction
418 to programming in assembly language---let alone programming in general!
419 In a similar vein, we make no attempt to introduce the machine
420 architecture; we do @emph{not} describe the instruction set, standard
421 mnemonics, registers or addressing modes that are standard to a
422 particular architecture.
424 You may want to consult the manufacturer's
425 machine architecture manual for this information.
429 For information on the H8/300 machine instruction set, see @cite{H8/300
430 Series Programming Manual} (Hitachi ADE--602--025).
433 For information on the Z8000 machine instruction set, see @cite{Z8000
434 CPU Technical Manual}.
439 @c I think this is premature---pesch@cygnus.com, 17jan1991
441 Throughout this manual, we assume that you are running @dfn{GNU},
442 the portable operating system from the @dfn{Free Software
443 Foundation, Inc.}. This restricts our attention to certain kinds of
444 computer (in particular, the kinds of computers that GNU can run on);
445 once this assumption is granted examples and definitions need less
448 @code{@value{as}} is part of a team of programs that turn a high-level
449 human-readable series of instructions into a low-level
450 computer-readable series of instructions. Different versions of
451 @code{@value{as}} are used for different kinds of computer.
454 @c There used to be a section "Terminology" here, which defined
455 @c "contents", "byte", "word", and "long". Defining "word" to any
456 @c particular size is confusing when the .word directive may generate 16
457 @c bits on one machine and 32 bits on another; in general, for the user
458 @c version of this manual, none of these terms seem essential to define.
459 @c They were used very little even in the former draft of the manual;
460 @c this draft makes an effort to avoid them (except in names of
464 @section @value{as}, the GNU Assembler
466 GNU @code{as} is really a family of assemblers.
468 This manual describes @code{@value{as}}, a member of that family which is
469 configured for the @value{host} architectures.
471 If you use (or have used) the GNU assembler on one architecture, you
472 should find a fairly similar environment when you use it on another
473 architecture. Each version has much in common with the others,
474 including object file formats, most assembler directives (often called
475 @dfn{pseudo-ops}) and assembler syntax.@refill
478 @cindex purpose of @sc{gnu} @code{@value{as}}
479 @code{@value{as}} is primarily intended to assemble the output of the GNU C
480 compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless,
481 we've tried to make @code{@value{as}} assemble correctly everything that
486 Any exceptions are documented explicitly (@pxref{_MACH_DEP__}).
488 @ifset generic-or-m68k
489 This doesn't mean @code{@value{as}} always uses the same syntax as another
490 assembler for the same architecture; for example, we know of several
491 incompatible versions of 680x0 assembly language syntax.
494 Unlike older assemblers, @code{@value{as}} is designed to assemble a source
495 program in one pass of the source file. This has a subtle impact on the
496 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
499 @section Object File Formats
501 @cindex object file format
502 The GNU assembler can be configured to produce several alternative
503 object file formats. For the most part, this does not affect how you
504 write assembly language programs; but directives for debugging symbols
505 are typically different in different file formats. @xref{Symbol
506 Attributes,,Symbol Attributes}.
508 _if__(!(_I960__||_A29K__))
509 _if__(_AOUT__ && (!_COFF__) && (!_ELF__))
510 On the @value{host}, @code{@value{as}} is configured to produce @code{a.out}
513 _fi__(_AOUT__ && (!_COFF__) && (!_ELF__))
514 _if__((!_AOUT__) && _COFF__ && (!_ELF__))
515 On the @value{host}, @code{@value{as}} is configured to produce COFF format object
517 _fi__((!_AOUT__) && _COFF__ && (!_ELF__))
518 _fi__(!(_I960__||_A29K__))
520 On the @value{host}, @code{@value{as}} can be configured to produce either
521 @code{a.out} or COFF format object files.
524 On the @value{host}, @code{@value{as}} can be configured to produce either
531 @section Command Line
533 @cindex command line conventions
534 After the program name @code{@value{as}}, the command line may contain
535 options and file names. Options may appear in any order, and may be
536 before, after, or between file names. The order of file names is
539 @cindex standard input, as input file
541 @file{--} (two hyphens) by itself names the standard input file
542 explicitly, as one of the files for @code{@value{as}} to assemble.
544 @cindex options, command line
545 Except for @samp{--} any command line argument that begins with a
546 hyphen (@samp{-}) is an option. Each option changes the behavior of
547 @code{@value{as}}. No option changes the way another option works. An
548 option is a @samp{-} followed by one or more letters; the case of
549 the letter is important. All options are optional.
551 Some options expect exactly one file name to follow them. The file
552 name may either immediately follow the option's letter (compatible
553 with older assemblers) or it may be the next command argument (GNU
554 standard). These two command lines are equivalent:
557 @value{as} -o my-object-file.o mumble.s
558 @value{as} -omy-object-file.o mumble.s
565 @cindex source program
567 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
568 describe the program input to one run of @code{@value{as}}. The program may
569 be in one or more files; how the source is partitioned into files
570 doesn't change the meaning of the source.
572 @c I added "con" prefix to "catenation" just to prove I can overcome my
573 @c APL training... pesch@cygnus.com
574 The source program is a concatenation of the text in all the files, in the
577 Each time you run @code{@value{as}} it assembles exactly one source
578 program. The source program is made up of one or more files.
579 (The standard input is also a file.)
581 You give @code{@value{as}} a command line that has zero or more input file
582 names. The input files are read (from left file name to right). A
583 command line argument (in any position) that has no special meaning
584 is taken to be an input file name.
586 If you give @code{@value{as}} no file names it attempts to read one input file
587 from the @code{@value{as}} standard input, which is normally your terminal. You
588 may have to type @key{ctl-D} to tell @code{@value{as}} there is no more program
591 Use @samp{--} if you need to explicitly name the standard input file
592 in your command line.
594 If the source is empty, @code{@value{as}} will produce a small, empty object
597 @subheading Filenames and Line-numbers
599 @cindex input file linenumbers
600 @cindex line numbers, in input files
601 There are two ways of locating a line in the input file (or files) and
602 either may be used in reporting error messages. One way refers to a line
603 number in a physical file; the other refers to a line number in a
604 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
606 @dfn{Physical files} are those files named in the command line given
607 to @code{@value{as}}.
609 @dfn{Logical files} are simply names declared explicitly by assembler
610 directives; they bear no relation to physical files. Logical file names
611 help error messages reflect the original source file, when @code{@value{as}}
612 source is itself synthesized from other files.
613 @xref{Appfile,,@code{.appfile}}.
616 @section Output (Object) File
622 Every time you run @code{@value{as}} it produces an output file, which is
623 your assembly language program translated into numbers. This file
624 is the object file, named
628 if @code{@value{as}} is configured for the Intel 80960, or
634 unless you tell @code{@value{as}} to
635 give it another name by using the @code{-o} option. Conventionally,
636 object file names end with @file{.o}. The default name of
637 @file{a.out} is used for historical reasons: older assemblers were
638 capable of assembling self-contained programs directly into a
640 (For some formats, this isn't currently possible, but it can be done for
641 @code{a.out} format.)
645 The object file is meant for input to the linker @code{_LD__}. It contains
646 assembled program code, information to help @code{_LD__} integrate
647 the assembled program into a runnable file, and (optionally) symbolic
648 information for the debugger.
650 @c link above to some info file(s) like the description of a.out.
651 @c don't forget to describe GNU info as well as Unix lossage.
654 @section Error and Warning Messages
656 @cindex error messsages
657 @cindex warning messages
658 @cindex messages from @code{@value{as}}
659 @code{@value{as}} may write warnings and error messages to the standard error
660 file (usually your terminal). This should not happen when a compiler
661 runs @code{@value{as}} automatically. Warnings report an assumption made so
662 that @code{@value{as}} could keep assembling a flawed program; errors report a
663 grave problem that stops the assembly.
665 @cindex format of warning messages
666 Warning messages have the format
669 file_name:@b{NNN}:Warning Message Text
673 @cindex line numbers, in warnings/errors
674 (where @b{NNN} is a line number). If a logical file name has
675 been given (@pxref{Appfile,,@code{.appfile}}) it is used for the
676 filename, otherwise the
677 name of the current input file is used. If a logical line number was
680 (@pxref{Line,,@code{.line}})
683 (@pxref{Ln,,@code{.ln}})
685 then it is used to calculate the number printed,
686 otherwise the actual line in the current source file is printed. The
687 message text is intended to be self explanatory (in the grand Unix
690 @cindex format of error messages
691 Error messages have the format
693 file_name:@b{NNN}:FATAL:Error Message Text
695 The file name and line number are derived as for warning
696 messages. The actual message text may be rather less explanatory
697 because many of them aren't supposed to happen.
700 @chapter Command-Line Options
702 @cindex options, all versions of @code{@value{as}}
703 This chapter describes command-line options available in @emph{all}
704 versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific
709 to particular machine architectures.
712 If you are invoking @code{@value{as}} via the GNU C compiler (version 2), you
713 can use the @samp{-Wa} option to pass arguments through to the
714 assembler. The assembler arguments must be separated from each other
715 (and the @samp{-Wa}) by commas. For example:
718 gcc -c -g -O -Wa,-alh,-L file.c
721 will cause a listing to be emitted to standard output with high-level
724 Many compiler command-line options, such as @samp{-R} and many
725 machine-specific options, will be automatically be passed to the
726 assembler by the compiler, so usually you do not need to use this
727 @samp{-Wa} mechanism.
729 @section Enable Listings: @code{-a[dhlns]}
737 @cindex listings, enabling
738 @cindex assembly listings, enabling
740 These options enable listing output from the assembler. By itself,
741 @samp{-a} requests high-level, assembly, and symbols listing.
742 Other letters may be used to select specific options for the list:
743 @samp{-ah} requests a high-level language listing,
744 @samp{-al} requests an output-program assembly listing, and
745 @samp{-as} requests a symbol table listing.
746 High-level listings require that a compiler debugging option like
747 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
750 The @samp{-ad} option may be used to omit debugging pseudo-ops from the
753 Once you have specified one of these options, you can further control
754 listing output and its appearance using the directives @code{.list},
755 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
757 The @samp{-an} option turns off all forms processing.
758 If you do not request listing output with one of the @samp{-a} options, the
759 listing-control directives have no effect.
761 The letters after @samp{-a} may be combined into one option,
762 @emph{e.g.}, @samp{-aln}.
767 This option has no effect whatsoever, but it is accepted to make it more
768 likely that scripts written for other assemblers will also work with
771 @section Work Faster: @code{-f}
774 @cindex trusted compiler
775 @cindex faster processing (@code{-f})
776 @samp{-f} should only be used when assembling programs written by a
777 (trusted) compiler. @samp{-f} stops the assembler from pre-processing
778 the input file(s) before assembling them. @xref{Pre-processing,
782 @emph{Warning:} if the files actually need to be pre-processed (if they
783 contain comments, for example), @code{@value{as}} will not work correctly if
787 @section @code{.include} search path: @code{-I} @var{path}
789 @kindex -I @var{path}
790 @cindex paths for @code{.include}
791 @cindex search path for @code{.include}
792 @cindex @code{include} directive search path
793 Use this option to add a @var{path} to the list of directories
794 @code{@value{as}} will search for files specified in @code{.include}
795 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
796 many times as necessary to include a variety of paths. The current
797 working directory is always searched first; after that, @code{@value{as}}
798 searches any @samp{-I} directories in the same order as they were
799 specified (left to right) on the command line.
801 @section Difference Tables: @code{-K}
804 _if__((!_GENERIC__) && (!_DIFFTABKLUG__))
805 On the @value{host} family, this option is allowed, but has no effect. It is
806 permitted for compatibility with the GNU assembler on other platforms,
807 where it can be used to warn when the assembler alters the machine code
808 generated for @samp{.word} directives in difference tables. The @value{host}
809 family does not have the addressing limitations that sometimes lead to this
810 alteration on other platforms.
811 _fi__((!_GENERIC__) && (!_DIFFTABKLUG__))
813 _if__(_GENERIC__ || _DIFFTABKLUG__ )
814 @cindex difference tables, warning
815 @cindex warning for altered difference tables
816 @code{@value{as}} sometimes alters the code emitted for directives of the form
817 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
818 You can use the @samp{-K} option if you want a warning issued when this
820 _fi__(_GENERIC__ || _DIFFTABKLUG__ )
822 @section Include Local Labels: @code{-L}
825 @cindex local labels, retaining in output
826 Labels beginning with @samp{L} (upper case only) are called @dfn{local
827 labels}. @xref{Symbol Names}. Normally you don't see such labels when
828 debugging, because they are intended for the use of programs (like
829 compilers) that compose assembler programs, not for your notice.
830 Normally both @code{@value{as}} and @code{_LD__} discard such labels, so you don't
831 normally debug with them.
833 This option tells @code{@value{as}} to retain those @samp{L@dots{}} symbols
834 in the object file. Usually if you do this you also tell the linker
835 @code{_LD__} to preserve symbols whose names begin with @samp{L}.
837 @section Name the Object File: @code{-o}
840 @cindex naming object file
841 @cindex object file name
842 There is always one object file output when you run @code{@value{as}}. By
843 default it has the name
846 @file{a.out} or @file{b.out}, depending on the target for which
847 @code{@value{as}} is configured.
861 You use this option (which
862 takes exactly one filename) to give the object file a different name.
864 Whatever the object file is called, @code{@value{as}} will overwrite any
865 existing file of the same name.
867 @section Join Data and Text Sections: @code{-R}
870 @cindex data and text sections, joining
871 @cindex text and data sections, joining
872 @cindex joining text and data sections
873 @cindex merging text and data sections
874 @code{-R} tells @code{@value{as}} to write the object file as if all
875 data-section data lives in the text section. This is only done at
876 the very last moment: your binary data are the same, but data
877 section parts are relocated differently. The data section part of
878 your object file is zero bytes long because all its bytes are
879 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
881 When you specify @code{-R} it would be possible to generate shorter
882 address displacements (because we don't have to cross between text and
883 data section). We refrain from doing this simply for compatibility with
884 older versions of @code{@value{as}}. In future, @code{-R} may work this way.
887 When @code{@value{as}} is configured for COFF output,
888 this option is only useful if you use sections named @samp{.text} and
892 @section Announce Version: @code{-v}
896 @cindex @code{@value{as}} version
897 @cindex version of @code{@value{as}}
898 You can find out what version of as is running by including the
899 option @samp{-v} (which you can also spell as @samp{-version}) on the
902 @section Suppress Warnings: @code{-W}
905 @cindex suppressing warnings
906 @cindex warnings, suppressing
907 @code{@value{as}} should never give a warning or error message when
908 assembling compiler output. But programs written by people often
909 cause @code{@value{as}} to give a warning that a particular assumption was
910 made. All such warnings are directed to the standard error file.
911 If you use this option, no warnings are issued. This option only
912 affects the warning messages: it does not change any particular of how
913 @code{@value{as}} assembles your file. Errors, which stop the assembly, are
919 @cindex machine-independent syntax
920 @cindex syntax, machine-independent
921 This chapter describes the machine-independent syntax allowed in a
922 source file. @code{@value{as}} syntax is similar to what many other assemblers
923 use; it is inspired by the BSD 4.2
928 assembler, except that @code{@value{as}} does not assemble Vax bit-fields.
932 * Pre-processing:: Pre-processing
933 * Whitespace:: Whitespace
934 * Comments:: Comments
935 * Symbol Intro:: Symbols
936 * Statements:: Statements
937 * Constants:: Constants
941 @section Pre-Processing
943 @cindex preprocessing
946 @cindex whitespace, removed by preprocessor
948 adjusts and removes extra whitespace. It leaves one space or tab before
949 the keywords on a line, and turns any other whitespace on the line into
952 @cindex comments, removed by preprocessor
954 removes all comments, replacing them with a single space, or an
955 appropriate number of newlines.
957 @cindex constants, converted by preprocessor
959 converts character constants into the appropriate numeric values.
962 Excess whitespace, comments, and character constants
963 cannot be used in the portions of the input text that are not
966 @cindex turning preprocessing on and off
967 @cindex preprocessing, turning on and off
970 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
971 option is given, the input file will not be pre-processed. Within such
972 an input file, parts of the file can be pre-processed by putting a line
973 that says @code{#APP} before the text that should be pre-processed, and
974 putting a line that says @code{#NO_APP} after them. This feature is
975 mainly intend to support @code{asm} statements in compilers whose output
976 normally does not need to be pre-processed.
982 @dfn{Whitespace} is one or more blanks or tabs, in any order.
983 Whitespace is used to separate symbols, and to make programs neater for
984 people to read. Unless within character constants
985 (@pxref{Characters,,Character Constants}), any whitespace means the same
986 as exactly one space.
992 There are two ways of rendering comments to @code{@value{as}}. In both
993 cases the comment is equivalent to one space.
995 Anything from @samp{/*} through the next @samp{*/} is a comment.
996 This means you may not nest these comments.
1000 The only way to include a newline ('\n') in a comment
1001 is to use this sort of comment.
1004 /* This sort of comment does not nest. */
1007 @cindex line comment character
1008 Anything from the @dfn{line comment} character to the next newline
1009 is considered a comment and is ignored. The line comment character is
1011 @samp{#} on the Vax;
1014 @samp{#} on the i960;
1017 @samp{!} on the SPARC;
1020 @samp{|} on the 680x0;
1023 @samp{;} for the AMD 29K family;
1026 @samp{;} for the H8/300 family;
1029 @samp{!} for the Z8000;
1031 see @ref{_MACH_DEP__}. @refill
1032 @c FIXME What about i386, m88k, i860?
1035 On some machines there are two different line comment characters. One
1036 will only begin a comment if it is the first non-whitespace character on
1037 a line, while the other will always begin a comment.
1041 @cindex lines starting with @code{#}
1042 @cindex logical line numbers
1043 To be compatible with past assemblers, a special interpretation is
1044 given to lines that begin with @samp{#}. Following the @samp{#} an
1045 absolute expression (@pxref{Expressions}) is expected: this will be
1046 the logical line number of the @b{next} line. Then a string
1047 (@xref{Strings}.) is allowed: if present it is a new logical file
1048 name. The rest of the line, if any, should be whitespace.
1050 If the first non-whitespace characters on the line are not numeric,
1051 the line is ignored. (Just like a comment.)
1053 # This is an ordinary comment.
1054 # 42-6 "new_file_name" # New logical file name
1055 # This is logical line # 36.
1057 This feature is deprecated, and may disappear from future versions
1058 of @code{@value{as}}.
1063 @cindex characters used in symbols
1064 A @dfn{symbol} is one or more characters chosen from the set of all
1065 letters (both upper and lower case), digits and
1067 the three characters @samp{_.$}
1070 the two characters @samp{_.}
1072 On most machines, you can also use @code{$} in symbol names; exceptions
1073 are noted in @ref{_MACH_DEP__}.
1076 No symbol may begin with a digit. Case is significant.
1077 There is no length limit: all characters are significant. Symbols are
1078 delimited by characters not in that set, or by the beginning of a file
1079 (since the source program must end with a newline, the end of a file is
1080 not a possible symbol delimiter). @xref{Symbols}.
1081 @cindex length of symbols
1086 @cindex statements, structure of
1087 @cindex line separator character
1088 @cindex statement separator character
1090 _if__(!(_A29K__||_H8__))
1091 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
1092 semicolon (@samp{;}). The newline or semicolon is considered part of
1093 the preceding statement. Newlines and semicolons within character
1094 constants are an exception: they don't end statements.
1095 _fi__(!(_A29K__||_H8__))
1097 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
1098 sign (@samp{@@}). The newline or at sign is considered part of the
1099 preceding statement. Newlines and at signs within character constants
1100 are an exception: they don't end statements.
1103 A @dfn{statement} ends at a newline character (@samp{\n}) or a dollar
1104 sign (@samp{$}). The newline or dollar sign is considered part of the
1105 preceding statement. Newlines and dollar signs within character constants
1106 are an exception: they don't end statements.
1110 A @dfn{statement} ends at a newline character (@samp{\n}) or line
1111 separator character. (The line separator is usually @samp{;}, unless
1112 this conflicts with the comment character; @pxref{_MACH_DEP__}.) The
1113 newline or separator character is considered part of the preceding
1114 statement. Newlines and separators within character constants are an
1115 exception: they don't end statements.
1118 @cindex newline, required at file end
1119 @cindex EOF, newline must precede
1120 It is an error to end any statement with end-of-file: the last
1121 character of any input file should be a newline.@refill
1123 @cindex continuing statements
1124 @cindex multi-line statements
1125 @cindex statement on multiple lines
1126 You may write a statement on more than one line if you put a
1127 backslash (@kbd{\}) immediately in front of any newlines within the
1128 statement. When @code{@value{as}} reads a backslashed newline both
1129 characters are ignored. You can even put backslashed newlines in
1130 the middle of symbol names without changing the meaning of your
1133 An empty statement is allowed, and may include whitespace. It is ignored.
1135 @cindex instructions and directives
1136 @cindex directives and instructions
1137 @c "key symbol" is not used elsewhere in the document; seems pedantic to
1138 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
1140 A statement begins with zero or more labels, optionally followed by a
1141 key symbol which determines what kind of statement it is. The key
1142 symbol determines the syntax of the rest of the statement. If the
1143 symbol begins with a dot @samp{.} then the statement is an assembler
1144 directive: typically valid for any computer. If the symbol begins with
1145 a letter the statement is an assembly language @dfn{instruction}: it
1146 will assemble into a machine language instruction.
1148 Different versions of @code{@value{as}} for different computers will
1149 recognize different instructions. In fact, the same symbol may
1150 represent a different instruction in a different computer's assembly
1154 @cindex @code{:} (label)
1155 @cindex label (@code{:})
1156 A label is a symbol immediately followed by a colon (@code{:}).
1157 Whitespace before a label or after a colon is permitted, but you may not
1158 have whitespace between a label's symbol and its colon. @xref{Labels}.
1161 label: .directive followed by something
1162 another_label: # This is an empty statement.
1163 instruction operand_1, operand_2, @dots{}
1170 A constant is a number, written so that its value is known by
1171 inspection, without knowing any context. Like this:
1173 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
1174 .ascii "Ring the bell\7" # A string constant.
1175 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
1176 .float 0f-314159265358979323846264338327\
1177 95028841971.693993751E-40 # - pi, a flonum.
1181 * Characters:: Character Constants
1182 * Numbers:: Number Constants
1186 @subsection Character Constants
1188 @cindex character constants
1189 @cindex constants, character
1190 There are two kinds of character constants. A @dfn{character} stands
1191 for one character in one byte and its value may be used in
1192 numeric expressions. String constants (properly called string
1193 @emph{literals}) are potentially many bytes and their values may not be
1194 used in arithmetic expressions.
1198 * Chars:: Characters
1202 @subsubsection Strings
1204 @cindex string constants
1205 @cindex constants, string
1206 A @dfn{string} is written between double-quotes. It may contain
1207 double-quotes or null characters. The way to get special characters
1208 into a string is to @dfn{escape} these characters: precede them with
1209 a backslash @samp{\} character. For example @samp{\\} represents
1210 one backslash: the first @code{\} is an escape which tells
1211 @code{@value{as}} to interpret the second character literally as a backslash
1212 (which prevents @code{@value{as}} from recognizing the second @code{\} as an
1213 escape character). The complete list of escapes follows.
1215 @cindex escape codes, character
1216 @cindex character escape codes
1219 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1222 @cindex @code{\b} (backspace character)
1223 @cindex backspace (@code{\b})
1224 Mnemonic for backspace; for ASCII this is octal code 010.
1227 @c Mnemonic for EOText; for ASCII this is octal code 004.
1230 @cindex @code{\f} (formfeed character)
1231 @cindex formfeed (@code{\f})
1232 Mnemonic for FormFeed; for ASCII this is octal code 014.
1235 @cindex @code{\n} (newline character)
1236 @cindex newline (@code{\n})
1237 Mnemonic for newline; for ASCII this is octal code 012.
1240 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1243 @cindex @code{\r} (carriage return character)
1244 @cindex carriage return (@code{\r})
1245 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1248 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1249 @c other assemblers.
1252 @cindex @code{\t} (tab)
1253 @cindex tab (@code{\t})
1254 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1257 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1258 @c @item \x @var{digit} @var{digit} @var{digit}
1259 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1261 @item \ @var{digit} @var{digit} @var{digit}
1262 @cindex @code{\@var{ddd}} (octal character code)
1263 @cindex octal character code (@code{\@var{ddd}})
1264 An octal character code. The numeric code is 3 octal digits.
1265 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1266 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1269 @cindex @code{\\} (@samp{\} character)
1270 @cindex backslash (@code{\\})
1271 Represents one @samp{\} character.
1274 @c Represents one @samp{'} (accent acute) character.
1275 @c This is needed in single character literals
1276 @c (@xref{Characters,,Character Constants}.) to represent
1280 @cindex @code{\"} (doublequote character)
1281 @cindex doublequote (@code{\"})
1282 Represents one @samp{"} character. Needed in strings to represent
1283 this character, because an unescaped @samp{"} would end the string.
1285 @item \ @var{anything-else}
1286 Any other character when escaped by @kbd{\} will give a warning, but
1287 assemble as if the @samp{\} was not present. The idea is that if
1288 you used an escape sequence you clearly didn't want the literal
1289 interpretation of the following character. However @code{@value{as}} has no
1290 other interpretation, so @code{@value{as}} knows it is giving you the wrong
1291 code and warns you of the fact.
1294 Which characters are escapable, and what those escapes represent,
1295 varies widely among assemblers. The current set is what we think
1296 the BSD 4.2 assembler recognizes, and is a subset of what most C
1297 compilers recognize. If you are in doubt, don't use an escape
1301 @subsubsection Characters
1303 @cindex single character constant
1304 @cindex character, single
1305 @cindex constant, single character
1306 A single character may be written as a single quote immediately
1307 followed by that character. The same escapes apply to characters as
1308 to strings. So if you want to write the character backslash, you
1309 must write @kbd{'\\} where the first @code{\} escapes the second
1310 @code{\}. As you can see, the quote is an acute accent, not a
1311 grave accent. A newline
1313 _if__(!(_A29K__||_H8__))
1314 (or semicolon @samp{;})
1315 _fi__(!(_A29K__||_H8__))
1317 (or at sign @samp{@@})
1320 (or dollar sign @samp{$})
1323 immediately following an acute accent is taken as a literal character
1324 and does not count as the end of a statement. The value of a character
1325 constant in a numeric expression is the machine's byte-wide code for
1326 that character. @code{@value{as}} assumes your character code is ASCII:
1327 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1330 @subsection Number Constants
1332 @cindex constants, number
1333 @cindex number constants
1334 @code{@value{as}} distinguishes three kinds of numbers according to how they
1335 are stored in the target machine. @emph{Integers} are numbers that
1336 would fit into an @code{int} in the C language. @emph{Bignums} are
1337 integers, but they are stored in more than 32 bits. @emph{Flonums}
1338 are floating point numbers, described below.
1341 * Integers:: Integers
1344 _if__(_I960__&&!_GENERIC__)
1345 * Bit Fields:: Bit Fields
1346 _fi__(_I960__&&!_GENERIC__)
1350 @subsubsection Integers
1352 @cindex constants, integer
1354 @cindex binary integers
1355 @cindex integers, binary
1356 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1357 the binary digits @samp{01}.
1359 @cindex octal integers
1360 @cindex integers, octal
1361 An octal integer is @samp{0} followed by zero or more of the octal
1362 digits (@samp{01234567}).
1364 @cindex decimal integers
1365 @cindex integers, decimal
1366 A decimal integer starts with a non-zero digit followed by zero or
1367 more digits (@samp{0123456789}).
1369 @cindex hexadecimal integers
1370 @cindex integers, hexadecimal
1371 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1372 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1374 Integers have the usual values. To denote a negative integer, use
1375 the prefix operator @samp{-} discussed under expressions
1376 (@pxref{Prefix Ops,,Prefix Operators}).
1379 @subsubsection Bignums
1382 @cindex constants, bignum
1383 A @dfn{bignum} has the same syntax and semantics as an integer
1384 except that the number (or its negative) takes more than 32 bits to
1385 represent in binary. The distinction is made because in some places
1386 integers are permitted while bignums are not.
1389 @subsubsection Flonums
1391 @cindex floating point numbers
1392 @cindex constants, floating point
1394 @cindex precision, floating point
1395 A @dfn{flonum} represents a floating point number. The translation is
1396 indirect: a decimal floating point number from the text is converted by
1397 @code{@value{as}} to a generic binary floating point number of more than
1398 sufficient precision. This generic floating point number is converted
1399 to a particular computer's floating point format (or formats) by a
1400 portion of @code{@value{as}} specialized to that computer.
1402 A flonum is written by writing (in order)
1407 A letter, to tell @code{@value{as}} the rest of the number is a flonum.
1409 @kbd{e} is recommended. Case is not important.
1411 @c FIXME: verify if flonum syntax really this vague for most cases
1412 (Any otherwise illegal letter
1413 will work here, but that might be changed. Vax BSD 4.2 assembler seems
1414 to allow any of @samp{defghDEFGH}.)
1417 _if__(_A29K__||_H8__)
1419 On the AMD 29K and H8/300 architectures, the letter must be:
1421 One of the letters @samp{DFPRSX} (in upper or lower case).
1422 _fi__(_A29K__||_H8__)
1425 On the Intel 960 architecture, the letter must be:
1427 One of the letters @samp{DFT} (in upper or lower case).
1430 An optional sign: either @samp{+} or @samp{-}.
1432 An optional @dfn{integer part}: zero or more decimal digits.
1434 An optional @dfn{fractional part}: @samp{.} followed by zero
1435 or more decimal digits.
1437 An optional exponent, consisting of:
1440 An @samp{E} or @samp{e}.
1441 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1442 @c principle this can perfectly well be different on different targets.
1444 Optional sign: either @samp{+} or @samp{-}.
1446 One or more decimal digits.
1450 At least one of the integer part or the fractional part must be
1451 present. The floating point number has the usual base-10 value.
1453 @code{@value{as}} does all processing using integers. Flonums are computed
1454 independently of any floating point hardware in the computer running
1457 _if__(_I960__&&!_GENERIC__)
1458 @c Bit fields are written as a general facility but are also controlled
1459 @c by a conditional-compilation flag---which is as of now (21mar91)
1460 @c turned on only by the i960 config of GAS.
1462 @subsubsection Bit Fields
1465 @cindex constants, bit field
1466 You can also define numeric constants as @dfn{bit fields}.
1467 specify two numbers separated by a colon---
1469 @var{mask}:@var{value}
1472 the first will act as a mask; @code{@value{as}} will bitwise-and it with the
1475 The resulting number is then packed
1477 @c this conditional paren in case bit fields turned on elsewhere than 960
1478 (in host-dependent byte order)
1480 into a field whose width depends on which assembler directive has the
1481 bit-field as its argument. Overflow (a result from the bitwise and
1482 requiring more binary digits to represent) is not an error; instead,
1483 more constants are generated, of the specified width, beginning with the
1484 least significant digits.@refill
1486 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1487 @code{.short}, and @code{.word} accept bit-field arguments.
1488 _fi__(_I960__&&!_GENERIC__)
1491 @chapter Sections and Relocation
1496 * Secs Background:: Background
1497 * _LD__ Sections:: _LD__ Sections
1498 * @value{as} Sections:: @value{as} Internal Sections
1499 * Sub-Sections:: Sub-Sections
1503 @node Secs Background
1506 Roughly, a section is a range of addresses, with no gaps; all data
1507 ``in'' those addresses is treated the same for some particular purpose.
1508 For example there may be a ``read only'' section.
1510 @cindex linker, and assembler
1511 @cindex assembler, and linker
1512 The linker @code{_LD__} reads many object files (partial programs) and
1513 combines their contents to form a runnable program. When @code{@value{as}}
1514 emits an object file, the partial program is assumed to start at address
1515 0. @code{_LD__} will assign the final addresses the partial program
1516 occupies, so that different partial programs don't overlap. This is
1517 actually an over-simplification, but it will suffice to explain how
1518 @code{@value{as}} uses sections.
1520 @code{_LD__} moves blocks of bytes of your program to their run-time
1521 addresses. These blocks slide to their run-time addresses as rigid
1522 units; their length does not change and neither does the order of bytes
1523 within them. Such a rigid unit is called a @emph{section}. Assigning
1524 run-time addresses to sections is called @dfn{relocation}. It includes
1525 the task of adjusting mentions of object-file addresses so they refer to
1526 the proper run-time addresses.
1528 For the H8/300, @code{@value{as}} pads sections if needed to ensure they end
1529 on a word (sixteen bit) boundary.
1532 @cindex standard @code{@value{as}} sections
1533 An object file written by @code{@value{as}} has at least three sections, any
1534 of which may be empty. These are named @dfn{text}, @dfn{data} and
1539 When it generates COFF output,
1541 @code{@value{as}} can also generate whatever other named sections you specify
1542 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1543 If you don't use any directives that place output in the @samp{.text}
1544 or @samp{.data} sections, these sections will still exist, but will be empty.
1547 Within the object file, the text section starts at address @code{0}, the
1548 data section follows, and the bss section follows the data section.
1550 To let @code{_LD__} know which data will change when the sections are
1551 relocated, and how to change that data, @code{@value{as}} also writes to the
1552 object file details of the relocation needed. To perform relocation
1553 @code{_LD__} must know, each time an address in the object
1557 Where in the object file is the beginning of this reference to
1560 How long (in bytes) is this reference?
1562 Which section does the address refer to? What is the numeric value of
1564 (@var{address}) @minus{} (@var{start-address of section})?
1567 Is the reference to an address ``Program-Counter relative''?
1570 @cindex addresses, format of
1571 @cindex section-relative addressing
1572 In fact, every address @code{@value{as}} ever uses is expressed as
1574 (@var{section}) + (@var{offset into section})
1577 Further, every expression @code{@value{as}} computes is of this section-relative
1578 nature. @dfn{Absolute expression} means an expression with section
1579 ``absolute'' (@pxref{_LD__ Sections}). A @dfn{pass1 expression} means
1580 an expression with section ``pass1'' (@pxref{@value{as} Sections,,@value{as}
1581 Internal Sections}). In this manual we use the notation @{@var{secname}
1582 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1584 Apart from text, data and bss sections you need to know about the
1585 @dfn{absolute} section. When @code{_LD__} mixes partial programs,
1586 addresses in the absolute section remain unchanged. For example, address
1587 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}.
1588 Although two partial programs' data sections will not overlap addresses
1589 after linking, @emph{by definition} their absolute sections will overlap.
1590 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1591 address when the program is running as address @code{@{absolute@ 239@}} in any
1592 other partial program.
1594 The idea of sections is extended to the @dfn{undefined} section. Any
1595 address whose section is unknown at assembly time is by definition
1596 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1597 Since numbers are always defined, the only way to generate an undefined
1598 address is to mention an undefined symbol. A reference to a named
1599 common block would be such a symbol: its value is unknown at assembly
1600 time so it has section @emph{undefined}.
1602 By analogy the word @emph{section} is used to describe groups of sections in
1603 the linked program. @code{_LD__} puts all partial programs' text
1604 sections in contiguous addresses in the linked program. It is
1605 customary to refer to the @emph{text section} of a program, meaning all
1606 the addresses of all partial program's text sections. Likewise for
1607 data and bss sections.
1609 Some sections are manipulated by @code{_LD__}; others are invented for
1610 use of @code{@value{as}} and have no meaning except during assembly.
1612 @node _LD__ Sections
1613 @section _LD__ Sections
1614 @code{_LD__} deals with just four kinds of sections, summarized below.
1618 _if__(_GENERIC__||_COFF__)
1619 @cindex named sections
1620 @cindex sections, named
1621 @item named sections
1622 _fi__(_GENERIC__||_COFF__)
1623 _if__(_AOUT__||_BOUT__)
1624 @cindex text section
1625 @cindex data section
1628 _fi__(_AOUT__||_BOUT__)
1629 These sections hold your program. @code{@value{as}} and @code{_LD__} treat them as
1630 separate but equal sections. Anything you can say of one section is
1632 _if__(_AOUT__||_BOUT__)
1633 When the program is running, however, it is
1634 customary for the text section to be unalterable. The
1635 text section is often shared among processes: it will contain
1636 instructions, constants and the like. The data section of a running
1637 program is usually alterable: for example, C variables would be stored
1638 in the data section.
1639 _fi__(_AOUT__||_BOUT__)
1643 This section contains zeroed bytes when your program begins running. It
1644 is used to hold unitialized variables or common storage. The length of
1645 each partial program's bss section is important, but because it starts
1646 out containing zeroed bytes there is no need to store explicit zero
1647 bytes in the object file. The bss section was invented to eliminate
1648 those explicit zeros from object files.
1650 @cindex absolute section
1651 @item absolute section
1652 Address 0 of this section is always ``relocated'' to runtime address 0.
1653 This is useful if you want to refer to an address that @code{_LD__} must
1654 not change when relocating. In this sense we speak of absolute
1655 addresses being ``unrelocatable'': they don't change during relocation.
1657 @cindex undefined section
1658 @item undefined section
1659 This ``section'' is a catch-all for address references to objects not in
1660 the preceding sections.
1661 @c FIXME: ref to some other doc on obj-file formats could go here.
1664 @cindex relocation example
1665 An idealized example of three relocatable sections follows.
1667 The example uses the traditional section names @samp{.text} and @samp{.data}.
1669 Memory addresses are on the horizontal axis.
1673 @c END TEXI2ROFF-KILL
1676 partial program # 1: |ttttt|dddd|00|
1683 partial program # 2: |TTT|DDD|000|
1686 +--+---+-----+--+----+---+-----+~~
1687 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1688 +--+---+-----+--+----+---+-----+~~
1690 addresses: 0 @dots{}
1694 @c FIXME make sure no page breaks inside figure!!
1697 \line{\it Partial program \#1: \hfil}
1698 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1699 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1701 \line{\it Partial program \#2: \hfil}
1702 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1703 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1705 \line{\it linked program: \hfil}
1706 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1707 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1708 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1709 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1711 \line{\it addresses: \hfil}
1715 @c END TEXI2ROFF-KILL
1717 @node @value{as} Sections
1718 @section @value{as} Internal Sections
1720 @cindex internal @code{@value{as}} sections
1721 @cindex sections in messages, internal
1722 These sections are meant only for the internal use of @code{@value{as}}. They
1723 have no meaning at run-time. You don't really need to know about these
1724 sections for most purposes; but they can be mentioned in @code{@value{as}}
1725 warning messages, so it might be helpful to have an idea of their
1726 meanings to @code{@value{as}}. These sections are used to permit the
1727 value of every expression in your assembly language program to be a
1728 section-relative address.
1732 @cindex absent (internal section)
1733 An expression was expected and none was found.
1735 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1736 @cindex assembler internal logic error
1737 An internal assembler logic error has been found. This means there is a
1738 bug in the assembler.
1741 @cindex bignum/flonum (internal section)
1742 If a number can't be written as a C @code{int} constant (a bignum or a
1743 flonum, but not an integer), it is recorded as belonging to this
1744 ``section''. @code{@value{as}} has to remember that a flonum or a bignum
1745 does not fit into 32 bits, and cannot be an argument (@pxref{Arguments})
1746 in an expression: this is done by making a flonum or bignum be in a
1747 separate internal section. This is purely for internal @code{@value{as}}
1748 convenience; bignum/flonum section behaves similarly to absolute
1752 @cindex pass1 (internal section)
1753 The expression was impossible to evaluate in the first pass. The
1754 assembler will attempt a second pass (second reading of the source) to
1755 evaluate the expression. Your expression mentioned an undefined symbol
1756 in a way that defies the one-pass (section + offset in section) assembly
1757 process. No compiler need emit such an expression.
1760 @emph{Warning:} the second pass is currently not implemented. @code{@value{as}}
1761 will abort with an error message if one is required.
1764 @item difference section
1765 @cindex difference (internal section)
1766 As an assist to the C compiler, expressions of the forms
1768 (@var{undefined symbol}) @minus{} (@var{expression})
1769 @var{something} @minus{} (@var{undefined symbol})
1770 (@var{undefined symbol}) @minus{} (@var{undefined symbol})
1773 are permitted, and belong to the difference section. @code{@value{as}}
1774 re-evaluates such expressions after the source file has been read and
1775 the symbol table built. If by that time there are no undefined symbols
1776 in the expression then the expression assumes a new section. The
1777 intention is to permit statements like
1778 @samp{.word label - base_of_table}
1779 to be assembled in one pass where both @code{label} and
1780 @code{base_of_table} are undefined. This is useful for compiling C and
1781 Algol switch statements, Pascal case statements, FORTRAN computed goto
1782 statements and the like.
1784 @c FIXME item transfer[t] vector preload
1785 @c FIXME item transfer[t] vector postload
1786 @c FIXME item register
1790 @section Sub-Sections
1792 @cindex numbered subsections
1793 @cindex grouping data
1794 _if__(_AOUT__||_BOUT__)
1799 fall into two sections: text and data.
1800 _fi__(_AOUT__||_BOUT__)
1801 You may have separate groups of
1802 _if__(_COFF__||_GENERIC__)
1803 data in named sections
1804 _fi__(_COFF__||_GENERIC__)
1805 _if__((_AOUT__||_BOUT__)&&!_GENERIC__)
1807 _fi__((_AOUT__||_BOUT__)&&!_GENERIC__)
1808 that you want to end up near to each other in the object
1809 file, even though they are not contiguous in the assembler source.
1810 @code{@value{as}} allows you to use @dfn{subsections} for this purpose.
1811 Within each section, there can be numbered subsections with
1812 values from 0 to 8192. Objects assembled into the same subsection will
1813 be grouped with other objects in the same subsection when they are all
1814 put into the object file. For example, a compiler might want to store
1815 constants in the text section, but might not want to have them
1816 interspersed with the program being assembled. In this case, the
1817 compiler could issue a @samp{.text 0} before each section of code being
1818 output, and a @samp{.text 1} before each group of constants being output.
1820 Subsections are optional. If you don't use subsections, everything
1821 will be stored in subsection number zero.
1824 Each subsection is zero-padded up to a multiple of four bytes.
1825 (Subsections may be padded a different amount on different flavors
1826 of @code{@value{as}}.)
1830 On the H8/300 platform, each subsection is zero-padded to a word
1831 boundary (two bytes).
1834 @c FIXME section padding (alignment)?
1835 @c Rich Pixley says padding here depends on target obj code format; that
1836 @c doesn't seem particularly useful to say without further elaboration,
1837 @c so for now I say nothing about it. If this is a generic BFD issue,
1838 @c these paragraphs might need to vanish from this manual, and be
1839 @c discussed in BFD chapter of binutils (or some such).
1842 On the AMD 29K family, no particular padding is added to section or
1843 subsection sizes; @value{as} forces no alignment on this platform.
1847 Subsections appear in your object file in numeric order, lowest numbered
1848 to highest. (All this to be compatible with other people's assemblers.)
1849 The object file contains no representation of subsections; @code{_LD__} and
1850 other programs that manipulate object files will see no trace of them.
1851 They just see all your text subsections as a text section, and all your
1852 data subsections as a data section.
1854 To specify which subsection you want subsequent statements assembled
1855 into, use a numeric argument to specify it, in a @samp{.text
1856 @var{expression}} or a @samp{.data @var{expression}} statement.
1859 When generating COFF output, you
1864 can also use an extra subsection
1865 argument with arbitrary named sections: @samp{.section @var{name},
1868 @var{Expression} should be an absolute expression.
1869 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
1870 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
1871 begins in @code{text 0}. For instance:
1873 .text 0 # The default subsection is text 0 anyway.
1874 .ascii "This lives in the first text subsection. *"
1876 .ascii "But this lives in the second text subsection."
1878 .ascii "This lives in the data section,"
1879 .ascii "in the first data subsection."
1881 .ascii "This lives in the first text section,"
1882 .ascii "immediately following the asterisk (*)."
1885 Each section has a @dfn{location counter} incremented by one for every
1886 byte assembled into that section. Because subsections are merely a
1887 convenience restricted to @code{@value{as}} there is no concept of a subsection
1888 location counter. There is no way to directly manipulate a location
1889 counter---but the @code{.align} directive will change it, and any label
1890 definition will capture its current value. The location counter of the
1891 section that statements are being assembled into is said to be the
1892 @dfn{active} location counter.
1895 @section bss Section
1898 @cindex common variable storage
1899 The bss section is used for local common variable storage.
1900 You may allocate address space in the bss section, but you may
1901 not dictate data to load into it before your program executes. When
1902 your program starts running, all the contents of the bss
1903 section are zeroed bytes.
1905 Addresses in the bss section are allocated with special directives; you
1906 may not assemble anything directly into the bss section. Hence there
1907 are no bss subsections. @xref{Comm,,@code{.comm}},
1908 @pxref{Lcomm,,@code{.lcomm}}.
1914 Symbols are a central concept: the programmer uses symbols to name
1915 things, the linker uses symbols to link, and the debugger uses symbols
1919 @cindex debuggers, and symbol order
1920 @emph{Warning:} @code{@value{as}} does not place symbols in the object file in
1921 the same order they were declared. This may break some debuggers.
1926 * Setting Symbols:: Giving Symbols Other Values
1927 * Symbol Names:: Symbol Names
1928 * Dot:: The Special Dot Symbol
1929 * Symbol Attributes:: Symbol Attributes
1936 A @dfn{label} is written as a symbol immediately followed by a colon
1937 @samp{:}. The symbol then represents the current value of the
1938 active location counter, and is, for example, a suitable instruction
1939 operand. You are warned if you use the same symbol to represent two
1940 different locations: the first definition overrides any other
1943 @node Setting Symbols
1944 @section Giving Symbols Other Values
1946 @cindex assigning values to symbols
1947 @cindex symbol values, assigning
1948 A symbol can be given an arbitrary value by writing a symbol, followed
1949 by an equals sign @samp{=}, followed by an expression
1950 (@pxref{Expressions}). This is equivalent to using the @code{.set}
1951 directive. @xref{Set,,@code{.set}}.
1954 @section Symbol Names
1956 @cindex symbol names
1957 @cindex names, symbol
1958 Symbol names begin with a letter or with one of
1965 (On most machines, you can also use @code{$} in symbol names; exceptions
1966 are noted in @ref{_MACH_DEP__}.)
1969 That character may be followed by any string of digits, letters,
1971 underscores and dollar signs.
1975 dollar signs (unless otherwise noted in @ref{_MACH_DEP__}),
1979 Case of letters is significant:
1980 @code{foo} is a different symbol name than @code{Foo}.
1983 For the AMD 29K family, @samp{?} is also allowed in the
1984 body of a symbol name, though not at its beginning.
1987 Each symbol has exactly one name. Each name in an assembly language
1988 program refers to exactly one symbol. You may use that symbol name any
1989 number of times in a program.
1991 @subheading Local Symbol Names
1993 @cindex local symbol names
1994 @cindex symbol names, local
1995 @cindex temporary symbol names
1996 @cindex symbol names, temporary
1997 Local symbols help compilers and programmers use names temporarily.
1998 There are ten local symbol names, which are re-used throughout the
1999 program. You may refer to them using the names @samp{0} @samp{1}
2000 @dots{} @samp{9}. To define a local symbol, write a label of the form
2001 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
2002 recent previous definition of that symbol write @samp{@b{N}b}, using the
2003 same digit as when you defined the label. To refer to the next
2004 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
2005 a choice of 10 forward references. The @samp{b} stands for
2006 ``backwards'' and the @samp{f} stands for ``forwards''.
2008 Local symbols are not emitted by the current GNU C compiler.
2010 There is no restriction on how you can use these labels, but
2011 remember that at any point in the assembly you can refer to at most
2012 10 prior local labels and to at most 10 forward local labels.
2014 Local symbol names are only a notation device. They are immediately
2015 transformed into more conventional symbol names before the assembler
2016 uses them. The symbol names stored in the symbol table, appearing in
2017 error messages and optionally emitted to the object file have these
2022 All local labels begin with @samp{L}. Normally both @code{@value{as}} and
2023 @code{_LD__} forget symbols that start with @samp{L}. These labels are
2024 used for symbols you are never intended to see. If you give the
2025 @samp{-L} option then @code{@value{as}} will retain these symbols in the
2026 object file. If you also instruct @code{_LD__} to retain these symbols,
2027 you may use them in debugging.
2030 If the label is written @samp{0:} then the digit is @samp{0}.
2031 If the label is written @samp{1:} then the digit is @samp{1}.
2032 And so on up through @samp{9:}.
2035 This unusual character is included so you don't accidentally invent
2036 a symbol of the same name. The character has ASCII value
2039 @item @emph{ordinal number}
2040 This is a serial number to keep the labels distinct. The first
2041 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
2042 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
2046 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
2047 @code{3:} is named @code{L3@ctrl{A}44}.
2050 @section The Special Dot Symbol
2052 @cindex dot (symbol)
2053 @cindex @code{.} (symbol)
2054 @cindex current address
2055 @cindex location counter
2056 The special symbol @samp{.} refers to the current address that
2057 @code{@value{as}} is assembling into. Thus, the expression @samp{melvin:
2058 .long .} will cause @code{melvin} to contain its own address.
2059 Assigning a value to @code{.} is treated the same as a @code{.org}
2060 directive. Thus, the expression @samp{.=.+4} is the same as saying
2068 @node Symbol Attributes
2069 @section Symbol Attributes
2071 @cindex symbol attributes
2072 @cindex attributes, symbol
2073 Every symbol has, as well as its name, the attributes ``Value'' and
2074 ``Type''. Depending on output format, symbols can also have auxiliary
2077 The detailed definitions are in _0__<a.out.h>_1__.
2080 If you use a symbol without defining it, @code{@value{as}} assumes zero for
2081 all these attributes, and probably won't warn you. This makes the
2082 symbol an externally defined symbol, which is generally what you
2086 * Symbol Value:: Value
2087 * Symbol Type:: Type
2088 _if__(_AOUT__||_BOUT__)
2089 _if__(_GENERIC__||!_BOUT__)
2090 * a.out Symbols:: Symbol Attributes: @code{a.out}
2091 _fi__(_GENERIC__||!_BOUT__)
2092 _if__(_BOUT__&&!_GENERIC__)
2093 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
2094 _fi__(_BOUT__&&!_GENERIC__)
2095 _fi__(_AOUT__||_BOUT__)
2097 * COFF Symbols:: Symbol Attributes for COFF
2104 @cindex value of a symbol
2105 @cindex symbol value
2106 The value of a symbol is (usually) 32 bits. For a symbol which labels a
2107 location in the text, data, bss or absolute sections the value is the
2108 number of addresses from the start of that section to the label.
2109 Naturally for text, data and bss sections the value of a symbol changes
2110 as @code{_LD__} changes section base addresses during linking. Absolute
2111 symbols' values do not change during linking: that is why they are
2114 The value of an undefined symbol is treated in a special way. If it is
2115 0 then the symbol is not defined in this assembler source program, and
2116 @code{_LD__} will try to determine its value from other programs it is
2117 linked with. You make this kind of symbol simply by mentioning a symbol
2118 name without defining it. A non-zero value represents a @code{.comm}
2119 common declaration. The value is how much common storage to reserve, in
2120 bytes (addresses). The symbol refers to the first address of the
2126 @cindex type of a symbol
2128 The type attribute of a symbol contains relocation (section)
2129 information, any flag settings indicating that a symbol is external, and
2130 (optionally), other information for linkers and debuggers. The exact
2131 format depends on the object-code output format in use.
2133 _if__(_AOUT__||_BOUT__)
2135 _if__(_BOUT__&&!_GENERIC__)
2136 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
2138 @cindex @code{b.out} symbol attributes
2139 @cindex symbol attributes, @code{b.out}
2140 These symbol attributes appear only when @code{@value{as}} is configured for
2141 one of the Berkeley-descended object output formats.
2142 _fi__(_BOUT__&&!_GENERIC__)
2143 _if__(_GENERIC__||!_BOUT__)
2144 @subsection Symbol Attributes: @code{a.out}
2145 _fi__(_GENERIC__||!_BOUT__)
2147 @cindex @code{a.out} symbol attributes
2148 @cindex symbol attributes, @code{a.out}
2151 * Symbol Desc:: Descriptor
2152 * Symbol Other:: Other
2156 @subsubsection Descriptor
2158 @cindex descriptor, of @code{a.out} symbol
2159 This is an arbitrary 16-bit value. You may establish a symbol's
2160 descriptor value by using a @code{.desc} statement
2161 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
2165 @subsubsection Other
2167 @cindex other attribute, of @code{a.out} symbol
2168 This is an arbitrary 8-bit value. It means nothing to @code{@value{as}}.
2169 _fi__(_AOUT__||_BOUT__)
2173 @subsection Symbol Attributes for COFF
2175 @cindex COFF symbol attributes
2176 @cindex symbol attributes, COFF
2178 The COFF format supports a multitude of auxiliary symbol attributes;
2179 like the primary symbol attributes, they are set between @code{.def} and
2180 @code{.endef} directives.
2182 @subsubsection Primary Attributes
2184 @cindex primary attributes, COFF symbols
2185 The symbol name is set with @code{.def}; the value and type,
2186 respectively, with @code{.val} and @code{.type}.
2188 @subsubsection Auxiliary Attributes
2190 @cindex auxiliary attributes, COFF symbols
2191 The @code{@value{as}} directives @code{.dim}, @code{.line}, @code{.scl},
2192 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2193 information for COFF.
2197 @chapter Expressions
2201 @cindex numeric values
2202 An @dfn{expression} specifies an address or numeric value.
2203 Whitespace may precede and/or follow an expression.
2206 * Empty Exprs:: Empty Expressions
2207 * Integer Exprs:: Integer Expressions
2211 @section Empty Expressions
2213 @cindex empty expressions
2214 @cindex expressions, empty
2215 An empty expression has no value: it is just whitespace or null.
2216 Wherever an absolute expression is required, you may omit the
2217 expression and @code{@value{as}} will assume a value of (absolute) 0. This
2218 is compatible with other assemblers.
2221 @section Integer Expressions
2223 @cindex integer expressions
2224 @cindex expressions, integer
2225 An @dfn{integer expression} is one or more @emph{arguments} delimited
2226 by @emph{operators}.
2229 * Arguments:: Arguments
2230 * Operators:: Operators
2231 * Prefix Ops:: Prefix Operators
2232 * Infix Ops:: Infix Operators
2236 @subsection Arguments
2238 @cindex expression arguments
2239 @cindex arguments in expressions
2240 @cindex operands in expressions
2241 @cindex arithmetic operands
2242 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2243 contexts arguments are sometimes called ``arithmetic operands''. In
2244 this manual, to avoid confusing them with the ``instruction operands'' of
2245 the machine language, we use the term ``argument'' to refer to parts of
2246 expressions only, reserving the word ``operand'' to refer only to machine
2247 instruction operands.
2249 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2250 @var{section} is one of text, data, bss, absolute,
2251 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2254 Numbers are usually integers.
2256 A number can be a flonum or bignum. In this case, you are warned
2257 that only the low order 32 bits are used, and @code{@value{as}} pretends
2258 these 32 bits are an integer. You may write integer-manipulating
2259 instructions that act on exotic constants, compatible with other
2262 @cindex subexpressions
2263 Subexpressions are a left parenthesis @samp{(} followed by an integer
2264 expression, followed by a right parenthesis @samp{)}; or a prefix
2265 operator followed by an argument.
2268 @subsection Operators
2270 @cindex operators, in expressions
2271 @cindex arithmetic functions
2272 @cindex functions, in expressions
2273 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2274 operators are followed by an argument. Infix operators appear
2275 between their arguments. Operators may be preceded and/or followed by
2279 @subsection Prefix Operator
2281 @cindex prefix operators
2282 @code{@value{as}} has the following @dfn{prefix operators}. They each take
2283 one argument, which must be absolute.
2285 @c the tex/end tex stuff surrounding this small table is meant to make
2286 @c it align, on the printed page, with the similar table in the next
2287 @c section (which is inside an enumerate).
2289 \global\advance\leftskip by \itemindent
2294 @dfn{Negation}. Two's complement negation.
2296 @dfn{Complementation}. Bitwise not.
2300 \global\advance\leftskip by -\itemindent
2304 @subsection Infix Operators
2306 @cindex infix operators
2307 @cindex operators, permitted arguments
2308 @dfn{Infix operators} take two arguments, one on either side. Operators
2309 have precedence, but operations with equal precedence are performed left
2310 to right. Apart from @code{+} or @code{-}, both arguments must be
2311 absolute, and the result is absolute.
2314 @cindex operator precedence
2315 @cindex precedence of operators
2322 @dfn{Multiplication}.
2325 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2332 @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__}
2336 @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__}
2340 Intermediate precedence
2345 @dfn{Bitwise Inclusive Or}.
2351 @dfn{Bitwise Exclusive Or}.
2354 @dfn{Bitwise Or Not}.
2362 @cindex addition, permitted arguments
2363 @cindex plus, permitted arguments
2364 @cindex arguments for addition
2365 @dfn{Addition}. If either argument is absolute, the result
2366 has the section of the other argument.
2367 If either argument is pass1 or undefined, the result is pass1.
2368 Otherwise @code{+} is illegal.
2371 @cindex subtraction, permitted arguments
2372 @cindex minus, permitted arguments
2373 @cindex arguments for subtraction
2374 @dfn{Subtraction}. If the right argument is absolute, the
2375 result has the section of the left argument.
2376 If either argument is pass1 the result is pass1.
2377 If either argument is undefined the result is difference section.
2378 If both arguments are in the same section, the result is absolute---provided
2379 that section is one of text, data or bss.
2380 Otherwise subtraction is illegal.
2384 The sense of the rule for addition is that it's only meaningful to add
2385 the @emph{offsets} in an address; you can only have a defined section in
2386 one of the two arguments.
2388 Similarly, you can't subtract quantities from two different sections.
2391 @chapter Assembler Directives
2393 @cindex directives, machine independent
2394 @cindex pseudo-ops, machine independent
2395 @cindex machine independent directives
2396 All assembler directives have names that begin with a period (@samp{.}).
2397 The rest of the name is letters, usually in lower case.
2399 This chapter discusses directives present regardless of the target
2400 machine configuration for the GNU assembler.
2402 @xref{_MACH_DEP__} for additional directives.
2406 * Abort:: @code{.abort}
2408 * coff-ABORT:: @code{.ABORT}
2410 _if__(_BOUT__&&!_COFF__)
2411 * bout-ABORT:: @code{.ABORT}
2412 _fi__(_BOUT__&&!_COFF__)
2413 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2414 * Appfile:: @code{.appfile @var{string}}
2415 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2416 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2417 * Byte:: @code{.byte @var{expressions}}
2418 * Comm:: @code{.comm @var{symbol} , @var{length} }
2419 * Data:: @code{.data @var{subsection}}
2420 _if__(_COFF__||_BOUT__)
2421 * Def:: @code{.def @var{name}}
2422 _fi__(_COFF__||_BOUT__)
2423 _if__(_AOUT__||_BOUT__)
2424 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2425 _fi__(_AOUT__||_BOUT__)
2426 _if__(_COFF__||_BOUT__)
2428 _fi__(_COFF__||_BOUT__)
2429 * Double:: @code{.double @var{flonums}}
2430 * Eject:: @code{.eject}
2431 * Else:: @code{.else}
2432 _if__(_COFF__||_BOUT__)
2433 * Endef:: @code{.endef}
2434 _fi__(_COFF__||_BOUT__)
2435 * Endif:: @code{.endif}
2436 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2437 * Extern:: @code{.extern}
2438 _if__(_GENERIC__||!_A29K__)
2439 * File:: @code{.file @var{string}}
2440 _fi__(_GENERIC__||!_A29K__)
2441 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2442 * Float:: @code{.float @var{flonums}}
2443 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2444 * hword:: @code{.hword @var{expressions}}
2445 * Ident:: @code{.ident}
2446 * If:: @code{.if @var{absolute expression}}
2447 * Include:: @code{.include "@var{file}"}
2448 * Int:: @code{.int @var{expressions}}
2449 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2450 * Lflags:: @code{.lflags}
2451 _if__(_GENERIC__||!_A29K__)
2452 * Line:: @code{.line @var{line-number}}
2453 _fi__(_GENERIC__||!_A29K__)
2454 * Ln:: @code{.ln @var{line-number}}
2455 * List:: @code{.list}
2456 * Long:: @code{.long @var{expressions}}
2458 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2460 * Nolist:: @code{.nolist}
2461 * Octa:: @code{.octa @var{bignums}}
2462 * Org:: @code{.org @var{new-lc} , @var{fill}}
2463 * Psize:: @code{.psize @var{lines}, @var{columns}}
2464 * Quad:: @code{.quad @var{bignums}}
2465 * Sbttl:: @code{.sbttl "@var{subheading}"}
2466 _if__(_COFF__||_BOUT__)
2467 * Scl:: @code{.scl @var{class}}
2468 _fi__(_COFF__||_BOUT__)
2470 * Section:: @code{.section @var{name}, @var{subsection}}
2472 * Set:: @code{.set @var{symbol}, @var{expression}}
2473 * Short:: @code{.short @var{expressions}}
2474 * Single:: @code{.single @var{flonums}}
2475 _if__(_COFF__||_BOUT__)
2476 * Size:: @code{.size}
2477 _fi__(_COFF__||_BOUT__)
2478 * Space:: @code{.space @var{size} , @var{fill}}
2479 _if__(_GENERIC__||!_H8__)
2480 * Stab:: @code{.stabd, .stabn, .stabs}
2481 _fi__(_GENERIC__||!_H8__)
2482 _if__(_COFF__||_BOUT__)
2483 * Tag:: @code{.tag @var{structname}}
2484 _fi__(_COFF__||_BOUT__)
2485 * Text:: @code{.text @var{subsection}}
2486 * Title:: @code{.title "@var{heading}"}
2487 _if__(_COFF__||_BOUT__)
2488 * Type:: @code{.type @var{int}}
2489 * Val:: @code{.val @var{addr}}
2490 _fi__(_COFF__||_BOUT__)
2491 * Word:: @code{.word @var{expressions}}
2492 * Deprecated:: Deprecated Directives
2496 @section @code{.abort}
2498 @cindex @code{abort} directive
2499 @cindex stopping the assembly
2500 This directive stops the assembly immediately. It is for
2501 compatibility with other assemblers. The original idea was that the
2502 assembly language source would be piped into the assembler. If the sender
2503 of the source quit, it could use this directive tells @code{@value{as}} to
2504 quit also. One day @code{.abort} will not be supported.
2508 @section @code{.ABORT}
2510 @cindex @code{ABORT} directive
2511 When producing COFF output, @code{@value{as}} accepts this directive as a
2512 synonym for @samp{.abort}.
2518 @section @code{.ABORT}
2520 @cindex @code{ABORT} directive
2523 When producing @code{b.out} output, @code{@value{as}} accepts this directive,
2528 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2530 @cindex padding the location counter
2531 @cindex @code{align} directive
2532 Pad the location counter (in the current subsection) to a particular
2533 storage boundary. The first expression (which must be absolute) is the
2534 number of low-order zero bits the location counter will have after
2535 advancement. For example @samp{.align 3} will advance the location
2536 counter until it a multiple of 8. If the location counter is already a
2537 multiple of 8, no change is needed.
2539 The second expression (also absolute) gives the value to be stored in
2540 the padding bytes. It (and the comma) may be omitted. If it is
2541 omitted, the padding bytes are zero.
2544 @section @code{.appfile @var{string}}
2546 @cindex logical file name
2547 @cindex file name, logical
2548 @cindex @code{appfile} directive
2551 (which may also be spelled @samp{.file})
2553 tells @code{@value{as}} that we are about to start a new
2554 logical file. @var{string} is the new file name. In general, the
2555 filename is recognized whether or not it is surrounded by quotes @samp{"};
2556 but if you wish to specify an empty file name is permitted,
2557 you must give the quotes--@code{""}. This statement may go away in
2558 future: it is only recognized to be compatible with old @code{@value{as}}
2562 @section @code{.ascii "@var{string}"}@dots{}
2564 @cindex @code{ascii} directive
2565 @cindex string literals
2566 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2567 separated by commas. It assembles each string (with no automatic
2568 trailing zero byte) into consecutive addresses.
2571 @section @code{.asciz "@var{string}"}@dots{}
2573 @cindex @code{asciz} directive
2574 @cindex zero-terminated strings
2575 @cindex null-terminated strings
2576 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2577 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2580 @section @code{.byte @var{expressions}}
2582 @cindex @code{byte} directive
2583 @cindex integers, one byte
2584 @code{.byte} expects zero or more expressions, separated by commas.
2585 Each expression is assembled into the next byte.
2588 @section @code{.comm @var{symbol} , @var{length} }
2590 @cindex @code{comm} directive
2591 @cindex symbol, common
2592 @code{.comm} declares a named common area in the bss section. Normally
2593 @code{_LD__} reserves memory addresses for it during linking, so no partial
2594 program defines the location of the symbol. Use @code{.comm} to tell
2595 @code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__}
2596 will allocate space for each @code{.comm} symbol that is at least as
2597 long as the longest @code{.comm} request in any of the partial programs
2598 linked. @var{length} is an absolute expression.
2601 @section @code{.data @var{subsection}}
2603 @cindex @code{data} directive
2604 @code{.data} tells @code{@value{as}} to assemble the following statements onto the
2605 end of the data subsection numbered @var{subsection} (which is an
2606 absolute expression). If @var{subsection} is omitted, it defaults
2609 _if__(_COFF__ || _BOUT__)
2611 @section @code{.def @var{name}}
2613 @cindex @code{def} directive
2614 @cindex COFF symbols, debugging
2615 @cindex debugging COFF symbols
2616 Begin defining debugging information for a symbol @var{name}; the
2617 definition extends until the @code{.endef} directive is encountered.
2620 This directive is only observed when @code{@value{as}} is configured for COFF
2621 format output; when producing @code{b.out}, @samp{.def} is recognized,
2624 _fi__(_COFF__ || _BOUT__)
2626 _if__(_AOUT__||_BOUT__)
2628 @section @code{.desc @var{symbol}, @var{abs-expression}}
2630 @cindex @code{desc} directive
2631 @cindex COFF symbol descriptor
2632 @cindex symbol descriptor, COFF
2633 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2634 to the low 16 bits of an absolute expression.
2637 The @samp{.desc} directive is not available when @code{@value{as}} is
2638 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2639 object format. For the sake of compatibility, @code{@value{as}} will accept
2640 it, but produce no output, when configured for COFF.
2642 _fi__(_AOUT__||_BOUT__)
2644 _if__(_COFF__ || _BOUT__)
2646 @section @code{.dim}
2648 @cindex @code{dim} directive
2649 @cindex COFF auxiliary symbol information
2650 @cindex auxiliary symbol information, COFF
2651 This directive is generated by compilers to include auxiliary debugging
2652 information in the symbol table. It is only permitted inside
2653 @code{.def}/@code{.endef} pairs.
2656 @samp{.dim} is only meaningful when generating COFF format output; when
2657 @code{@value{as}} is generating @code{b.out}, it accepts this directive but
2660 _fi__(_COFF__ || _BOUT__)
2663 @section @code{.double @var{flonums}}
2665 @cindex @code{double} directive
2666 @cindex floating point numbers (double)
2667 @code{.double} expects zero or more flonums, separated by commas. It
2668 assembles floating point numbers.
2670 The exact kind of floating point numbers emitted depends on how
2671 @code{@value{as}} is configured. @xref{_MACH_DEP__}.
2673 _if__((!_GENERIC__) && _IEEEFLOAT__)
2674 On the @value{host} family @samp{.double} emits 64-bit floating-point numbers
2675 in @sc{ieee} format.
2676 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2679 @section @code{.eject}
2681 @cindex @code{eject} directive
2682 @cindex new page, in listings
2683 @cindex page, in listings
2684 @cindex listing control: new page
2685 Force a page break at this point, when generating assembly listings.
2688 @section @code{.else}
2690 @cindex @code{else} directive
2691 @code{.else} is part of the @code{@value{as}} support for conditional
2692 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2693 of code to be assembled if the condition for the preceding @code{.if}
2697 @node End, Endef, Else, Pseudo Ops
2698 @section @code{.end}
2700 @cindex @code{end} directive
2701 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2702 meant to do something eventually (which is why it isn't documented here
2703 as "for compatibility with blah").
2706 _if__(_COFF__||_BOUT__)
2708 @section @code{.endef}
2710 @cindex @code{endef} directive
2711 This directive flags the end of a symbol definition begun with
2715 @samp{.endef} is only meaningful when generating COFF format output; if
2716 @code{@value{as}} is configured to generate @code{b.out}, it accepts this
2717 directive but ignores it.
2719 _fi__(_COFF__||_BOUT__)
2722 @section @code{.endif}
2724 @cindex @code{endif} directive
2725 @code{.endif} is part of the @code{@value{as}} support for conditional assembly;
2726 it marks the end of a block of code that is only assembled
2727 conditionally. @xref{If,,@code{.if}}.
2730 @section @code{.equ @var{symbol}, @var{expression}}
2732 @cindex @code{equ} directive
2733 @cindex assigning values to symbols
2734 @cindex symbols, assigning values to
2735 This directive sets the value of @var{symbol} to @var{expression}.
2736 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2739 @section @code{.extern}
2741 @cindex @code{extern} directive
2742 @code{.extern} is accepted in the source program---for compatibility
2743 with other assemblers---but it is ignored. @code{@value{as}} treats
2744 all undefined symbols as external.
2746 _if__(_GENERIC__||!_A29K__)
2748 @section @code{.file @var{string}}
2750 @cindex @code{file} directive
2751 @cindex logical file name
2752 @cindex file name, logical
2753 @code{.file} (which may also be spelled @samp{.appfile}) tells
2754 @code{@value{as}} that we are about to start a new logical file.
2755 @var{string} is the new file name. In general, the filename is
2756 recognized whether or not it is surrounded by quotes @samp{"}; but if
2757 you wish to specify an empty file name, you must give the
2758 quotes--@code{""}. This statement may go away in future: it is only
2759 recognized to be compatible with old @code{@value{as}} programs.
2761 In some configurations of @code{@value{as}}, @code{.file} has already been
2762 removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}.
2764 _fi__(_GENERIC__||!_A29K__)
2767 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2769 @cindex @code{fill} directive
2770 @cindex writing patterns in memory
2771 @cindex patterns, writing in memory
2772 @var{result}, @var{size} and @var{value} are absolute expressions.
2773 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2774 may be zero or more. @var{Size} may be zero or more, but if it is
2775 more than 8, then it is deemed to have the value 8, compatible with
2776 other people's assemblers. The contents of each @var{repeat} bytes
2777 is taken from an 8-byte number. The highest order 4 bytes are
2778 zero. The lowest order 4 bytes are @var{value} rendered in the
2779 byte-order of an integer on the computer @code{@value{as}} is assembling for.
2780 Each @var{size} bytes in a repetition is taken from the lowest order
2781 @var{size} bytes of this number. Again, this bizarre behavior is
2782 compatible with other people's assemblers.
2784 @var{size} and @var{value} are optional.
2785 If the second comma and @var{value} are absent, @var{value} is
2786 assumed zero. If the first comma and following tokens are absent,
2787 @var{size} is assumed to be 1.
2790 @section @code{.float @var{flonums}}
2792 @cindex floating point numbers (single)
2793 @cindex @code{float} directive
2794 This directive assembles zero or more flonums, separated by commas. It
2795 has the same effect as @code{.single}.
2797 The exact kind of floating point numbers emitted depends on how
2798 @code{@value{as}} is configured.
2801 _if__((!_GENERIC__) && _IEEEFLOAT__)
2802 On the @value{host} family, @code{.float} emits 32-bit floating point numbers
2803 in @sc{ieee} format.
2804 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2807 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2809 @cindex @code{global} directive
2810 @cindex symbol, making visible to linker
2811 @code{.global} makes the symbol visible to @code{_LD__}. If you define
2812 @var{symbol} in your partial program, its value is made available to
2813 other partial programs that are linked with it. Otherwise,
2814 @var{symbol} will take its attributes from a symbol of the same name
2815 from another partial program it is linked with.
2817 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2818 compatibility with other assemblers.
2821 @section @code{.hword @var{expressions}}
2823 @cindex @code{hword} directive
2824 @cindex integers, 16-bit
2825 @cindex numbers, 16-bit
2826 @cindex sixteen bit integers
2827 This expects zero or more @var{expressions}, and emits
2828 a 16 bit number for each.
2831 This directive is a synonym for @samp{.short}; depending on the target
2832 architecture, it may also be a synonym for @samp{.word}.
2834 _if__( _W32__ && !_GENERIC__ )
2835 This directive is a synonym for @samp{.short}.
2836 _fi__( _W32__ && !_GENERIC__ )
2837 _if__(_W16__ && !_GENERIC__ )
2838 This directive is a synonym for both @samp{.short} and @samp{.word}.
2839 _fi__(_W16__ && !_GENERIC__ )
2841 _if__(_AOUT__||_BOUT__||_COFF__)
2843 @section @code{.ident}
2845 @cindex @code{ident} directive
2846 This directive is used by some assemblers to place tags in object files.
2847 @code{@value{as}} simply accepts the directive for source-file
2848 compatibility with such assemblers, but does not actually emit anything
2850 _fi__(_AOUT__||_BOUT__||_COFF__)
2853 @section @code{.if @var{absolute expression}}
2855 @cindex conditional assembly
2856 @cindex @code{if} directive
2857 @code{.if} marks the beginning of a section of code which is only
2858 considered part of the source program being assembled if the argument
2859 (which must be an @var{absolute expression}) is non-zero. The end of
2860 the conditional section of code must be marked by @code{.endif}
2861 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
2862 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
2864 The following variants of @code{.if} are also supported:
2866 @item .ifdef @var{symbol}
2867 @cindex @code{ifdef} directive
2868 Assembles the following section of code if the specified @var{symbol}
2873 @cindex @code{ifeqs} directive
2874 Not yet implemented.
2877 @item .ifndef @var{symbol}
2878 @itemx ifnotdef @var{symbol}
2879 @cindex @code{ifndef} directive
2880 @cindex @code{ifnotdef} directive
2881 Assembles the following section of code if the specified @var{symbol}
2882 has not been defined. Both spelling variants are equivalent.
2886 Not yet implemented.
2891 @section @code{.include "@var{file}"}
2893 @cindex @code{include} directive
2894 @cindex supporting files, including
2895 @cindex files, including
2896 This directive provides a way to include supporting files at specified
2897 points in your source program. The code from @var{file} is assembled as
2898 if it followed the point of the @code{.include}; when the end of the
2899 included file is reached, assembly of the original file continues. You
2900 can control the search paths used with the @samp{-I} command-line option
2901 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
2905 @section @code{.int @var{expressions}}
2907 @cindex @code{int} directive
2908 _if__(_GENERIC__||!_H8__)
2909 @cindex integers, 32-bit
2910 _fi__(_GENERIC__||!_H8__)
2911 Expect zero or more @var{expressions}, of any section, separated by
2912 commas. For each expression, emit a
2913 _if__(_GENERIC__||!_H8__)
2915 _fi__(_GENERIC__||!_H8__)
2916 _if__(_H8__&&!_GENERIC__)
2918 _fi__(_H8__&&!_GENERIC__)
2919 number that will, at run
2920 time, be the value of that expression. The byte order of the
2921 expression depends on what kind of computer will run the program.
2924 @section @code{.lcomm @var{symbol} , @var{length}}
2926 @cindex @code{lcomm} directive
2927 @cindex local common symbols
2928 @cindex symbols, local common
2929 Reserve @var{length} (an absolute expression) bytes for a local common
2930 denoted by @var{symbol}. The section and value of @var{symbol} are
2931 those of the new local common. The addresses are allocated in the bss
2932 section, so at run-time the bytes will start off zeroed. @var{Symbol}
2933 is not declared global (@pxref{Global,,@code{.global}}), so is normally
2934 not visible to @code{_LD__}.
2937 @section @code{.lflags}
2939 @cindex @code{lflags} directive (ignored)
2940 @code{@value{as}} accepts this directive, for compatibility with other
2941 assemblers, but ignores it.
2943 _if__(_GENERIC__ || !_A29K__)
2945 @section @code{.line @var{line-number}}
2947 @cindex @code{line} directive
2948 _fi__(_GENERIC__ || (!_A29K__))
2949 _if__(_A29K__ && (!_GENERIC__) && !_COFF__)
2951 @section @code{.ln @var{line-number}}
2953 @cindex @code{ln} directive
2954 _fi__(_A29K__ && (!_GENERIC__) && !_COFF__)
2955 @cindex logical line number
2956 _if__(_AOUT__||_BOUT__)
2957 Tell @code{@value{as}} to change the logical line number. @var{line-number} must be
2958 an absolute expression. The next line will have that logical line
2959 number. So any other statements on the current line (after a statement
2965 _if__(! (_A29K__||_H8__) )
2967 _fi__(! (_A29K__||_H8__) )
2969 character @samp{@@})
2975 will be reported as on logical line number
2976 @var{line-number} @minus{} 1.
2977 One day this directive will be unsupported: it is used only
2978 for compatibility with existing assembler programs. @refill
2980 _if__(_GENERIC__ && _A29K__)
2981 @emph{Warning:} In the AMD29K configuration of @value{as}, this command is
2982 only available with the name @code{.ln}, rather than as either
2983 @code{.line} or @code{.ln}.
2984 _fi__(_GENERIC__ && _A29K__)
2985 _fi__(_AOUT__||_BOUT__)
2986 _if__(_COFF__ && !_A29K__)
2988 Even though this is a directive associated with the @code{a.out} or
2989 @code{b.out} object-code formats, @code{@value{as}} will still recognize it
2990 when producing COFF output, and will treat @samp{.line} as though it
2991 were the COFF @samp{.ln} @emph{if} it is found outside a
2992 @code{.def}/@code{.endef} pair.
2994 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
2995 used by compilers to generate auxiliary symbol information for
2997 _fi__(_COFF__ && !_A29K__)
2999 _if__(_AOUT__&&(_GENERIC__||!_A29K__))
3001 @section @code{.ln @var{line-number}}
3003 @cindex @code{ln} directive
3004 @samp{.ln} is a synonym for @samp{.line}.
3005 _fi__(_AOUT__&&(_GENERIC__||!_A29K__))
3006 _if__(_COFF__&&!_AOUT__)
3008 @section @code{.ln @var{line-number}}
3010 @cindex @code{ln} directive
3011 Tell @code{@value{as}} to change the logical line number. @var{line-number}
3012 must be an absolute expression. The next line will have that logical
3013 line number, so any other statements on the current line (after a
3014 statement separator character @code{;}) will be reported as on logical
3015 line number @var{line-number} @minus{} 1.
3018 This directive is accepted, but ignored, when @code{@value{as}} is configured for
3019 @code{b.out}; its effect is only associated with COFF output format.
3021 _fi__(_COFF__&&!_AOUT__)
3024 @section @code{.list}
3026 @cindex @code{list} directive
3027 @cindex listing control, turning on
3028 Control (in conjunction with the @code{.nolist} directive) whether or
3029 not assembly listings are generated. These two directives maintain an
3030 internal counter (which is zero initially). @code{.list} increments the
3031 counter, and @code{.nolist} decrements it. Assembly listings are
3032 generated whenever the counter is greater than zero.
3034 By default, listings are disabled. When you enable them (with the
3035 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
3036 the initial value of the listing counter is one.
3039 @section @code{.long @var{expressions}}
3041 @cindex @code{long} directive
3042 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
3045 @c no one seems to know what this is for or whether this description is
3046 @c what it really ought to do
3048 @section @code{.lsym @var{symbol}, @var{expression}}
3050 @cindex @code{lsym} directive
3051 @cindex symbol, not referenced in assembly
3052 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
3053 the hash table, ensuring it cannot be referenced by name during the
3054 rest of the assembly. This sets the attributes of the symbol to be
3055 the same as the expression value:
3057 @var{other} = @var{descriptor} = 0
3058 @var{type} = @r{(section of @var{expression})}
3059 @var{value} = @var{expression}
3062 The new symbol is not flagged as external.
3066 @section @code{.nolist}
3068 @cindex @code{nolist} directive
3069 @cindex listing control, turning off
3070 Control (in conjunction with the @code{.list} directive) whether or
3071 not assembly listings are generated. These two directives maintain an
3072 internal counter (which is zero initially). @code{.list} increments the
3073 counter, and @code{.nolist} decrements it. Assembly listings are
3074 generated whenever the counter is greater than zero.
3077 @section @code{.octa @var{bignums}}
3079 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
3080 @cindex @code{octa} directive
3081 @cindex integer, 16-byte
3082 @cindex sixteen byte integer
3083 This directive expects zero or more bignums, separated by commas. For each
3084 bignum, it emits a 16-byte integer.
3086 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
3087 hence @emph{octa}-word for 16 bytes.
3090 @section @code{.org @var{new-lc} , @var{fill}}
3092 @cindex @code{org} directive
3093 @cindex location counter, advancing
3094 @cindex advancing location counter
3095 @cindex current address, advancing
3096 @code{.org} will advance the location counter of the current section to
3097 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3098 expression with the same section as the current subsection. That is,
3099 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3100 wrong section, the @code{.org} directive is ignored. To be compatible
3101 with former assemblers, if the section of @var{new-lc} is absolute,
3102 @code{@value{as}} will issue a warning, then pretend the section of @var{new-lc}
3103 is the same as the current subsection.
3105 @code{.org} may only increase the location counter, or leave it
3106 unchanged; you cannot use @code{.org} to move the location counter
3109 @c double negative used below "not undefined" because this is a specific
3110 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3111 @c section. pesch@cygnus.com 18feb91
3112 Because @code{@value{as}} tries to assemble programs in one pass @var{new-lc}
3113 may not be undefined. If you really detest this restriction we eagerly await
3114 a chance to share your improved assembler.
3116 Beware that the origin is relative to the start of the section, not
3117 to the start of the subsection. This is compatible with other
3118 people's assemblers.
3120 When the location counter (of the current subsection) is advanced, the
3121 intervening bytes are filled with @var{fill} which should be an
3122 absolute expression. If the comma and @var{fill} are omitted,
3123 @var{fill} defaults to zero.
3126 @section @code{.psize @var{lines} , @var{columns}}
3128 @cindex @code{psize} directive
3129 @cindex listing control: paper size
3130 @cindex paper size, for listings
3131 Use this directive to declare the number of lines---and, optionally, the
3132 number of columns---to use for each page, when generating listings.
3134 If you don't use @code{.psize}, listings will use a default line-count
3135 of 60. You may omit the comma and @var{columns} specification; the
3136 default width is 200 columns.
3138 @code{@value{as}} will generate formfeeds whenever the specified number of
3139 lines is exceeded (or whenever you explicitly request one, using
3142 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3143 those explicitly specified with @code{.eject}.
3146 @section @code{.quad @var{bignums}}
3148 @cindex @code{quad} directive
3149 @code{.quad} expects zero or more bignums, separated by commas. For
3150 each bignum, it emits
3151 _if__(_GENERIC__||(!_I960__))
3152 an 8-byte integer. If the bignum won't fit in 8
3153 bytes, it prints a warning message; and just takes the lowest order 8
3154 bytes of the bignum.@refill
3155 @cindex eight-byte integer
3156 @cindex integer, 8-byte
3158 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3159 hence @emph{quad}-word for 8 bytes.
3160 _fi__(_GENERIC__||(!_I960__))
3161 _if__(_I960__&&(!_GENERIC__))
3162 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3163 warning message; and just takes the lowest order 16 bytes of the
3165 @cindex sixteen-byte integer
3166 @cindex integer, 16-byte
3167 _fi__(_I960__&&(!_GENERIC__))
3170 @section @code{.sbttl "@var{subheading}"}
3172 @cindex @code{sbttl} directive
3173 @cindex subtitles for listings
3174 @cindex listing control: subtitle
3175 Use @var{subheading} as the title (third line, immediately after the
3176 title line) when generating assembly listings.
3178 This directive affects subsequent pages, as well as the current page if
3179 it appears within ten lines of the top of a page.
3181 _if__(_COFF__||_BOUT__)
3183 @section @code{.scl @var{class}}
3185 @cindex @code{scl} directive
3186 @cindex symbol storage class (COFF)
3187 @cindex COFF symbol storage class
3188 Set the storage-class value for a symbol. This directive may only be
3189 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3190 whether a symbol is static or external, or it may record further
3191 symbolic debugging information.
3194 The @samp{.scl} directive is primarily associated with COFF output; when
3195 configured to generate @code{b.out} output format, @code{@value{as}} will
3196 accept this directive but ignore it.
3198 _fi__(_COFF__||_BOUT__)
3202 @section @code{.section @var{name}, @var{subsection}}
3204 @cindex @code{section} directive
3205 @cindex named section (COFF)
3206 @cindex COFF named section
3207 Assemble the following code into end of subsection numbered
3208 @var{subsection} in the COFF named section @var{name}. If you omit
3209 @var{subsection}, @code{@value{as}} uses subsection number zero.
3210 @samp{.section .text} is equivalent to the @code{.text} directive;
3211 @samp{.section .data} is equivalent to the @code{.data} directive.
3215 @section @code{.set @var{symbol}, @var{expression}}
3217 @cindex @code{set} directive
3218 @cindex symbol value, setting
3219 This directive sets the value of @var{symbol} to @var{expression}. This
3220 will change @var{symbol}'s value and type to conform to
3221 @var{expression}. If @var{symbol} was flagged as external, it remains
3222 flagged. (@xref{Symbol Attributes}.)
3224 You may @code{.set} a symbol many times in the same assembly.
3225 If the expression's section is unknowable during pass 1, a second
3226 pass over the source program will be forced. The second pass is
3227 currently not implemented. @code{@value{as}} will abort with an error
3228 message if one is required.
3230 If you @code{.set} a global symbol, the value stored in the object
3231 file is the last value stored into it.
3234 @section @code{.short @var{expressions}}
3236 @cindex @code{short} directive
3237 _if__(_GENERIC__ || _W16__)
3238 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3240 In some configurations, however, @code{.short} and @code{.word} generate
3241 numbers of different lengths; @pxref{_MACH_DEP__}.
3243 _fi__(_GENERIC__|| _W16__)
3244 _if__((!_GENERIC__) && _W32__)
3245 This expects zero or more @var{expressions}, and emits
3246 a 16 bit number for each.
3247 _fi__((!_GENERIC__) && _W32__)
3250 @section @code{.single @var{flonums}}
3252 @cindex @code{single} directive
3253 @cindex floating point numbers (single)
3254 This directive assembles zero or more flonums, separated by commas. It
3255 has the same effect as @code{.float}.
3257 The exact kind of floating point numbers emitted depends on how
3258 @code{@value{as}} is configured. @xref{_MACH_DEP__}.
3260 _if__((!_GENERIC__) && _IEEEFLOAT__)
3261 On the @value{host} family, @code{.single} emits 32-bit floating point
3262 numbers in @sc{ieee} format.
3263 _fi__((!_GENERIC__) && _IEEEFLOAT__)
3265 _if__(_COFF__||_BOUT__)
3267 @section @code{.size}
3269 @cindex @code{size} directive
3270 This directive is generated by compilers to include auxiliary debugging
3271 information in the symbol table. It is only permitted inside
3272 @code{.def}/@code{.endef} pairs.
3275 @samp{.size} is only meaningful when generating COFF format output; when
3276 @code{@value{as}} is generating @code{b.out}, it accepts this directive but
3279 _fi__(_COFF__||_BOUT__)
3282 _if__(_GENERIC__ || !_A29K__)
3283 @section @code{.space @var{size} , @var{fill}}
3285 @cindex @code{space} directive
3286 @cindex filling memory
3287 This directive emits @var{size} bytes, each of value @var{fill}. Both
3288 @var{size} and @var{fill} are absolute expressions. If the comma
3289 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3290 _fi__(_GENERIC__ || !_A29K__)
3294 @section @code{.space}
3295 @cindex @code{space} directive
3297 On the AMD 29K, this directive is ignored; it is accepted for
3298 compatibility with other AMD 29K assemblers.
3301 @emph{Warning:} In other versions of the GNU assembler, the directive
3302 @code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}.
3306 _if__(_GENERIC__||!_H8__)
3307 _if__(_AOUT__||_BOUT__||_COFF__)
3309 @section @code{.stabd, .stabn, .stabs}
3311 @cindex symbolic debuggers, information for
3312 @cindex @code{stab@var{x}} directives
3313 There are three directives that begin @samp{.stab}.
3314 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3315 The symbols are not entered in the @code{@value{as}} hash table: they
3316 cannot be referenced elsewhere in the source file.
3317 Up to five fields are required:
3320 This is the symbol's name. It may contain any character except @samp{\000},
3321 so is more general than ordinary symbol names. Some debuggers used to
3322 code arbitrarily complex structures into symbol names using this field.
3324 An absolute expression. The symbol's type is set to the low 8
3325 bits of this expression.
3326 Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on
3329 An absolute expression.
3330 The symbol's ``other'' attribute is set to the low 8 bits of this expression.
3332 An absolute expression.
3333 The symbol's descriptor is set to the low 16 bits of this expression.
3335 An absolute expression which becomes the symbol's value.
3338 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3339 or @code{.stabs} statement, the symbol has probably already been created
3340 and you will get a half-formed symbol in your object file. This is
3341 compatible with earlier assemblers!
3344 @cindex @code{stabd} directive
3345 @item .stabd @var{type} , @var{other} , @var{desc}
3347 The ``name'' of the symbol generated is not even an empty string.
3348 It is a null pointer, for compatibility. Older assemblers used a
3349 null pointer so they didn't waste space in object files with empty
3352 The symbol's value is set to the location counter,
3353 relocatably. When your program is linked, the value of this symbol
3354 will be where the location counter was when the @code{.stabd} was
3357 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3358 @cindex @code{stabn} directive
3359 The name of the symbol is set to the empty string @code{""}.
3361 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3362 @cindex @code{stabs} directive
3363 All five fields are specified.
3365 _fi__(_AOUT__||_BOUT__||_COFF__)
3366 _fi__(_GENERIC__||!_H8__)
3368 _if__(_COFF__||_BOUT__)
3370 @section @code{.tag @var{structname}}
3372 @cindex COFF structure debugging
3373 @cindex structure debugging, COFF
3374 @cindex @code{tag} directive
3375 This directive is generated by compilers to include auxiliary debugging
3376 information in the symbol table. It is only permitted inside
3377 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3378 definitions in the symbol table with instances of those structures.
3381 @samp{.tag} is only used when generating COFF format output; when
3382 @code{@value{as}} is generating @code{b.out}, it accepts this directive but
3385 _fi__(_COFF__||_BOUT__)
3388 @section @code{.text @var{subsection}}
3390 @cindex @code{text} directive
3391 Tells @code{@value{as}} to assemble the following statements onto the end of
3392 the text subsection numbered @var{subsection}, which is an absolute
3393 expression. If @var{subsection} is omitted, subsection number zero
3397 @section @code{.title "@var{heading}"}
3399 @cindex @code{title} directive
3400 @cindex listing control: title line
3401 Use @var{heading} as the title (second line, immediately after the
3402 source file name and pagenumber) when generating assembly listings.
3404 This directive affects subsequent pages, as well as the current page if
3405 it appears within ten lines of the top of a page.
3407 _if__(_COFF__||_BOUT__)
3409 @section @code{.type @var{int}}
3411 @cindex COFF symbol type
3412 @cindex symbol type, COFF
3413 @cindex @code{type} directive
3414 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3415 records the integer @var{int} as the type attribute of a symbol table entry.
3418 @samp{.type} is associated only with COFF format output; when
3419 @code{@value{as}} is configured for @code{b.out} output, it accepts this
3420 directive but ignores it.
3422 _fi__(_COFF__||_BOUT__)
3424 _if__(_COFF__||_BOUT__)
3426 @section @code{.val @var{addr}}
3428 @cindex @code{val} directive
3429 @cindex COFF value attribute
3430 @cindex value attribute, COFF
3431 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3432 records the address @var{addr} as the value attribute of a symbol table
3436 @samp{.val} is used only for COFF output; when @code{@value{as}} is
3437 configured for @code{b.out}, it accepts this directive but ignores it.
3439 _fi__(_COFF__||_BOUT__)
3442 @section @code{.word @var{expressions}}
3444 @cindex @code{word} directive
3445 This directive expects zero or more @var{expressions}, of any section,
3446 separated by commas.
3447 _if__((!_GENERIC__) && _W32__)
3448 For each expression, @code{@value{as}} emits a 32-bit number.
3449 _fi__((!_GENERIC__) && _W32__)
3450 _if__((!_GENERIC__) && _W16__)
3451 For each expression, @code{@value{as}} emits a 16-bit number.
3452 _fi__((!_GENERIC__) && _W16__)
3455 The size of the number emitted, and its byte order,
3456 depends on what kind of computer will run the program.
3459 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3460 @c happen---32-bit addressability, period; no long/short jumps.
3461 _if__(_GENERIC__ || _DIFFTABKLUG__)
3462 @cindex difference tables altered
3463 @cindex altered difference tables
3465 @emph{Warning: Special Treatment to support Compilers}
3469 Machines with a 32-bit address space, but that do less than 32-bit
3470 addressing, require the following special treatment. If the machine of
3471 interest to you does 32-bit addressing (or doesn't require it;
3472 @pxref{_MACH_DEP__}), you can ignore this issue.
3475 In order to assemble compiler output into something that will work,
3476 @code{@value{as}} will occasionlly do strange things to @samp{.word} directives.
3477 Directives of the form @samp{.word sym1-sym2} are often emitted by
3478 compilers as part of jump tables. Therefore, when @code{@value{as}} assembles a
3479 directive of the form @samp{.word sym1-sym2}, and the difference between
3480 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{as}} will
3481 create a @dfn{secondary jump table}, immediately before the next label.
3482 This secondary jump table will be preceded by a short-jump to the
3483 first byte after the secondary table. This short-jump prevents the flow
3484 of control from accidentally falling into the new table. Inside the
3485 table will be a long-jump to @code{sym2}. The original @samp{.word}
3486 will contain @code{sym1} minus the address of the long-jump to
3489 If there were several occurrences of @samp{.word sym1-sym2} before the
3490 secondary jump table, all of them will be adjusted. If there was a
3491 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3492 long-jump to @code{sym4} will be included in the secondary jump table,
3493 and the @code{.word} directives will be adjusted to contain @code{sym3}
3494 minus the address of the long-jump to @code{sym4}; and so on, for as many
3495 entries in the original jump table as necessary.
3498 @emph{This feature may be disabled by compiling @code{@value{as}} with the
3499 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3500 assembly language programmers.
3502 _fi__(_GENERIC__ || _DIFFTABKLUG__)
3505 @section Deprecated Directives
3507 @cindex deprecated directives
3508 @cindex obsolescent directives
3509 One day these directives won't work.
3510 They are included for compatibility with older assemblers.
3519 @chapter Machine Dependent Features
3521 @cindex machine dependencies
3522 The machine instruction sets are (almost by definition) different on
3523 each machine where @code{@value{as}} runs. Floating point representations
3524 vary as well, and @code{@value{as}} often supports a few additional
3525 directives or command-line options for compatibility with other
3526 assemblers on a particular platform. Finally, some versions of
3527 @code{@value{as}} support special pseudo-instructions for branch
3530 This chapter discusses most of these differences, though it does not
3531 include details on any machine's instruction set. For details on that
3532 subject, see the hardware manufacturer's manual.
3536 * Vax-Dependent:: VAX Dependent Features
3539 * AMD29K-Dependent:: AMD 29K Dependent Features
3542 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3545 * i960-Dependent:: Intel 80960 Dependent Features
3548 * M68K-Dependent:: M680x0 Dependent Features
3551 * Sparc-Dependent:: SPARC Dependent Features
3554 * Z8000-Dependent:: Z8000 Dependent Features
3557 * i386-Dependent:: 80386 Dependent Features
3566 _CHAPSEC__(0+_GENERIC__) VAX Dependent Features
3570 * Vax-Opts:: VAX Command-Line Options
3571 * VAX-float:: VAX Floating Point
3572 * VAX-directives:: Vax Machine Directives
3573 * VAX-opcodes:: VAX Opcodes
3574 * VAX-branch:: VAX Branch Improvement
3575 * VAX-operands:: VAX Operands
3576 * VAX-no:: Not Supported on VAX
3580 _CHAPSEC__(1+_GENERIC__) VAX Command-Line Options
3582 @cindex command-line options ignored, VAX
3583 @cindex VAX command-line options ignored
3584 The Vax version of @code{@value{as}} accepts any of the following options,
3585 gives a warning message that the option was ignored and proceeds.
3586 These options are for compatibility with scripts designed for other
3587 people's assemblers.
3590 @item @kbd{-D} (Debug)
3591 @itemx @kbd{-S} (Symbol Table)
3592 @itemx @kbd{-T} (Token Trace)
3593 @cindex @code{-D}, ignored on VAX
3594 @cindex @code{-S}, ignored on VAX
3595 @cindex @code{-T}, ignored on VAX
3596 These are obsolete options used to debug old assemblers.
3598 @item @kbd{-d} (Displacement size for JUMPs)
3599 @cindex @code{-d}, VAX option
3600 This option expects a number following the @kbd{-d}. Like options
3601 that expect filenames, the number may immediately follow the
3602 @kbd{-d} (old standard) or constitute the whole of the command line
3603 argument that follows @kbd{-d} (GNU standard).
3605 @item @kbd{-V} (Virtualize Interpass Temporary File)
3606 @cindex @code{-V}, redundant on VAX
3607 Some other assemblers use a temporary file. This option
3608 commanded them to keep the information in active memory rather
3609 than in a disk file. @code{@value{as}} always does this, so this
3610 option is redundant.
3612 @item @kbd{-J} (JUMPify Longer Branches)
3613 @cindex @code{-J}, ignored on VAX
3614 Many 32-bit computers permit a variety of branch instructions
3615 to do the same job. Some of these instructions are short (and
3616 fast) but have a limited range; others are long (and slow) but
3617 can branch anywhere in virtual memory. Often there are 3
3618 flavors of branch: short, medium and long. Some other
3619 assemblers would emit short and medium branches, unless told by
3620 this option to emit short and long branches.
3622 @item @kbd{-t} (Temporary File Directory)
3623 @cindex @code{-t}, ignored on VAX
3624 Some other assemblers may use a temporary file, and this option
3625 takes a filename being the directory to site the temporary
3626 file. @code{@value{as}} does not use a temporary disk file, so this
3627 option makes no difference. @kbd{-t} needs exactly one
3631 @cindex VMS (VAX) options
3632 @cindex options for VAX/VMS
3633 @cindex VAX/VMS options
3634 @cindex @code{-h} option, VAX/VMS
3635 @cindex @code{-+} option, VAX/VMS
3636 @cindex Vax-11 C compatibility
3637 @cindex symbols with lowercase, VAX/VMS
3638 @c FIXME! look into "I think" below, correct if needed, delete.
3639 The Vax version of the assembler accepts two options when
3640 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
3641 @kbd{-h} option prevents @code{@value{as}} from modifying the
3642 symbol-table entries for symbols that contain lowercase
3643 characters (I think). The @kbd{-+} option causes @code{@value{as}} to
3644 print warning messages if the FILENAME part of the object file,
3645 or any symbol name is larger than 31 characters. The @kbd{-+}
3646 option also insertes some code following the @samp{_main}
3647 symbol so that the object file will be compatible with Vax-11
3651 _CHAPSEC__(1+_GENERIC__) VAX Floating Point
3653 @cindex VAX floating point
3654 @cindex floating point, VAX
3655 Conversion of flonums to floating point is correct, and
3656 compatible with previous assemblers. Rounding is
3657 towards zero if the remainder is exactly half the least significant bit.
3659 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3662 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3663 are rendered correctly. Again, rounding is towards zero in the
3666 @cindex @code{float} directive, VAX
3667 @cindex @code{double} directive, VAX
3668 The @code{.float} directive produces @code{f} format numbers.
3669 The @code{.double} directive produces @code{d} format numbers.
3671 @node VAX-directives
3672 _CHAPSEC__(1+_GENERIC__) Vax Machine Directives
3674 @cindex machine directives, VAX
3675 @cindex VAX machine directives
3676 The Vax version of the assembler supports four directives for
3677 generating Vax floating point constants. They are described in the
3680 @cindex wide floating point directives, VAX
3683 @cindex @code{dfloat} directive, VAX
3684 This expects zero or more flonums, separated by commas, and
3685 assembles Vax @code{d} format 64-bit floating point constants.
3688 @cindex @code{ffloat} directive, VAX
3689 This expects zero or more flonums, separated by commas, and
3690 assembles Vax @code{f} format 32-bit floating point constants.
3693 @cindex @code{gfloat} directive, VAX
3694 This expects zero or more flonums, separated by commas, and
3695 assembles Vax @code{g} format 64-bit floating point constants.
3698 @cindex @code{hfloat} directive, VAX
3699 This expects zero or more flonums, separated by commas, and
3700 assembles Vax @code{h} format 128-bit floating point constants.
3705 _CHAPSEC__(1+_GENERIC__) VAX Opcodes
3707 @cindex VAX opcode mnemonics
3708 @cindex opcode mnemonics, VAX
3709 @cindex mnemonics for opcodes, VAX
3710 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3711 instructions have exactly 3 operands. The dispatch table that
3712 follows the @code{case@dots{}} instruction should be made with
3713 @code{.word} statements. This is compatible with all unix
3714 assemblers we know of.
3717 _CHAPSEC__(1+_GENERIC__) VAX Branch Improvement
3719 @cindex VAX branch improvement
3720 @cindex branch improvement, VAX
3721 @cindex pseudo-ops for branch, VAX
3722 Certain pseudo opcodes are permitted. They are for branch
3723 instructions. They expand to the shortest branch instruction that
3724 will reach the target. Generally these mnemonics are made by
3725 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3726 This feature is included both for compatibility and to help
3727 compilers. If you don't need this feature, don't use these
3728 opcodes. Here are the mnemonics, and the code they can expand into.
3732 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3734 @item (byte displacement)
3736 @item (word displacement)
3738 @item (long displacement)
3743 Unconditional branch.
3745 @item (byte displacement)
3747 @item (word displacement)
3749 @item (long displacement)
3753 @var{COND} may be any one of the conditional branches
3754 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
3755 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
3756 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
3757 @var{COND} may also be one of the bit tests
3758 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
3759 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
3760 @var{NOTCOND} is the opposite condition to @var{COND}.
3762 @item (byte displacement)
3763 @kbd{b@var{COND} @dots{}}
3764 @item (word displacement)
3765 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
3766 @item (long displacement)
3767 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
3770 @var{X} may be one of @code{b d f g h l w}.
3772 @item (word displacement)
3773 @kbd{@var{OPCODE} @dots{}}
3774 @item (long displacement)
3776 @var{OPCODE} @dots{}, foo ;
3783 @var{YYY} may be one of @code{lss leq}.
3785 @var{ZZZ} may be one of @code{geq gtr}.
3787 @item (byte displacement)
3788 @kbd{@var{OPCODE} @dots{}}
3789 @item (word displacement)
3791 @var{OPCODE} @dots{}, foo ;
3793 foo: brw @var{destination} ;
3796 @item (long displacement)
3798 @var{OPCODE} @dots{}, foo ;
3800 foo: jmp @var{destination} ;
3809 @item (byte displacement)
3810 @kbd{@var{OPCODE} @dots{}}
3811 @item (word displacement)
3813 @var{OPCODE} @dots{}, foo ;
3815 foo: brw @var{destination} ;
3818 @item (long displacement)
3820 @var{OPCODE} @dots{}, foo ;
3822 foo: jmp @var{destination} ;
3829 _CHAPSEC__(1+_GENERIC__) VAX Operands
3831 @cindex VAX operand notation
3832 @cindex operand notation, VAX
3833 @cindex immediate character, VAX
3834 @cindex VAX immediate character
3835 The immediate character is @samp{$} for Unix compatibility, not
3836 @samp{#} as DEC writes it.
3838 @cindex indirect character, VAX
3839 @cindex VAX indirect character
3840 The indirect character is @samp{*} for Unix compatibility, not
3841 @samp{@@} as DEC writes it.
3843 @cindex displacement sizing character, VAX
3844 @cindex VAX displacement sizing character
3845 The displacement sizing character is @samp{`} (an accent grave) for
3846 Unix compatibility, not @samp{^} as DEC writes it. The letter
3847 preceding @samp{`} may have either case. @samp{G} is not
3848 understood, but all other letters (@code{b i l s w}) are understood.
3850 @cindex register names, VAX
3851 @cindex VAX register names
3852 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
3853 pc}. Any case of letters will do.
3860 Any expression is permitted in an operand. Operands are comma
3863 @c There is some bug to do with recognizing expressions
3864 @c in operands, but I forget what it is. It is
3865 @c a syntax clash because () is used as an address mode
3866 @c and to encapsulate sub-expressions.
3869 _CHAPSEC__(1+_GENERIC__) Not Supported on VAX
3871 @cindex VAX bitfields not supported
3872 @cindex bitfields, not supported on VAX
3873 Vax bit fields can not be assembled with @code{@value{as}}. Someone
3874 can add the required code if they really need it.
3879 @node AMD29K-Dependent
3881 _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features
3883 @cindex AMD 29K support
3886 * AMD29K Options:: Options
3887 * AMD29K Syntax:: Syntax
3888 * AMD29K Floating Point:: Floating Point
3889 * AMD29K Directives:: AMD 29K Machine Directives
3890 * AMD29K Opcodes:: Opcodes
3893 @node AMD29K Options
3894 _CHAPSEC__(1+_GENERIC__) Options
3895 @cindex AMD 29K options (none)
3896 @cindex options for AMD29K (none)
3897 @code{@value{as}} has no additional command-line options for the AMD
3901 _CHAPSEC__(1+_GENERIC__) Syntax
3903 * AMD29K-Chars:: Special Characters
3904 * AMD29K-Regs:: Register Names
3908 _CHAPSEC__(2+_GENERIC__) Special Characters
3910 @cindex line comment character, AMD 29K
3911 @cindex AMD 29K line comment character
3912 @samp{;} is the line comment character.
3914 @cindex line separator, AMD 29K
3915 @cindex AMD 29K line separator
3916 @cindex statement separator, AMD 29K
3917 @cindex AMD 29K statement separator
3918 @samp{@@} can be used instead of a newline to separate statements.
3920 @cindex identifiers, AMD 29K
3921 @cindex AMD 29K identifiers
3922 The character @samp{?} is permitted in identifiers (but may not begin
3926 _CHAPSEC__(2+_GENERIC__) Register Names
3928 @cindex AMD 29K register names
3929 @cindex register names, AMD 29K
3930 General-purpose registers are represented by predefined symbols of the
3931 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
3932 (for local registers), where @var{nnn} represents a number between
3933 @code{0} and @code{127}, written with no leading zeros. The leading
3934 letters may be in either upper or lower case; for example, @samp{gr13}
3935 and @samp{LR7} are both valid register names.
3937 You may also refer to general-purpose registers by specifying the
3938 register number as the result of an expression (prefixed with @samp{%%}
3939 to flag the expression as a register number):
3944 ---where @var{expression} must be an absolute expression evaluating to a
3945 number between @code{0} and @code{255}. The range [0, 127] refers to
3946 global registers, and the range [128, 255] to local registers.
3948 @cindex special purpose registers, AMD 29K
3949 @cindex AMD 29K special purpose registers
3950 @cindex protected registers, AMD 29K
3951 @cindex AMD 29K protected registers
3952 In addition, @code{@value{as}} understands the following protected
3953 special-purpose register names for the AMD 29K family:
3963 These unprotected special-purpose register names are also recognized:
3971 @node AMD29K Floating Point
3972 _CHAPSEC__(1+_GENERIC__) Floating Point
3974 @cindex floating point, AMD 29K (@sc{ieee})
3975 @cindex AMD 29K floating point (@sc{ieee})
3976 The AMD 29K family uses @sc{ieee} floating-point numbers.
3978 @node AMD29K Directives
3979 _CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives
3981 @cindex machine directives, AMD 29K
3982 @cindex AMD 29K machine directives
3984 @item .block @var{size} , @var{fill}
3985 @cindex @code{block} directive, AMD 29K
3986 This directive emits @var{size} bytes, each of value @var{fill}. Both
3987 @var{size} and @var{fill} are absolute expressions. If the comma
3988 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3990 In other versions of the GNU assembler, this directive is called
3996 @cindex @code{cputype} directive, AMD 29K
3997 This directive is ignored; it is accepted for compatibility with other
4001 @cindex @code{file} directive, AMD 29K
4002 This directive is ignored; it is accepted for compatibility with other
4006 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
4007 used for the directive called @code{.appfile} in the AMD 29K support.
4011 @cindex @code{line} directive, AMD 29K
4012 This directive is ignored; it is accepted for compatibility with other
4016 @c since we're ignoring .lsym...
4017 @item .reg @var{symbol}, @var{expression}
4018 @cindex @code{reg} directive, AMD 29K
4019 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
4023 @cindex @code{sect} directive, AMD 29K
4024 This directive is ignored; it is accepted for compatibility with other
4027 @item .use @var{section name}
4028 @cindex @code{use} directive, AMD 29K
4029 Establishes the section and subsection for the following code;
4030 @var{section name} may be one of @code{.text}, @code{.data},
4031 @code{.data1}, or @code{.lit}. With one of the first three @var{section
4032 name} options, @samp{.use} is equivalent to the machine directive
4033 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
4037 @node AMD29K Opcodes
4038 _CHAPSEC__(1+_GENERIC__) Opcodes
4040 @cindex AMD 29K opcodes
4041 @cindex opcodes for AMD 29K
4042 @code{@value{as}} implements all the standard AMD 29K opcodes. No
4043 additional pseudo-instructions are needed on this family.
4045 For information on the 29K machine instruction set, see @cite{Am29000
4046 User's Manual}, Advanced Micro Devices, Inc.
4051 @node H8/300-Dependent
4053 _CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features
4055 @cindex H8/300 support
4057 * H8/300 Options:: Options
4058 * H8/300 Syntax:: Syntax
4059 * H8/300 Floating Point:: Floating Point
4060 * H8/300 Directives:: H8/300 Machine Directives
4061 * H8/300 Opcodes:: Opcodes
4064 @node H8/300 Options
4065 _CHAPSEC__(1+_GENERIC__) Options
4067 @cindex H8/300 options (none)
4068 @cindex options, H8/300 (none)
4069 @code{@value{as}} has no additional command-line options for the Hitachi
4073 _CHAPSEC__(1+_GENERIC__) Syntax
4075 * H8/300-Chars:: Special Characters
4076 * H8/300-Regs:: Register Names
4077 * H8/300-Addressing:: Addressing Modes
4081 _CHAPSEC__(2+_GENERIC__) Special Characters
4083 @cindex line comment character, H8/300
4084 @cindex H8/300 line comment character
4085 @samp{;} is the line comment character.
4087 @cindex line separator, H8/300
4088 @cindex statement separator, H8/300
4089 @cindex H8/300 line separator
4090 @samp{$} can be used instead of a newline to separate statements.
4091 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4094 _CHAPSEC__(2+_GENERIC__) Register Names
4096 @cindex H8/300 registers
4097 @cindex registers, H8/300
4098 You can use predefined symbols of the form @samp{r@var{n}h} and
4099 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4100 general-purpose registers. @var{n} is a digit from @samp{0} to
4101 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4104 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4105 to the H8/300 registers as 16-bit registers (you must use this form for
4108 The two control registers are called @code{pc} (program counter; a
4109 16-bit register) and @code{ccr} (condition code register; an 8-bit
4110 register). @code{r7} is used as the stack pointer, and can also be
4113 @node H8/300-Addressing
4114 _CHAPSEC__(2+_GENERIC__) Addressing Modes
4116 @cindex addressing modes, H8/300
4117 @cindex H8/300 addressing modes
4118 @value{as} understands the following addressing modes for the H8/300:
4126 @item @@(@var{d}, r@var{n})
4127 @itemx @@(@var{d}:16, r@var{n})
4128 Register indirect: 16-bit displacement @var{d} from register @var{n}.
4129 (You may specify the @samp{:16} for clarity if you wish, but it is not
4130 required and has no effect.)
4133 Register indirect with post-increment
4136 Register indirect with pre-decrement
4138 @item @code{@@}@var{aa}
4139 @itemx @code{@@}@var{aa}:8
4140 @itemx @code{@@}@var{aa}:16
4141 Absolute address @code{aa}. You may specify the @samp{:8} or @samp{:16}
4142 for clarity, if you wish; but @code{@value{as}} neither requires this nor
4143 uses it---the address size required is taken from context.
4148 Immediate data @var{xx}. You may specify the @samp{:8} or @samp{:16}
4149 for clarity, if you wish; but @code{@value{as}} neither requires this nor
4150 uses it---the data size required is taken from context.
4152 @item @code{@@}@code{@@}@var{aa}
4153 @itemx @code{@@}@code{@@}@var{aa}:8
4154 Memory indirect. You may specify the @samp{:8} for clarity, if you
4155 wish; but @code{@value{as}} neither requires this nor uses it.
4158 @node H8/300 Floating Point
4159 _CHAPSEC__(1+_GENERIC__) Floating Point
4161 @cindex floating point, H8/300 (@sc{ieee})
4162 @cindex H8/300 floating point (@sc{ieee})
4163 The H8/300 family uses @sc{ieee} floating-point numbers.
4165 @node H8/300 Directives
4166 _CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives
4168 @cindex H8/300 machine directives (none)
4169 @cindex machine directives, H8/300 (none)
4170 @cindex @code{word} directive, H8/300
4171 @cindex @code{int} directive, H8/300
4172 @code{@value{as}} has no machine-dependent directives for the H8/300.
4173 However, on this platform the @samp{.int} and @samp{.word} directives
4174 generate 16-bit numbers.
4176 @node H8/300 Opcodes
4177 _CHAPSEC__(1+_GENERIC__) Opcodes
4179 @cindex H8/300 opcode summary
4180 @cindex opcode summary, H8/300
4181 @cindex mnemonics, H8/300
4182 @cindex instruction summary, H8/300
4183 For detailed information on the H8/300 machine instruction set, see
4184 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025).
4186 @code{@value{as}} implements all the standard H8/300 opcodes. No additional
4187 pseudo-instructions are needed on this family.
4189 The following table summarizes the opcodes and their arguments:
4190 @c kluge due to lack of group outside example
4194 Rs @r{source register}
4195 Rd @r{destination register}
4196 imm @r{immediate data}
4197 x:3 @r{a bit (as a number between 0 and 7)}
4198 d:8 @r{eight bit displacement from @code{pc}}
4199 d:16 @r{sixteen bit displacement from @code{Rs}}
4201 add.b Rs,Rd biand #x:3,Rd
4202 add.b #imm:8,Rd biand #x:3,@@Rd
4203 add.w Rs,Rd biand #x:3,@@aa:8
4204 adds #1,Rd bild #x:3,Rd
4205 adds #2,Rd bild #x:3,@@Rd
4206 addx #imm:8,Rd bild #x:3,@@aa:8
4207 addx Rs,Rd bior #x:3,Rd
4208 and #imm:8,Rd bior #x:3,@@Rd
4209 and Rs,Rd bior #x:3,@@aa:8
4210 andc #imm:8,ccr bist #x:3,Rd
4211 band #x:3,Rd bist #x:3,@@Rd
4212 band #x:3,@@Rd bist #x:3,@@aa:8
4213 bra d:8 bixor #x:3,Rd
4214 bt d:8 bixor #x:3,@@Rd
4215 brn d:8 bixor #x:3,@@aa:8
4217 bhi d:8 bld #x:3,@@Rd
4218 bls d:8 bld #x:3,@@aa:8
4219 bcc d:8 bnot #x:3,Rd
4220 bhs d:8 bnot #x:3,@@Rd
4221 bcs d:8 bnot #x:3,@@aa:8
4223 bne d:8 bnot Rs,@@Rd
4224 beq d:8 bnot Rs,@@aa:8
4226 bvs d:8 bor #x:3,@@Rd
4227 bpl d:8 bor #x:3,@@aa:8
4228 bmi d:8 bset #x:3,@@Rd
4229 bge d:8 bset #x:3,@@aa:8
4231 bgt d:8 bset Rs,@@Rd
4232 ble d:8 bset Rs,@@aa:8
4233 bclr #x:3,Rd bsr d:8
4234 bclr #x:3,@@Rd bst #x:3,Rd
4235 bclr #x:3,@@aa:8 bst #x:3,@@Rd
4236 bclr Rs,Rd bst #x:3,@@aa:8
4237 bclr Rs,@@Rd btst #x:3,Rd
4240 btst #x:3,@@Rd mov.w @@(d:16, Rs),Rd
4241 btst #x:3,@@aa:8 mov.w @@Rs+,Rd
4242 btst Rs,Rd mov.w @@aa:16,Rd
4243 btst Rs,@@Rd mov.w Rs,@@Rd
4244 btst Rs,@@aa:8 mov.w Rs,@@(d:16, Rd)
4245 bxor #x:3,Rd mov.w Rs,@@-Rd
4246 bxor #x:3,@@Rd mov.w Rs,@@aa:16
4247 bxor #x:3,@@aa:8 movfpe @@aa:16,Rd
4248 cmp.b #imm:8,Rd movtpe Rs,@@aa:16
4249 cmp.b Rs,Rd mulxu Rs,Rd
4254 divxu Rs,Rd or Rs,Rd
4255 eepmov orc #imm:8,ccr
4261 jsr @@aa:16 rotxr Rs
4266 mov.b #imm:8,Rd shll Rs
4267 mov.b @@Rs,Rd shlr Rs
4268 mov.b @@(d:16, Rs),Rd sleep
4269 mov.b @@Rs+,Rd stc ccr,Rd
4270 mov.b @@aa:16,Rd sub.b Rs,Rd
4271 mov.b @@aa:8,Rd sub.w Rs,Rd
4272 mov.b Rs,@@Rd subs #1,Rd
4273 mov.b Rs,@@(d:16, Rd) subs #2,Rd
4274 mov.b Rs,@@-Rd subx #imm:8,Rd
4275 mov.b Rs,@@aa:16 subx Rs,Rd
4276 mov.b Rs,@@aa:8 xor #imm:8,Rd
4277 mov.w Rs,Rd xor Rs,Rd
4278 mov.w #imm:16,Rd xorc #imm:8,ccr
4283 @cindex size suffixes, H8/300
4284 @cindex H8/300 size suffixes
4285 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4286 @code{sub}) are defined with variants using the suffixes @samp{.b} and
4287 @samp{.w} to specify the size of a memory operand. @code{@value{as}}
4288 supports these suffixes, but does not require them; since one of the
4289 operands is always a register, @code{@value{as}} can deduce the correct size.
4291 For example, since @code{r0} refers to a 16-bit register,
4294 @exdent is equivalent to
4298 If you use the size suffixes, @code{@value{as}} will issue a warning if
4299 there's a mismatch between the suffix and the register size.
4304 @node i960-Dependent
4306 _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features
4308 @cindex i960 support
4310 * Options-i960:: i960 Command-line Options
4311 * Floating Point-i960:: Floating Point
4312 * Directives-i960:: i960 Machine Directives
4313 * Opcodes for i960:: i960 Opcodes
4316 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
4317 @c long as they're not turned on for other machines than 960.
4321 _CHAPSEC__(1+_GENERIC__) i960 Command-line Options
4323 @cindex i960 options
4324 @cindex options, i960
4327 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
4328 @cindex i960 architecture options
4329 @cindex architecture options, i960
4330 @cindex @code{-A} options, i960
4331 Select the 80960 architecture. Instructions or features not supported
4332 by the selected architecture cause fatal errors.
4334 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
4335 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
4337 If none of these options is specified, @code{@value{as}} will generate code for any
4338 instruction or feature that is supported by @emph{some} version of the
4339 960 (even if this means mixing architectures!). In principle,
4340 @code{@value{as}} will attempt to deduce the minimal sufficient processor
4341 type if none is specified; depending on the object code format, the
4342 processor type may be recorded in the object file. If it is critical
4343 that the @code{@value{as}} output match a specific architecture, specify that
4344 architecture explicitly.
4347 @cindex @code{-b} option, i960
4348 @cindex branch recording, i960
4349 @cindex i960 branch recording
4350 Add code to collect information about conditional branches taken, for
4351 later optimization using branch prediction bits. (The conditional branch
4352 instructions have branch prediction bits in the CA, CB, and CC
4353 architectures.) If @var{BR} represents a conditional branch instruction,
4354 the following represents the code generated by the assembler when
4355 @samp{-b} is specified:
4358 call @var{increment routine}
4359 .word 0 # pre-counter
4361 call @var{increment routine}
4362 .word 0 # post-counter
4365 The counter following a branch records the number of times that branch
4366 was @emph{not} taken; the differenc between the two counters is the
4367 number of times the branch @emph{was} taken.
4369 @cindex @code{gbr960}, i960 postprocessor
4370 @cindex branch statistics table, i960
4371 A table of every such @code{Label} is also generated, so that the
4372 external postprocessor @code{gbr960} (supplied by Intel) can locate all
4373 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
4374 this is a local symbol to permit collecting statistics for many separate
4375 object files. The table is word aligned, and begins with a two-word
4376 header. The first word, initialized to 0, is used in maintaining linked
4377 lists of branch tables. The second word is a count of the number of
4378 entries in the table, which follow immediately: each is a word, pointing
4379 to one of the labels illustrated above.
4383 @c END TEXI2ROFF-KILL
4385 +------------+------------+------------+ ... +------------+
4387 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
4389 +------------+------------+------------+ ... +------------+
4391 __BRANCH_TABLE__ layout
4397 \line{\leftskip=0pt\hskip\tableindent
4398 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
4399 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
4400 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
4402 @c END TEXI2ROFF-KILL
4404 The first word of the header is used to locate multiple branch tables,
4405 since each object file may contain one. Normally the links are
4406 maintained with a call to an initialization routine, placed at the
4407 beginning of each function in the file. The GNU C compiler will
4408 generate these calls automatically when you give it a @samp{-b} option.
4409 For further details, see the documentation of @samp{gbr960}.
4412 @cindex @code{-norelax} option, i960
4413 Normally, Compare-and-Branch instructions with targets that require
4414 displacements greater than 13 bits (or that have external targets) are
4415 replaced with the corresponding compare (or @samp{chkbit}) and branch
4416 instructions. You can use the @samp{-norelax} option to specify that
4417 @code{@value{as}} should generate errors instead, if the target displacement
4418 is larger than 13 bits.
4420 This option does not affect the Compare-and-Jump instructions; the code
4421 emitted for them is @emph{always} adjusted when necessary (depending on
4422 displacement size), regardless of whether you use @samp{-norelax}.
4425 @node Floating Point-i960
4426 _CHAPSEC__(1+_GENERIC__) Floating Point
4428 @cindex floating point, i960 (@sc{ieee})
4429 @cindex i960 floating point (@sc{ieee})
4430 @code{@value{as}} generates @sc{ieee} floating-point numbers for the directives
4431 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
4433 @node Directives-i960
4434 _CHAPSEC__(1+_GENERIC__) i960 Machine Directives
4436 @cindex machine directives, i960
4437 @cindex i960 machine directives
4440 @cindex @code{bss} directive, i960
4441 @item .bss @var{symbol}, @var{length}, @var{align}
4442 Reserve @var{length} bytes in the bss section for a local @var{symbol},
4443 aligned to the power of two specified by @var{align}. @var{length} and
4444 @var{align} must be positive absolute expressions. This directive
4445 differs from @samp{.lcomm} only in that it permits you to specify
4446 an alignment. @xref{Lcomm,,@code{.lcomm}}.
4450 @item .extended @var{flonums}
4451 @cindex @code{extended} directive, i960
4452 @code{.extended} expects zero or more flonums, separated by commas; for
4453 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
4454 floating-point number.
4456 @item .leafproc @var{call-lab}, @var{bal-lab}
4457 @cindex @code{leafproc} directive, i960
4458 You can use the @samp{.leafproc} directive in conjunction with the
4459 optimized @code{callj} instruction to enable faster calls of leaf
4460 procedures. If a procedure is known to call no other procedures, you
4461 may define an entry point that skips procedure prolog code (and that does
4462 not depend on system-supplied saved context), and declare it as the
4463 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
4464 entry point that goes through the normal prolog, you can specify that
4465 entry point as @var{call-lab}.
4467 A @samp{.leafproc} declaration is meant for use in conjunction with the
4468 optimized call instruction @samp{callj}; the directive records the data
4469 needed later to choose between converting the @samp{callj} into a
4470 @code{bal} or a @code{call}.
4472 @var{call-lab} is optional; if only one argument is present, or if the
4473 two arguments are identical, the single argument is assumed to be the
4474 @code{bal} entry point.
4476 @item .sysproc @var{name}, @var{index}
4477 @cindex @code{sysproc} directive, i960
4478 The @samp{.sysproc} directive defines a name for a system procedure.
4479 After you define it using @samp{.sysproc}, you can use @var{name} to
4480 refer to the system procedure identified by @var{index} when calling
4481 procedures with the optimized call instruction @samp{callj}.
4483 Both arguments are required; @var{index} must be between 0 and 31
4487 @node Opcodes for i960
4488 _CHAPSEC__(1+_GENERIC__) i960 Opcodes
4490 @cindex opcodes, i960
4491 @cindex i960 opcodes
4492 All Intel 960 machine instructions are supported;
4493 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
4494 selecting the instruction subset for a particular 960
4495 architecture.@refill
4497 Some opcodes are processed beyond simply emitting a single corresponding
4498 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
4499 instructions with target displacements larger than 13 bits.
4502 * callj-i960:: @code{callj}
4503 * Compare-and-branch-i960:: Compare-and-Branch
4507 _CHAPSEC__(2+_GENERIC__) @code{callj}
4509 @cindex @code{callj}, i960 pseudo-opcode
4510 @cindex i960 @code{callj} pseudo-opcode
4511 You can write @code{callj} to have the assembler or the linker determine
4512 the most appropriate form of subroutine call: @samp{call},
4513 @samp{bal}, or @samp{calls}. If the assembly source contains
4514 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
4515 defining the operand---then @code{@value{as}} will translate the
4516 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
4517 for the linker to resolve.
4519 @node Compare-and-branch-i960
4520 _CHAPSEC__(2+_GENERIC__) Compare-and-Branch
4522 @cindex i960 compare/branch instructions
4523 @cindex compare/branch instructions, i960
4524 The 960 architectures provide combined Compare-and-Branch instructions
4525 that permit you to store the branch target in the lower 13 bits of the
4526 instruction word itself. However, if you specify a branch target far
4527 enough away that its address won't fit in 13 bits, the assembler can
4528 either issue an error, or convert your Compare-and-Branch instruction
4529 into separate instructions to do the compare and the branch.
4531 @cindex compare and jump expansions, i960
4532 @cindex i960 compare and jump expansions
4533 Whether @code{@value{as}} gives an error or expands the instruction depends
4534 on two choices you can make: whether you use the @samp{-norelax} option,
4535 and whether you use a ``Compare and Branch'' instruction or a ``Compare
4536 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
4537 expanded if necessary; the ``Branch'' instructions are expanded when
4538 necessary @emph{unless} you specify @code{-norelax}---in which case
4539 @code{@value{as}} gives an error instead.
4541 These are the Compare-and-Branch instructions, their ``Jump'' variants,
4542 and the instruction pairs they may expand into:
4546 @c END TEXI2ROFF-KILL
4549 Branch Jump Expanded to
4550 ------ ------ ------------
4553 cmpibe cmpije cmpi; be
4554 cmpibg cmpijg cmpi; bg
4555 cmpibge cmpijge cmpi; bge
4556 cmpibl cmpijl cmpi; bl
4557 cmpible cmpijle cmpi; ble
4558 cmpibno cmpijno cmpi; bno
4559 cmpibne cmpijne cmpi; bne
4560 cmpibo cmpijo cmpi; bo
4561 cmpobe cmpoje cmpo; be
4562 cmpobg cmpojg cmpo; bg
4563 cmpobge cmpojge cmpo; bge
4564 cmpobl cmpojl cmpo; bl
4565 cmpoble cmpojle cmpo; ble
4566 cmpobne cmpojne cmpo; bne
4572 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
4573 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
4574 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
4575 bbc& & chkbit; bno\cr
4576 bbs& & chkbit; bo\cr
4577 cmpibe& cmpije& cmpi; be\cr
4578 cmpibg& cmpijg& cmpi; bg\cr
4579 cmpibge& cmpijge& cmpi; bge\cr
4580 cmpibl& cmpijl& cmpi; bl\cr
4581 cmpible& cmpijle& cmpi; ble\cr
4582 cmpibno& cmpijno& cmpi; bno\cr
4583 cmpibne& cmpijne& cmpi; bne\cr
4584 cmpibo& cmpijo& cmpi; bo\cr
4585 cmpobe& cmpoje& cmpo; be\cr
4586 cmpobg& cmpojg& cmpo; bg\cr
4587 cmpobge& cmpojge& cmpo; bge\cr
4588 cmpobl& cmpojl& cmpo; bl\cr
4589 cmpoble& cmpojle& cmpo; ble\cr
4590 cmpobne& cmpojne& cmpo; bne\cr}
4592 @c END TEXI2ROFF-KILL
4597 @node M68K-Dependent
4599 _CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features
4601 @cindex M680x0 support
4603 * M68K-Opts:: M680x0 Options
4604 * M68K-Syntax:: Syntax
4605 * M68K-Float:: Floating Point
4606 * M68K-Directives:: 680x0 Machine Directives
4607 * M68K-opcodes:: Opcodes
4611 _CHAPSEC__(1+_GENERIC__) M680x0 Options
4613 @cindex options, M680x0
4614 @cindex M680x0 options
4615 The Motorola 680x0 version of @code{@value{as}} has two machine dependent options.
4616 One shortens undefined references from 32 to 16 bits, while the
4617 other is used to tell @code{@value{as}} what kind of machine it is
4620 @cindex @code{-l} option, M680x0
4621 You can use the @kbd{-l} option to shorten the size of references to
4622 undefined symbols. If the @kbd{-l} option is not given, references to
4623 undefined symbols will be a full long (32 bits) wide. (Since @code{@value{as}}
4624 cannot know where these symbols will end up, @code{@value{as}} can only allocate
4625 space for the linker to fill in later. Since @code{@value{as}} doesn't know how
4626 far away these symbols will be, it allocates as much space as it can.)
4627 If this option is given, the references will only be one word wide (16
4628 bits). This may be useful if you want the object file to be as small as
4629 possible, and you know that the relevant symbols will be less than 17
4632 @cindex @code{-m68000} and related options
4633 @cindex architecture options, M680x0
4634 @cindex M680x0 architecture options
4635 The 680x0 version of @code{@value{as}} is most frequently used to assemble
4636 programs for the Motorola MC68020 microprocessor. Occasionally it is
4637 used to assemble programs for the mostly similar, but slightly different
4638 MC68000 or MC68010 microprocessors. You can give @code{@value{as}} the options
4639 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
4640 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
4644 _CHAPSEC__(1+_GENERIC__) Syntax
4646 @cindex M680x0 syntax
4647 @cindex syntax, M680x0
4648 @cindex M680x0 size modifiers
4649 @cindex size modifiers, M680x0
4650 The 680x0 version of @code{@value{as}} uses syntax similar to the Sun assembler.
4651 Size modifiers are appended directly to the end of the opcode without an
4652 intervening period. For example, write @samp{movl} rather than
4656 If @code{@value{as}} is compiled with SUN_ASM_SYNTAX defined, it will also allow
4657 Sun-style local labels of the form @samp{1$} through @samp{$9}.
4660 In the following table @dfn{apc} stands for any of the address
4661 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
4662 Program Counter (@samp{pc}), or the zero-address relative to the
4663 program counter (@samp{zpc}).
4665 @cindex M680x0 addressing modes
4666 @cindex addressing modes, M680x0
4667 The following addressing modes are understood:
4670 @samp{#@var{digits}}
4673 @samp{d0} through @samp{d7}
4675 @item Address Register
4676 @samp{a0} through @samp{a7}
4678 @item Address Register Indirect
4679 @samp{a0@@} through @samp{a7@@}
4681 @item Address Register Postincrement
4682 @samp{a0@@+} through @samp{a7@@+}
4684 @item Address Register Predecrement
4685 @samp{a0@@-} through @samp{a7@@-}
4687 @item Indirect Plus Offset
4688 @samp{@var{apc}@@(@var{digits})}
4691 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4693 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
4696 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4698 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
4701 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4703 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4705 @item Memory Indirect
4706 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
4709 @samp{@var{symbol}}, or @samp{@var{digits}}
4711 @c pesch@cygnus.com: gnu, rich concur the following needs careful
4712 @c research before documenting.
4713 , or either of the above followed
4714 by @samp{:b}, @samp{:w}, or @samp{:l}.
4719 _CHAPSEC__(1+_GENERIC__) Floating Point
4721 @cindex floating point, M680x0
4722 @cindex M680x0 floating point
4723 @c FIXME is this "not too well tested" crud STILL true?
4724 The floating point code is not too well tested, and may have
4727 Packed decimal (P) format floating literals are not supported.
4728 Feel free to add the code!
4730 The floating point formats generated by directives are these.
4734 @cindex @code{float} directive, M680x0
4735 @code{Single} precision floating point constants.
4738 @cindex @code{double} directive, M680x0
4739 @code{Double} precision floating point constants.
4742 There is no directive to produce regions of memory holding
4743 extended precision numbers, however they can be used as
4744 immediate operands to floating-point instructions. Adding a
4745 directive to create extended precision numbers would not be
4746 hard, but it has not yet seemed necessary.
4748 @node M68K-Directives
4749 _CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives
4751 @cindex M680x0 directives
4752 @cindex directives, M680x0
4753 In order to be compatible with the Sun assembler the 680x0 assembler
4754 understands the following directives.
4758 @cindex @code{data1} directive, M680x0
4759 This directive is identical to a @code{.data 1} directive.
4762 @cindex @code{data2} directive, M680x0
4763 This directive is identical to a @code{.data 2} directive.
4766 @cindex @code{even} directive, M680x0
4767 This directive is identical to a @code{.align 1} directive.
4768 @c Is this true? does it work???
4771 @cindex @code{skip} directive, M680x0
4772 This directive is identical to a @code{.space} directive.
4776 _CHAPSEC__(1+_GENERIC__) Opcodes
4778 @cindex M680x0 opcodes
4779 @cindex opcodes, M680x0
4780 @cindex instruction set, M680x0
4781 @c pesch@cygnus.com: I don't see any point in the following
4782 @c paragraph. Bugs are bugs; how does saying this
4785 Danger: Several bugs have been found in the opcode table (and
4786 fixed). More bugs may exist. Be careful when using obscure
4791 * M68K-Branch:: Branch Improvement
4792 * M68K-Chars:: Special Characters
4796 _CHAPSEC__(2+_GENERIC__) Branch Improvement
4798 @cindex pseudo-opcodes, M680x0
4799 @cindex M680x0 pseudo-opcodes
4800 @cindex branch improvement, M680x0
4801 @cindex M680x0 branch improvement
4802 Certain pseudo opcodes are permitted for branch instructions.
4803 They expand to the shortest branch instruction that will reach the
4804 target. Generally these mnemonics are made by substituting @samp{j} for
4805 @samp{b} at the start of a Motorola mnemonic.
4807 The following table summarizes the pseudo-operations. A @code{*} flags
4808 cases that are more fully described after the table:
4812 +-------------------------------------------------
4814 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
4815 +-------------------------------------------------
4816 jbsr |bsrs bsr bsrl jsr jsr
4817 jra |bras bra bral jmp jmp
4818 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
4819 * dbXX |dbXX dbXX dbXX; bra; jmpl
4820 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
4823 NX: negative of condition XX
4826 @center @code{*}---see full description below
4831 These are the simplest jump pseudo-operations; they always map to one
4832 particular machine instruction, depending on the displacement to the
4836 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
4837 where @var{XX} is a conditional branch or condition-code test. The full
4838 list of pseudo-ops in this family is:
4840 jhi jls jcc jcs jne jeq jvc
4841 jvs jpl jmi jge jlt jgt jle
4844 For the cases of non-PC relative displacements and long displacements on
4845 the 68000 or 68010, @code{@value{as}} will issue a longer code fragment in terms of
4846 @var{NX}, the opposite condition to @var{XX}. For example, for the
4847 non-PC relative case:
4859 The full family of pseudo-operations covered here is
4861 dbhi dbls dbcc dbcs dbne dbeq dbvc
4862 dbvs dbpl dbmi dbge dblt dbgt dble
4866 Other than for word and byte displacements, when the source reads
4867 @samp{db@var{XX} foo}, @code{@value{as}} will emit
4876 This family includes
4878 fjne fjeq fjge fjlt fjgt fjle fjf
4879 fjt fjgl fjgle fjnge fjngl fjngle fjngt
4880 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
4881 fjor fjseq fjsf fjsne fjst fjueq fjuge
4882 fjugt fjule fjult fjun
4885 For branch targets that are not PC relative, @code{@value{as}} emits
4891 when it encounters @samp{fj@var{XX} foo}.
4896 _CHAPSEC__(2+_GENERIC__) Special Characters
4898 @cindex special characters, M680x0
4899 @cindex M680x0 immediate character
4900 @cindex immediate character, M680x0
4901 @cindex M680x0 line comment character
4902 @cindex line comment character, M680x0
4903 @cindex comments, M680x0
4904 The immediate character is @samp{#} for Sun compatibility. The
4905 line-comment character is @samp{|}. If a @samp{#} appears at the
4906 beginning of a line, it is treated as a comment unless it looks like
4907 @samp{# line file}, in which case it is treated normally.
4911 @c pesch@cygnus.com: conditionalize on something other than 0 when filled in.
4914 The 32x32 version of @code{@value{as}} accepts a @kbd{-m32032} option to
4915 specify thiat it is compiling for a 32032 processor, or a
4916 @kbd{-m32532} to specify that it is compiling for a 32532 option.
4917 The default (if neither is specified) is chosen when the assembler
4921 I don't know anything about the 32x32 syntax assembled by
4922 @code{@value{as}}. Someone who undersands the processor (I've never seen
4923 one) and the possible syntaxes should write this section.
4925 @subsection Floating Point
4926 The 32x32 uses @sc{ieee} floating point numbers, but @code{@value{as}} will only
4927 create single or double precision values. I don't know if the 32x32
4928 understands extended precision numbers.
4930 @subsection 32x32 Machine Directives
4931 The 32x32 has no machine dependent directives.
4936 @node Sparc-Dependent
4938 _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features
4940 @cindex SPARC support
4942 * Sparc-Opts:: Options
4943 * Sparc-Float:: Floating Point
4944 * Sparc-Directives:: Sparc Machine Directives
4948 _CHAPSEC__(1+_GENERIC__) Options
4950 @cindex options for SPARC (none)
4951 @cindex SPARC options (none)
4952 The Sparc has no machine dependent options.
4955 @c FIXME: (sparc) Fill in "syntax" section!
4956 @c subsection syntax
4957 I don't know anything about Sparc syntax. Someone who does
4958 will have to write this section.
4962 _CHAPSEC__(1+_GENERIC__) Floating Point
4964 @cindex floating point, SPARC (@sc{ieee})
4965 @cindex SPARC floating point (@sc{ieee})
4966 The Sparc uses @sc{ieee} floating-point numbers.
4968 @node Sparc-Directives
4969 _CHAPSEC__(1+_GENERIC__) Sparc Machine Directives
4971 @cindex SPARC machine directives
4972 @cindex machine directives, SPARC
4973 The Sparc version of @code{@value{as}} supports the following additional
4978 @cindex @code{common} directive, SPARC
4979 This must be followed by a symbol name, a positive number, and
4980 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
4981 syntax is different.
4984 @cindex @code{half} directive, SPARC
4985 This is functionally identical to @code{.short}.
4988 @cindex @code{proc} directive, SPARC
4989 This directive is ignored. Any text following it on the same
4990 line is also ignored.
4993 @cindex @code{reserve} directive, SPARC
4994 This must be followed by a symbol name, a positive number, and
4995 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
4996 syntax is different.
4999 @cindex @code{seg} directive, SPARC
5000 This must be followed by @code{"text"}, @code{"data"}, or
5001 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
5005 @cindex @code{skip} directive, SPARC
5006 This is functionally identical to the @code{.space} directive.
5009 @cindex @code{word} directive, SPARC
5010 On the Sparc, the .word directive produces 32 bit values,
5011 instead of the 16 bit values it produces on many other machines.
5017 @node i386-Dependent
5019 _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features
5021 @cindex i386 support
5022 @cindex i80306 support
5024 * i386-Options:: Options
5025 * i386-Syntax:: AT&T Syntax versus Intel Syntax
5026 * i386-Opcodes:: Opcode Naming
5027 * i386-Regs:: Register Naming
5028 * i386-prefixes:: Opcode Prefixes
5029 * i386-Memory:: Memory References
5030 * i386-jumps:: Handling of Jump Instructions
5031 * i386-Float:: Floating Point
5032 * i386-Notes:: Notes
5036 _CHAPSEC__(1+_GENERIC__) Options
5038 @cindex options for i386 (none)
5039 @cindex i386 options (none)
5040 The 80386 has no machine dependent options.
5043 _CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax
5045 @cindex i386 syntax compatibility
5046 @cindex syntax compatibility, i386
5047 In order to maintain compatibility with the output of @code{_GCC__},
5048 @code{@value{as}} supports AT&T System V/386 assembler syntax. This is quite
5049 different from Intel syntax. We mention these differences because
5050 almost all 80386 documents used only Intel syntax. Notable differences
5051 between the two syntaxes are:
5055 @cindex immediate operands, i386
5056 @cindex i386 immediate operands
5057 @cindex register operands, i386
5058 @cindex i386 register operands
5059 @cindex jump/call operands, i386
5060 @cindex i386 jump/call operands
5061 @cindex operand delimiters, i386
5062 AT&T immediate operands are preceded by @samp{$}; Intel immediate
5063 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
5064 AT&T register operands are preceded by @samp{%}; Intel register operands
5065 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
5066 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
5069 @cindex i386 source, destination operands
5070 @cindex source, destination operands; i386
5071 AT&T and Intel syntax use the opposite order for source and destination
5072 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
5073 @samp{source, dest} convention is maintained for compatibility with
5074 previous Unix assemblers.
5077 @cindex opcode suffixes, i386
5078 @cindex sizes operands, i386
5079 @cindex i386 size suffixes
5080 In AT&T syntax the size of memory operands is determined from the last
5081 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
5082 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
5083 memory references. Intel syntax accomplishes this by prefixes memory
5084 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
5085 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
5086 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
5089 @cindex return instructions, i386
5090 @cindex i386 jump, call, return
5091 Immediate form long jumps and calls are
5092 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
5094 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
5096 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
5097 @samp{ret far @var{stack-adjust}}.
5100 @cindex sections, i386
5101 @cindex i386 sections
5102 The AT&T assembler does not provide support for multiple section
5103 programs. Unix style systems expect all programs to be single sections.
5107 _CHAPSEC__(1+_GENERIC__) Opcode Naming
5109 @cindex i386 opcode naming
5110 @cindex opcode naming, i386
5111 Opcode names are suffixed with one character modifiers which specify the
5112 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
5113 byte, word, and long operands. If no suffix is specified by an
5114 instruction and it contains no memory operands then @code{@value{as}} tries to
5115 fill in the missing suffix based on the destination register operand
5116 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
5117 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
5118 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
5119 assembler which assumes that a missing opcode suffix implies long
5120 operand size. (This incompatibility does not affect compiler output
5121 since compilers always explicitly specify the opcode suffix.)
5123 Almost all opcodes have the same names in AT&T and Intel format. There
5124 are a few exceptions. The sign extend and zero extend instructions need
5125 two sizes to specify them. They need a size to sign/zero extend
5126 @emph{from} and a size to zero extend @emph{to}. This is accomplished
5127 by using two opcode suffixes in AT&T syntax. Base names for sign extend
5128 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
5129 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
5130 suffixes are tacked on to this base name, the @emph{from} suffix before
5131 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
5132 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
5133 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
5134 and @samp{wl} (from word to long).
5136 @cindex conversion instructions, i386
5137 @cindex i386 conversion instructions
5138 The Intel-syntax conversion instructions
5142 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
5145 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
5148 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
5151 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
5155 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
5156 AT&T naming. @code{@value{as}} accepts either naming for these instructions.
5158 @cindex jump instructions, i386
5159 @cindex call instructions, i386
5160 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
5161 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
5165 _CHAPSEC__(1+_GENERIC__) Register Naming
5167 @cindex i386 registers
5168 @cindex registers, i386
5169 Register operands are always prefixes with @samp{%}. The 80386 registers
5174 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
5175 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
5176 frame pointer), and @samp{%esp} (the stack pointer).
5179 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
5180 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
5183 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
5184 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
5185 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
5186 @samp{%cx}, and @samp{%dx})
5189 the 6 section registers @samp{%cs} (code section), @samp{%ds}
5190 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
5194 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
5198 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
5199 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
5202 the 2 test registers @samp{%tr6} and @samp{%tr7}.
5205 the 8 floating point register stack @samp{%st} or equivalently
5206 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
5207 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
5211 _CHAPSEC__(1+_GENERIC__) Opcode Prefixes
5213 @cindex i386 opcode prefixes
5214 @cindex opcode prefixes, i386
5215 @cindex prefixes, i386
5216 Opcode prefixes are used to modify the following opcode. They are used
5217 to repeat string instructions, to provide section overrides, to perform
5218 bus lock operations, and to give operand and address size (16-bit
5219 operands are specified in an instruction by prefixing what would
5220 normally be 32-bit operands with a ``operand size'' opcode prefix).
5221 Opcode prefixes are usually given as single-line instructions with no
5222 operands, and must directly precede the instruction they act upon. For
5223 example, the @samp{scas} (scan string) instruction is repeated with:
5229 Here is a list of opcode prefixes:
5233 @cindex section override prefixes, i386
5234 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
5235 @samp{fs}, @samp{gs}. These are automatically added by specifying
5236 using the @var{section}:@var{memory-operand} form for memory references.
5239 @cindex size prefixes, i386
5240 Operand/Address size prefixes @samp{data16} and @samp{addr16}
5241 change 32-bit operands/addresses into 16-bit operands/addresses. Note
5242 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
5243 are not supported (yet).
5246 @cindex bus lock prefixes, i386
5247 @cindex inhibiting interrupts, i386
5248 The bus lock prefix @samp{lock} inhibits interrupts during
5249 execution of the instruction it precedes. (This is only valid with
5250 certain instructions; see a 80386 manual for details).
5253 @cindex coprocessor wait, i386
5254 The wait for coprocessor prefix @samp{wait} waits for the
5255 coprocessor to complete the current instruction. This should never be
5256 needed for the 80386/80387 combination.
5259 @cindex repeat prefixes, i386
5260 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
5261 to string instructions to make them repeat @samp{%ecx} times.
5265 _CHAPSEC__(1+_GENERIC__) Memory References
5267 @cindex i386 memory references
5268 @cindex memory references, i386
5269 An Intel syntax indirect memory reference of the form
5272 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
5276 is translated into the AT&T syntax
5279 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
5283 where @var{base} and @var{index} are the optional 32-bit base and
5284 index registers, @var{disp} is the optional displacement, and
5285 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
5286 to calculate the address of the operand. If no @var{scale} is
5287 specified, @var{scale} is taken to be 1. @var{section} specifies the
5288 optional section register for the memory operand, and may override the
5289 default section register (see a 80386 manual for section register
5290 defaults). Note that section overrides in AT&T syntax @emph{must} have
5291 be preceded by a @samp{%}. If you specify a section override which
5292 coincides with the default section register, @code{@value{as}} will @emph{not}
5293 output any section register override prefixes to assemble the given
5294 instruction. Thus, section overrides can be specified to emphasize which
5295 section register is used for a given memory operand.
5297 Here are some examples of Intel and AT&T style memory references:
5300 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
5301 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
5302 missing, and the default section is used (@samp{%ss} for addressing with
5303 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
5305 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
5306 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
5307 @samp{foo}. All other fields are missing. The section register here
5308 defaults to @samp{%ds}.
5310 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
5311 This uses the value pointed to by @samp{foo} as a memory operand.
5312 Note that @var{base} and @var{index} are both missing, but there is only
5313 @emph{one} @samp{,}. This is a syntactic exception.
5315 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
5316 This selects the contents of the variable @samp{foo} with section
5317 register @var{section} being @samp{%gs}.
5320 Absolute (as opposed to PC relative) call and jump operands must be
5321 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{as}} will
5322 always choose PC relative addressing for jump/call labels.
5324 Any instruction that has a memory operand @emph{must} specify its size (byte,
5325 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
5329 _CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions
5331 @cindex jump optimization, i386
5332 @cindex i386 jump optimization
5333 Jump instructions are always optimized to use the smallest possible
5334 displacements. This is accomplished by using byte (8-bit) displacement
5335 jumps whenever the target is sufficiently close. If a byte displacement
5336 is insufficient a long (32-bit) displacement is used. We do not support
5337 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
5338 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
5339 @samp{%eip} to 16 bits after the word displacement is added.
5341 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
5342 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
5343 byte displacements, so that it is possible that use of these
5344 instructions (@code{_GCC__} does not use them) will cause the assembler to
5345 print an error message (and generate incorrect code). The AT&T 80386
5346 assembler tries to get around this problem by expanding @samp{jcxz foo} to
5355 _CHAPSEC__(1+_GENERIC__) Floating Point
5357 @cindex i386 floating point
5358 @cindex floating point, i386
5359 All 80387 floating point types except packed BCD are supported.
5360 (BCD support may be added without much difficulty). These data
5361 types are 16-, 32-, and 64- bit integers, and single (32-bit),
5362 double (64-bit), and extended (80-bit) precision floating point.
5363 Each supported type has an opcode suffix and a constructor
5364 associated with it. Opcode suffixes specify operand's data
5365 types. Constructors build these data types into memory.
5369 @cindex @code{float} directive, i386
5370 @cindex @code{single} directive, i386
5371 @cindex @code{double} directive, i386
5372 @cindex @code{tfloat} directive, i386
5373 Floating point constructors are @samp{.float} or @samp{.single},
5374 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
5375 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
5376 @samp{t} stands for temporary real, and that the 80387 only supports
5377 this format via the @samp{fldt} (load temporary real to stack top) and
5378 @samp{fstpt} (store temporary real and pop stack) instructions.
5381 @cindex @code{word} directive, i386
5382 @cindex @code{long} directive, i386
5383 @cindex @code{int} directive, i386
5384 @cindex @code{quad} directive, i386
5385 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
5386 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
5387 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
5388 (quad). As with the temporary real format the 64-bit @samp{q} format is
5389 only present in the @samp{fildq} (load quad integer to stack top) and
5390 @samp{fistpq} (store quad integer and pop stack) instructions.
5393 Register to register operations do not require opcode suffixes,
5394 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
5396 @cindex i386 @code{fwait} instruction
5397 @cindex @code{fwait instruction}, i386
5398 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
5399 instructions are almost never needed (this is not the case for the
5400 80286/80287 and 8086/8087 combinations). Therefore, @code{@value{as}} suppresses
5401 the @samp{fwait} instruction whenever it is implicitly selected by one
5402 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
5403 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
5404 instructions are made equivalent to @samp{f@dots{}} instructions. If
5405 @samp{fwait} is desired it must be explicitly coded.
5408 _CHAPSEC__(1+_GENERIC__) Notes
5410 @cindex i386 @code{mul}, @code{imul} instructions
5411 @cindex @code{mul} instruction, i386
5412 @cindex @code{imul} instruction, i386
5413 There is some trickery concerning the @samp{mul} and @samp{imul}
5414 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
5415 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
5416 for @samp{imul}) can be output only in the one operand form. Thus,
5417 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
5418 the expanding multiply would clobber the @samp{%edx} register, and this
5419 would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the
5420 64-bit product in @samp{%edx:%eax}.
5422 We have added a two operand form of @samp{imul} when the first operand
5423 is an immediate mode expression and the second operand is a register.
5424 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
5425 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
5431 @node Z8000-Dependent
5433 _CHAPSEC__(0+_GENERIC__) Z8000 Dependent Features
5435 @cindex Z8000 support
5436 The Z8000 @value{as} supports both members of the Z8000 family: the
5437 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
5440 When the assembler is in unsegmented mode (specified with the
5441 @code{unsegm} directive), an address will take up one word (16 bit)
5442 sized register. When the assembler is in segmented mode (specified with
5443 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
5444 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
5445 for a list of other Z8000 specific assembler directives.
5448 * Z8000 Options:: No special command-line options for Z8000
5449 * Z8000 Syntax:: Assembler syntax for the Z8000
5450 * Z8000 Directives:: Special directives for the Z8000
5451 * Z8000 Opcodes:: Opcodes
5455 _CHAPSEC__(1+_GENERIC__) Options
5457 @cindex Z8000 options
5458 @cindex options, Z8000
5459 @code{@value{as}} has no additional command-line options for the Zilog
5463 _CHAPSEC__(1+_GENERIC__) Syntax
5465 * Z8000-Chars:: Special Characters
5466 * Z8000-Regs:: Register Names
5467 * Z8000-Addressing:: Addressing Modes
5471 _CHAPSEC__(2+_GENERIC__) Special Characters
5473 @cindex line comment character, Z8000
5474 @cindex Z8000 line comment character
5475 @samp{!} is the line comment character.
5477 @cindex line separator, Z8000
5478 @cindex statement separator, Z8000
5479 @cindex Z8000 line separator
5480 You can use @samp{;} instead of a newline to separate statements.
5483 _CHAPSEC__(2+_GENERIC__) Register Names
5485 @cindex Z8000 registers
5486 @cindex registers, Z8000
5487 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
5488 to different sized groups of registers by register number, with the
5489 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
5490 @samp{rq} for 64 bit registers. You can also refer to the contents of
5491 the first eight (of the sixteen 16 bit registers) by bytes. They are
5492 named @samp{r@var{n}h} and @samp{r@var{n}l}.
5495 @exdent @emph{byte registers}
5496 r0l r0h r1h r1l r2h r2l r3h r3l
5497 r4h r4l r5h r5l r6h r6l r7h r7l
5499 @exdent @emph{word registers}
5500 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
5502 @exdent @emph{long word registers}
5503 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
5505 @exdent @emph{quad word registers}
5509 @node Z8000-Addressing
5510 _CHAPSEC__(2+_GENERIC__) Addressing Modes
5512 @cindex addressing modes, Z8000
5513 @cindex Z800 addressing modes
5514 @value{as} understands the following addressing modes for the Z8000:
5524 Direct: the 16 bit or 24 bit address (depending on whether the assembler
5525 is in segmented or unsegmented mode) of the operand is in the instruction.
5527 @item address(r@var{n})
5528 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
5529 the final address in memory of the operand.
5531 @item r@var{n}(#@var{imm})
5532 Base Address: the 16 or 24 bit register is added to the 16 bit sign
5533 extended immediate displacement to produce the final address in memory
5536 @item r@var{n}(r@var{m})
5537 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
5538 extended 16 bit index register r@var{m} to produce the final address in
5539 memory of the operand.
5542 Immediate data @var{xx}.
5545 @node Z8000 Directives
5546 _CHAPSEC__(1+_GENERIC__) Assembler Directives for the Z8000
5548 @cindex Z8000 directives
5549 @cindex directives, Z8000
5550 The Z8000 port of @value{as} includes these additional assembler directives,
5551 for compatibility with other Z8000 assemblers. As shown, these do not
5552 begin with @samp{.} (unlike the ordinary @value{as} directives).
5557 Generates code for the segmented Z8001.
5561 Generates code for the unsegmented Z8002.
5565 Synonym for @code{.file}
5569 Synonum for @code{.global}
5573 Synonym for @code{.word}
5577 Synonym for @code{.long}
5581 Synonym for @code{.byte}
5585 Assemble a string. @code{sval} expects one string literal, delimited by
5586 single quotes. It assembles each byte of the string into consecutive
5587 addresses. You can use the escape sequence @samp{%@var{xx}} (where
5588 @var{xx} represents a two-digit hexadecimal number) to represent the
5589 character whose @sc{ascii} value is @var{xx}. Use this feature to
5590 describe single quote and other characters that may not appear in string
5591 literals as themselves. For example, the C statement @w{@samp{char *a =
5592 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
5593 (shown with the assembler output in hex at the left) as
5597 @let@nonarrowing=@comment
5600 68652073 sval 'he said %22it%27s 50%25 off%22%00'
5613 synonym for @code{.section}
5617 synonym for @code{.space}
5621 synonym for @code{.align 1}
5625 _CHAPSEC__(1+_GENERIC__) Opcodes
5627 @cindex Z8000 opcode summary
5628 @cindex opcode summary, Z8000
5629 @cindex mnemonics, Z8000
5630 @cindex instruction summary, Z8000
5631 For detailed information on the Z8000 machine instruction set, see
5632 @cite{Z8000 Technical Manual}.
5634 The following table summarizes the opcodes and their arguments:
5637 @let@nonarrowing=@comment
5641 rs @r{16 bit source register}
5642 rd @r{16 bit destination register}
5643 rbs @r{8 bit source register}
5644 rbd @r{8 bit destination register}
5645 rrs @r{32 bit source register}
5646 rrd @r{32 bit destination register}
5647 rqs @r{64 bit source register}
5648 rqd @r{64 bit destination register}
5649 addr @r{16/24 bit address}
5650 imm @r{immediate data}
5652 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
5653 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
5654 add rd,@@rs clrb rbd dab rbd
5655 add rd,addr com @@rd dbjnz rbd,disp7
5656 add rd,addr(rs) com addr dec @@rd,imm4m1
5657 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
5658 add rd,rs com rd dec addr,imm4m1
5659 addb rbd,@@rs comb @@rd dec rd,imm4m1
5660 addb rbd,addr comb addr decb @@rd,imm4m1
5661 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
5662 addb rbd,imm8 comb rbd decb addr,imm4m1
5663 addb rbd,rbs comflg flags decb rbd,imm4m1
5664 addl rrd,@@rs cp @@rd,imm16 di i2
5665 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
5666 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
5667 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
5668 addl rrd,rrs cp rd,addr div rrd,imm16
5669 and rd,@@rs cp rd,addr(rs) div rrd,rs
5670 and rd,addr cp rd,imm16 divl rqd,@@rs
5671 and rd,addr(rs) cp rd,rs divl rqd,addr
5672 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
5673 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
5674 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
5675 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
5676 andb rbd,addr(rs) cpb rbd,addr ei i2
5677 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
5678 andb rbd,rbs cpb rbd,imm8 ex rd,addr
5679 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
5680 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
5681 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
5682 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
5683 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
5684 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
5685 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
5686 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
5687 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
5688 bitb rbd,rs cpl rrd,@@rs ext8f imm8
5689 bpt cpl rrd,addr exts rrd
5690 call @@rd cpl rrd,addr(rs) extsb rd
5691 call addr cpl rrd,imm32 extsl rqd
5692 call addr(rd) cpl rrd,rrs halt
5693 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
5694 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
5695 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
5696 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
5697 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
5698 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
5699 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
5700 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
5701 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
5702 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
5703 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
5704 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
5705 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
5706 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
5707 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
5708 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
5709 iret ldib @@rd,@@rs,rr neg addr(rd)
5710 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
5711 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
5712 jp cc,addr(rd) ldk rd,imm4 negb addr
5713 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
5714 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
5715 ld @@rd,rs ldl addr,rrs nop
5716 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
5717 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
5718 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
5719 ld addr,rs ldl rrd,addr or rd,imm16
5720 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
5721 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
5722 ld rd,@@rs ldl rrd,rrs orb rbd,addr
5723 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
5724 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
5725 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
5726 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
5727 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
5728 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
5729 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
5730 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
5731 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
5732 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
5733 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
5734 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
5735 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
5736 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
5737 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
5738 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
5739 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
5740 ldb rbd,@@rs mbit popl addr,@@rs
5741 ldb rbd,addr mreq rd popl rrd,@@rs
5742 ldb rbd,addr(rs) mres push @@rd,@@rs
5743 ldb rbd,imm8 mset push @@rd,addr
5744 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
5745 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
5746 push @@rd,rs set addr,imm4 subl rrd,imm32
5747 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
5748 pushl @@rd,addr set rd,rs tcc cc,rd
5749 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
5750 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
5751 res @@rd,imm4 setb addr,imm4 test addr
5752 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
5753 res addr,imm4 setb rbd,rs test rd
5754 res rd,imm4 setflg imm4 testb @@rd
5755 res rd,rs sinb rbd,imm16 testb addr
5756 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
5757 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
5758 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
5759 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
5760 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
5761 resflg imm4 sla rd,imm8 testl rrd
5762 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
5763 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
5764 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
5765 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
5766 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
5767 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
5768 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
5769 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
5770 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
5771 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
5772 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
5773 rsvd36 sra rd,imm8 tset rd
5774 rsvd38 srab rbd,imm8 tsetb @@rd
5775 rsvd78 sral rrd,imm8 tsetb addr
5776 rsvd7e srl rd,imm8 tsetb addr(rd)
5777 rsvd9d srlb rbd,imm8 tsetb rbd
5778 rsvd9f srll rrd,imm8 xor rd,@@rs
5779 rsvdb9 sub rd,@@rs xor rd,addr
5780 rsvdbf sub rd,addr xor rd,addr(rs)
5781 sbc rd,rs sub rd,addr(rs) xor rd,imm16
5782 sbcb rbd,rbs sub rd,imm16 xor rd,rs
5783 sc imm8 sub rd,rs xorb rbd,@@rs
5784 sda rd,rs subb rbd,@@rs xorb rbd,addr
5785 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
5786 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
5787 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
5788 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
5789 sdll rrd,rs subl rrd,@@rs
5790 set @@rd,imm4 subl rrd,addr
5791 set addr(rd),imm4 subl rrd,addr(rs)
5799 @c pesch@cygnus.com: we ignore the following chapters, since internals are
5800 @c changing rapidly. These may need to be moved to another
5801 @c book anyhow, if we adopt the model of user/modifier
5804 @chapter Maintaining the Assembler
5805 [[this chapter is still being built]]
5808 We had these goals, in descending priority:
5811 For every program composed by a compiler, @code{@value{as}} should emit
5812 ``correct'' code. This leaves some latitude in choosing addressing
5813 modes, order of @code{relocation_info} structures in the object
5816 @item Speed, for usual case.
5817 By far the most common use of @code{@value{as}} will be assembling compiler
5820 @item Upward compatibility for existing assembler code.
5821 Well @dots{} we don't support Vax bit fields but everything else
5822 seems to be upward compatible.
5825 The code should be maintainable with few surprises. (JF: ha!)
5829 We assumed that disk I/O was slow and expensive while memory was
5830 fast and access to memory was cheap. We expect the in-memory data
5831 structures to be less than 10 times the size of the emitted object
5832 file. (Contrast this with the C compiler where in-memory structures
5833 might be 100 times object file size!)
5837 Try to read the source file from disk only one time. For other
5838 reasons, we keep large chunks of the source file in memory during
5839 assembly so this is not a problem. Also the assembly algorithm
5840 should only scan the source text once if the compiler composed the
5841 text according to a few simple rules.
5843 Emit the object code bytes only once. Don't store values and then
5846 Build the object file in memory and do direct writes to disk of
5850 RMS suggested a one-pass algorithm which seems to work well. By not
5851 parsing text during a second pass considerable time is saved on
5852 large programs (@emph{e.g.} the sort of C program @code{yacc} would
5855 It happened that the data structures needed to emit relocation
5856 information to the object file were neatly subsumed into the data
5857 structures that do backpatching of addresses after pass 1.
5859 Many of the functions began life as re-usable modules, loosely
5860 connected. RMS changed this to gain speed. For example, input
5861 parsing routines which used to work on pre-sanitized strings now
5862 must parse raw data. Hence they have to import knowledge of the
5863 assemblers' comment conventions @emph{etc}.
5865 @section Deprecated Feature(?)s
5866 We have stopped supporting some features:
5869 @code{.org} statements must have @b{defined} expressions.
5871 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
5874 It might be a good idea to not support these features in a future release:
5877 @kbd{#} should begin a comment, even in column 1.
5879 Why support the logical line & file concept any more?
5881 Subsections are a good candidate for flushing.
5882 Depends on which compilers need them I guess.
5885 @section Bugs, Ideas, Further Work
5886 Clearly the major improvement is DON'T USE A TEXT-READING
5887 ASSEMBLER for the back end of a compiler. It is much faster to
5888 interpret binary gobbledygook from a compiler's tables than to
5889 ask the compiler to write out human-readable code just so the
5890 assembler can parse it back to binary.
5892 Assuming you use @code{@value{as}} for human written programs: here are
5896 Document (here) @code{APP}.
5898 Take advantage of knowing no spaces except after opcode
5899 to speed up @code{@value{as}}. (Modify @code{app.c} to flush useless spaces:
5900 only keep space/tabs at begin of line or between 2
5903 Put pointers in this documentation to @file{a.out} documentation.
5905 Split the assembler into parts so it can gobble direct binary
5906 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
5907 just so @code{@value{as}} can parse it back to binary.
5909 Rewrite hash functions: I want a more modular, faster library.
5911 Clean up LOTS of code.
5913 Include all the non-@file{.c} files in the maintenance chapter.
5917 Implement flonum short literals.
5919 Change all talk of expression operands to expression quantities,
5920 or perhaps to expression arguments.
5924 Whenever a @code{.text} or @code{.data} statement is seen, we close
5925 of the current frag with an imaginary @code{.fill 0}. This is
5926 because we only have one obstack for frags, and we can't grow new
5927 frags for a new subsection, then go back to the old subsection and
5928 append bytes to the old frag. All this nonsense goes away if we
5929 give each subsection its own obstack. It makes code simpler in
5930 about 10 places, but nobody has bothered to do it because C compiler
5931 output rarely changes subsections (compared to ending frags with
5932 relaxable addresses, which is common).
5936 @c The following files in the @file{@value{as}} directory
5937 @c are symbolic links to other files, of
5938 @c the same name, in a different directory.
5941 @c @file{atof_generic.c}
5943 @c @file{atof_vax.c}
5945 @c @file{flonum_const.c}
5947 @c @file{flonum_copy.c}
5949 @c @file{flonum_get.c}
5951 @c @file{flonum_multip.c}
5953 @c @file{flonum_normal.c}
5955 @c @file{flonum_print.c}
5958 Here is a list of the source files in the @file{@value{as}} directory.
5962 This contains the pre-processing phase, which deletes comments,
5963 handles whitespace, etc. This was recently re-written, since app
5964 used to be a separate program, but RMS wanted it to be inline.
5967 This is a subroutine to append a string to another string returning a
5968 pointer just after the last @code{char} appended. (JF: All these
5969 little routines should probably all be put in one file.)
5972 Here you will find the main program of the assembler @code{@value{as}}.
5975 This is a branch office of @file{read.c}. This understands
5976 expressions, arguments. Inside @code{@value{as}}, arguments are called
5977 (expression) @emph{operands}. This is confusing, because we also talk
5978 (elsewhere) about instruction @emph{operands}. Also, expression
5979 operands are called @emph{quantities} explicitly to avoid confusion
5980 with instruction operands. What a mess.
5983 This implements the @b{frag} concept. Without frags, finding the
5984 right size for branch instructions would be a lot harder.
5987 This contains the symbol table, opcode table @emph{etc.} hashing
5991 This is a table of values of digits, for use in atoi() type
5992 functions. Could probably be flushed by using calls to strtol(), or
5996 This contains Operating system dependent source file reading
5997 routines. Since error messages often say where we are in reading
5998 the source file, they live here too. Since @code{@value{as}} is intended to
5999 run under GNU and Unix only, this might be worth flushing. Anyway,
6000 almost all C compilers support stdio.
6003 This deals with calling the pre-processor (if needed) and feeding the
6004 chunks back to the rest of the assembler the right way.
6007 This contains operating system independent parts of fatal and
6008 warning message reporting. See @file{append.c} above.
6011 This contains operating system dependent functions that write an
6012 object file for @code{@value{as}}. See @file{input-file.c} above.
6015 This implements all the directives of @code{@value{as}}. This also deals
6016 with passing input lines to the machine dependent part of the
6020 This is a C library function that isn't in most C libraries yet.
6021 See @file{append.c} above.
6024 This implements subsections.
6027 This implements symbols.
6030 This contains the code to perform relaxation, and to write out
6031 the object file. It is mostly operating system independent, but
6032 different OSes have different object file formats in any case.
6035 This implements @code{malloc()} or bust. See @file{append.c} above.
6038 This implements @code{realloc()} or bust. See @file{append.c} above.
6040 @item atof-generic.c
6041 The following files were taken from a machine-independent subroutine
6042 library for manipulating floating point numbers and very large
6045 @file{atof-generic.c} turns a string into a flonum internal format
6046 floating-point number.
6048 @item flonum-const.c
6049 This contains some potentially useful floating point numbers in
6053 This copies a flonum.
6055 @item flonum-multip.c
6056 This multiplies two flonums together.
6059 This copies a bignum.
6063 Here is a table of all the machine-specific files (this includes
6064 both source and header files). Typically, there is a
6065 @var{machine}.c file, a @var{machine}-opcode.h file, and an
6066 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
6067 be identical to the one used by GDB (which uses it for disassembly.)
6072 This contains code to turn a flonum into a ieee literal constant.
6073 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{@value{as}}.
6076 This is the opcode-table for the i386 version of the assembler.
6079 This contains all the code for the i386 version of the assembler.
6082 This defines constants and macros used by the i386 version of the assembler.
6085 generic 68020 header file. To be linked to m68k.h on a
6086 non-sun3, non-hpux system.
6089 68010 header file for Sun2 workstations. Not well tested. To be linked
6090 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
6094 68020 header file for Sun3 workstations. To be linked to m68k.h before
6095 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
6099 68020 header file for a HPUX (system 5?) box. Which box, which
6100 version of HPUX, etc? I don't know.
6103 A hard- or symbolic- link to one of @file{m-generic.h},
6104 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
6105 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
6109 Opcode table for 68020. This is now a link to the opcode table
6110 in the @code{GDB} source directory.
6113 All the mc680x0 code, in one huge, slow-to-compile file.
6116 This contains the code for the ns32032/ns32532 version of the
6119 @item ns32k-opcode.h
6120 This contains the opcode table for the ns32032/ns32532 version
6124 Vax specific file for describing Vax operands and other Vax-ish things.
6130 Vax specific parts of @code{@value{as}}. Also includes the former files
6131 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
6134 Turns a flonum into a Vax constant.
6137 This file contains the special code needed to put out a VMS
6138 style object file for the Vax.
6142 Here is a list of the header files in the source directory.
6143 (Warning: This section may not be very accurate. I didn't
6144 write the header files; I just report them.) Also note that I
6145 think many of these header files could be cleaned up or
6151 This describes the structures used to create the binary header data
6152 inside the object file. Perhaps we should use the one in
6153 @file{/usr/include}?
6156 This defines all the globally useful things, and pulls in _0__<stdio.h>_1__
6157 and _0__<assert.h>_1__.
6160 This defines macros useful for dealing with bignums.
6163 Structure and macros for dealing with expression()
6166 This defines the structure for dealing with floating point
6167 numbers. It #includes @file{bignum.h}.
6170 This contains macro for appending a byte to the current frag.
6173 Structures and function definitions for the hashing functions.
6176 Function headers for the input-file.c functions.
6179 structures and function headers for things defined in the
6180 machine dependent part of the assembler.
6183 This is the GNU systemwide include file for manipulating obstacks.
6184 Since nobody is running under real GNU yet, we include this file.
6187 Macros and function headers for reading in source files.
6189 @item struct-symbol.h
6190 Structure definition and macros for dealing with the @value{as}
6191 internal form of a symbol.
6194 structure definition for dealing with the numbered subsections
6195 of the text and data sections.
6198 Macros and function headers for dealing with symbols.
6201 Structure for doing section fixups.
6204 @c ~subsection Test Directory
6205 @c (Note: The test directory seems to have disappeared somewhere
6206 @c along the line. If you want it, you'll probably have to find a
6207 @c REALLY OLD dump tape~dots{})
6209 @c The ~file{test/} directory is used for regression testing.
6210 @c After you modify ~@code{@value{as}}, you can get a quick go/nogo
6211 @c confidence test by running the new ~@code{@value{as}} over the source
6212 @c files in this directory. You use a shell script ~file{test/do}.
6214 @c The tests in this suite are evolving. They are not comprehensive.
6215 @c They have, however, caught hundreds of bugs early in the debugging
6216 @c cycle of ~@code{@value{as}}. Most test statements in this suite were naturally
6217 @c selected: they were used to demonstrate actual ~@code{@value{as}} bugs rather
6218 @c than being written ~i{a prioi}.
6220 @c Another testing suggestion: over 30 bugs have been found simply by
6221 @c running examples from this manual through ~@code{@value{as}}.
6222 @c Some examples in this manual are selected
6223 @c to distinguish boundary conditions; they are good for testing ~@code{@value{as}}.
6225 @c ~subsubsection Regression Testing
6226 @c Each regression test involves assembling a file and comparing the
6227 @c actual output of ~@code{@value{as}} to ``known good'' output files. Both
6228 @c the object file and the error/warning message file (stderr) are
6229 @c inspected. Optionally the ~@code{@value{as}} exit status may be checked.
6230 @c Discrepencies are reported. Each discrepency means either that
6231 @c you broke some part of ~@code{@value{as}} or that the ``known good'' files
6232 @c are now out of date and should be changed to reflect the new
6233 @c definition of ``good''.
6235 @c Each regression test lives in its own directory, in a tree
6236 @c rooted in the directory ~file{test/}. Each such directory
6237 @c has a name ending in ~file{.ret}, where `ret' stands for
6238 @c REgression Test. The ~file{.ret} ending allows ~code{find
6239 @c (1)} to find all regression tests in the tree, without
6240 @c needing to list them explicitly.
6242 @c Any ~file{.ret} directory must contain a file called
6243 @c ~file{input} which is the source file to assemble. During
6244 @c testing an object file ~file{output} is created, as well as
6245 @c a file ~file{stdouterr} which contains the output to both
6246 @c stderr and stderr. If there is a file ~file{output.good} in
6247 @c the directory, and if ~file{output} contains exactly the
6248 @c same data as ~file{output.good}, the file ~file{output} is
6249 @c deleted. Likewise ~file{stdouterr} is removed if it exactly
6250 @c matches a file ~file{stdouterr.good}. If file
6251 @c ~file{status.good} is present, containing a decimal number
6252 @c before a newline, the exit status of ~@code{@value{as}} is compared
6253 @c to this number. If the status numbers are not equal, a file
6254 @c ~file{status} is written to the directory, containing the
6255 @c actual status as a decimal number followed by newline.
6257 @c Should any of the ~file{*.good} files fail to match their corresponding
6258 @c actual files, this is noted by a 1-line message on the screen during
6259 @c the regression test, and you can use ~@code{find (1)} to find any
6260 @c files named ~file{status}, ~file {output} or ~file{stdouterr}.
6264 @chapter Teaching the Assembler about a New Machine
6266 This chapter describes the steps required in order to make the
6267 assembler work with another machine's assembly language. This
6268 chapter is not complete, and only describes the steps in the
6269 broadest terms. You should look at the source for the
6270 currently supported machine in order to discover some of the
6271 details that aren't mentioned here.
6273 You should create a new file called @file{@var{machine}.c}, and
6274 add the appropriate lines to the file @file{Makefile} so that
6275 you can compile your new version of the assembler. This should
6276 be straighforward; simply add lines similar to the ones there
6277 for the four current versions of the assembler.
6279 If you want to be compatible with GDB, (and the current
6280 machine-dependent versions of the assembler), you should create
6281 a file called @file{@var{machine}-opcode.h} which should
6282 contain all the information about the names of the machine
6283 instructions, their opcodes, and what addressing modes they
6284 support. If you do this right, the assembler and GDB can share
6285 this file, and you'll only have to write it once. Note that
6286 while you're writing @code{@value{as}}, you may want to use an
6287 independent program (if you have access to one), to make sure
6288 that @code{@value{as}} is emitting the correct bytes. Since @code{@value{as}}
6289 and @code{GDB} share the opcode table, an incorrect opcode
6290 table entry may make invalid bytes look OK when you disassemble
6291 them with @code{GDB}.
6293 @section Functions You will Have to Write
6295 Your file @file{@var{machine}.c} should contain definitions for
6296 the following functions and variables. It will need to include
6297 some header files in order to use some of the structures
6298 defined in the machine-independent part of the assembler. The
6299 needed header files are mentioned in the descriptions of the
6300 functions that will need them.
6305 This long integer holds the value to place at the beginning of
6306 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
6307 machines that store additional information in the magic-number.
6309 @item char comment_chars[];
6310 This character array holds the values of the characters that
6311 start a comment anywhere in a line. Comments are stripped off
6312 automatically by the machine independent part of the
6313 assembler. Note that the @samp{/*} will always start a
6314 comment, and that only @samp{*/} will end a comment started by
6317 @item char line_comment_chars[];
6318 This character array holds the values of the chars that start a
6319 comment only if they are the first (non-whitespace) character
6320 on a line. If the character @samp{#} does not appear in this
6321 list, you may get unexpected results. (Various
6322 machine-independent parts of the assembler treat the comments
6323 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
6324 that start with @samp{#} are comments.)
6326 @item char EXP_CHARS[];
6327 This character array holds the letters that can separate the
6328 mantissa and the exponent of a floating point number. Typical
6329 values are @samp{e} and @samp{E}.
6331 @item char FLT_CHARS[];
6332 This character array holds the letters that--when they appear
6333 immediately after a leading zero--indicate that a number is a
6334 floating-point number. (Sort of how 0x indicates that a
6335 hexadecimal number follows.)
6337 @item pseudo_typeS md_pseudo_table[];
6338 (@var{pseudo_typeS} is defined in @file{md.h})
6339 This array contains a list of the machine_dependent directives
6340 the assembler must support. It contains the name of each
6341 pseudo op (Without the leading @samp{.}), a pointer to a
6342 function to be called when that directive is encountered, and
6343 an integer argument to be passed to that function.
6345 @item void md_begin(void)
6346 This function is called as part of the assembler's
6347 initialization. It should do any initialization required by
6348 any of your other routines.
6350 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
6351 This routine is called once for each option on the command line
6352 that the machine-independent part of @code{@value{as}} does not
6353 understand. This function should return non-zero if the option
6354 pointed to by @var{optionPTR} is a valid option. If it is not
6355 a valid option, this routine should return zero. The variables
6356 @var{argcPTR} and @var{argvPTR} are provided in case the option
6357 requires a filename or something similar as an argument. If
6358 the option is multi-character, @var{optionPTR} should be
6359 advanced past the end of the option, otherwise every letter in
6360 the option will be treated as a separate single-character
6363 @item void md_assemble(char *string)
6364 This routine is called for every machine-dependent
6365 non-directive line in the source file. It does all the real
6366 work involved in reading the opcode, parsing the operands,
6367 etc. @var{string} is a pointer to a null-terminated string,
6368 that comprises the input line, with all excess whitespace and
6371 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
6372 This routine is called to turn a C long int, short int, or char
6373 into the series of bytes that represents that number on the
6374 target machine. @var{outputPTR} points to an array where the
6375 result should be stored; @var{value} is the value to store; and
6376 @var{nbytes} is the number of bytes in 'value' that should be
6379 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
6380 This routine is called to turn a C long int, short int, or char
6381 into the series of bytes that represent an immediate value on
6382 the target machine. It is identical to the function @code{md_number_to_chars},
6383 except on NS32K machines.@refill
6385 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
6386 This routine is called to turn a C long int, short int, or char
6387 into the series of bytes that represent an displacement value on
6388 the target machine. It is identical to the function @code{md_number_to_chars},
6389 except on NS32K machines.@refill
6391 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
6392 This routine is identical to @code{md_number_to_chars},
6393 except on NS32K machines.
6395 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
6396 (@code{struct relocation_info} is defined in @file{a.out.h})
6397 This routine emits the relocation info in @var{ri}
6398 in the appropriate bit-pattern for the target machine.
6399 The result should be stored in the location pointed
6400 to by @var{riPTR}. This routine may be a no-op unless you are
6401 attempting to do cross-assembly.
6403 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
6404 This routine turns a series of digits into the appropriate
6405 internal representation for a floating-point number.
6406 @var{type} is a character from @var{FLT_CHARS[]} that describes
6407 what kind of floating point number is wanted; @var{outputPTR}
6408 is a pointer to an array that the result should be stored in;
6409 and @var{sizePTR} is a pointer to an integer where the size (in
6410 bytes) of the result should be stored. This routine should
6411 return an error message, or an empty string (not (char *)0) for
6414 @item int md_short_jump_size;
6415 This variable holds the (maximum) size in bytes of a short (16
6416 bit or so) jump created by @code{md_create_short_jump()}. This
6417 variable is used as part of the broken-word feature, and isn't
6418 needed if the assembler is compiled with
6419 @samp{-DWORKING_DOT_WORD}.
6421 @item int md_long_jump_size;
6422 This variable holds the (maximum) size in bytes of a long (32
6423 bit or so) jump created by @code{md_create_long_jump()}. This
6424 variable is used as part of the broken-word feature, and isn't
6425 needed if the assembler is compiled with
6426 @samp{-DWORKING_DOT_WORD}.
6428 @item void md_create_short_jump(char *resultPTR,long from_addr,
6429 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6430 This function emits a jump from @var{from_addr} to @var{to_addr} in
6431 the array of bytes pointed to by @var{resultPTR}. If this creates a
6432 type of jump that must be relocated, this function should call
6433 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
6434 emitted by this function may be smaller than @var{md_short_jump_size},
6435 but it must never create a larger one.
6436 (If it creates a smaller jump, the extra bytes of memory will not be
6437 used.) This function is used as part of the broken-word feature,
6438 and isn't needed if the assembler is compiled with
6439 @samp{-DWORKING_DOT_WORD}.@refill
6441 @item void md_create_long_jump(char *ptr,long from_addr,
6442 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6443 This function is similar to the previous function,
6444 @code{md_create_short_jump()}, except that it creates a long
6445 jump instead of a short one. This function is used as part of
6446 the broken-word feature, and isn't needed if the assembler is
6447 compiled with @samp{-DWORKING_DOT_WORD}.
6449 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
6450 This function does the initial setting up for relaxation. This
6451 includes forcing references to still-undefined symbols to the
6452 appropriate addressing modes.
6454 @item relax_typeS md_relax_table[];
6455 (relax_typeS is defined in md.h)
6456 This array describes the various machine dependent states a
6457 frag may be in before relaxation. You will need one group of
6458 entries for each type of addressing mode you intend to relax.
6460 @item void md_convert_frag(fragS *fragPTR)
6461 (@var{fragS} is defined in @file{as.h})
6462 This routine does the required cleanup after relaxation.
6463 Relaxation has changed the type of the frag to a type that can
6464 reach its destination. This function should adjust the opcode
6465 of the frag to use the appropriate addressing mode.
6466 @var{fragPTR} points to the frag to clean up.
6468 @item void md_end(void)
6469 This function is called just before the assembler exits. It
6470 need not free up memory unless the operating system doesn't do
6471 it automatically on exit. (In which case you'll also have to
6472 track down all the other places where the assembler allocates
6473 space but never frees it.)
6477 @section External Variables You will Need to Use
6479 You will need to refer to or change the following external variables
6480 from within the machine-dependent part of the assembler.
6483 @item extern char flagseen[];
6484 This array holds non-zero values in locations corresponding to
6485 the options that were on the command line. Thus, if the
6486 assembler was called with @samp{-W}, @var{flagseen['W']} would
6489 @item extern fragS *frag_now;
6490 This pointer points to the current frag--the frag that bytes
6491 are currently being added to. If nothing else, you will need
6492 to pass it as an argument to various machine-independent
6493 functions. It is maintained automatically by the
6494 frag-manipulating functions; you should never have to change it
6497 @item extern LITTLENUM_TYPE generic_bignum[];
6498 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
6499 This is where @dfn{bignums}--numbers larger than 32 bits--are
6500 returned when they are encountered in an expression. You will
6501 need to use this if you need to implement directives (or
6502 anything else) that must deal with these large numbers.
6503 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
6504 @file{as.h}, and have a positive @code{X_add_number}. The
6505 @code{X_add_number} of a @code{bignum} is the number of
6506 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
6509 @item extern FLONUM_TYPE generic_floating_point_number;
6510 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
6511 The is where @dfn{flonums}--floating-point numbers within
6512 expressions--are returned. @code{Flonums} are of @code{segT}
6513 @code{SEG_BIG}, and have a negative @code{X_add_number}.
6514 @code{Flonums} are returned in a generic format. You will have
6515 to write a routine to turn this generic format into the
6516 appropriate floating-point format for your machine.
6518 @item extern int need_pass_2;
6519 If this variable is non-zero, the assembler has encountered an
6520 expression that cannot be assembled in a single pass. Since
6521 the second pass isn't implemented, this flag means that the
6522 assembler is punting, and is only looking for additional syntax
6523 errors. (Or something like that.)
6525 @item extern segT now_seg;
6526 This variable holds the value of the section the assembler is
6527 currently assembling into.
6531 @section External functions will you need
6533 You will find the following external functions useful (or
6534 indispensable) when you're writing the machine-dependent part
6539 @item char *frag_more(int bytes)
6540 This function allocates @var{bytes} more bytes in the current
6541 frag (or starts a new frag, if it can't expand the current frag
6542 any more.) for you to store some object-file bytes in. It
6543 returns a pointer to the bytes, ready for you to store data in.
6545 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
6546 This function stores a relocation fixup to be acted on later.
6547 @var{frag} points to the frag the relocation belongs in;
6548 @var{where} is the location within the frag where the relocation begins;
6549 @var{size} is the size of the relocation, and is usually 1 (a single byte),
6550 2 (sixteen bits), or 4 (a longword).
6551 The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
6552 at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the
6553 location is subtracted from the result. A relocation entry is also added
6554 to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
6555 @var{offset} may be NULL.@refill
6557 @item char *frag_var(relax_stateT type, int max_chars, int var,
6558 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
6559 This function creates a machine-dependent frag of type @var{type}
6560 (usually @code{rs_machine_dependent}).
6561 @var{max_chars} is the maximum size in bytes that the frag may grow by;
6562 @var{var} is the current size of the variable end of the frag;
6563 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
6564 @var{md_relax_table[]} during @code{relaxation}.
6565 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
6566 @var{opcode} points into a byte whose value may have to be modified if the
6567 addressing mode used by this frag changes. It typically points into the
6568 @var{fr_literal[]} of the previous frag, and is used to point to a location
6569 that @code{md_convert_frag()}, may have to change.@refill
6571 @item void frag_wane(fragS *fragPTR)
6572 This function is useful from within @code{md_convert_frag}. It
6573 changes a frag to type rs_fill, and sets the variable-sized
6574 piece of the frag to zero. The frag will never change in size
6577 @item segT expression(expressionS *retval)
6578 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
6579 This function parses the string pointed to by the external char
6580 pointer @var{input_line_pointer}, and returns the section-type
6581 of the expression. It also stores the results in the
6582 @var{expressionS} pointed to by @var{retval}.
6583 @var{input_line_pointer} is advanced to point past the end of
6584 the expression. (@var{input_line_pointer} is used by other
6585 parts of the assembler. If you modify it, be sure to restore
6586 it to its original value.)
6588 @item as_warn(char *message,@dots{})
6589 If warning messages are disabled, this function does nothing.
6590 Otherwise, it prints out the current file name, and the current
6591 line number, then uses @code{fprintf} to print the
6592 @var{message} and any arguments it was passed.
6594 @item as_bad(char *message,@dots{})
6595 This function should be called when @code{@value{as}} encounters
6596 conditions that are bad enough that @code{@value{as}} should not
6597 produce an object file, but should continue reading input and
6598 printing warning and bad error messages.
6600 @item as_fatal(char *message,@dots{})
6601 This function prints out the current file name and line number,
6602 prints the word @samp{FATAL:}, then uses @code{fprintf} to
6603 print the @var{message} and any arguments it was passed. Then
6604 the assembler exits. This function should only be used for
6605 serious, unrecoverable errors.
6607 @item void float_const(int float_type)
6608 This function reads floating-point constants from the current
6609 input line, and calls @code{md_atof} to assemble them. It is
6610 useful as the function to call for the directives
6611 @samp{.single}, @samp{.double}, @samp{.float}, etc.
6612 @var{float_type} must be a character from @var{FLT_CHARS}.
6614 @item void demand_empty_rest_of_line(void);
6615 This function can be used by machine-dependent directives to
6616 make sure the rest of the input line is empty. It prints a
6617 warning message if there are additional characters on the line.
6619 @item long int get_absolute_expression(void)
6620 This function can be used by machine-dependent directives to
6621 read an absolute number from the current input line. It
6622 returns the result. If it isn't given an absolute expression,
6623 it prints a warning message and returns zero.
6628 @section The concept of Frags
6630 This assembler works to optimize the size of certain addressing
6631 modes. (e.g. branch instructions) This means the size of many
6632 pieces of object code cannot be determined until after assembly
6633 is finished. (This means that the addresses of symbols cannot be
6634 determined until assembly is finished.) In order to do this,
6635 @code{@value{as}} stores the output bytes as @dfn{frags}.
6637 Here is the definition of a frag (from @file{as.h})
6643 relax_stateT fr_type;
6644 relax_substateT fr_substate;
6645 unsigned long fr_address;
6647 struct symbol *fr_symbol;
6649 struct frag *fr_next;
6656 is the size of the fixed-size piece of the frag.
6659 is the maximum (?) size of the variable-sized piece of the frag.
6662 is the type of the frag.
6667 rs_machine_dependent
6670 This stores the type of machine-dependent frag this is. (what
6671 kind of addressing mode is being used, and what size is being
6675 @var{fr_address} is only valid after relaxation is finished.
6676 Before relaxation, the only way to store an address is (pointer
6677 to frag containing the address) plus (offset into the frag).
6680 This contains a number, whose meaning depends on the type of
6682 for machine_dependent frags, this contains the offset from
6683 fr_symbol that the frag wants to go to. Thus, for branch
6684 instructions it is usually zero. (unless the instruction was
6685 @samp{jba foo+12} or something like that.)
6688 for machine_dependent frags, this points to the symbol the frag
6692 This points to the location in the frag (or in a previous frag)
6693 of the opcode for the instruction that caused this to be a frag.
6694 @var{fr_opcode} is needed if the actual opcode must be changed
6695 in order to use a different form of the addressing mode.
6696 (For example, if a conditional branch only comes in size tiny,
6697 a large-size branch could be implemented by reversing the sense
6698 of the test, and turning it into a tiny branch over a large jump.
6699 This would require changing the opcode.)
6701 @var{fr_literal} is a variable-size array that contains the
6702 actual object bytes. A frag consists of a fixed size piece of
6703 object data, (which may be zero bytes long), followed by a
6704 piece of object data whose size may not have been determined
6705 yet. Other information includes the type of the frag (which
6706 controls how it is relaxed),
6709 This is the next frag in the singly-linked list. This is
6710 usually only needed by the machine-independent part of
6717 @unnumbered GNU GENERAL PUBLIC LICENSE
6721 @cindex copying @code{@value{as}}
6722 @center Version 2, June 1991
6725 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
6726 675 Mass Ave, Cambridge, MA 02139, USA
6728 Everyone is permitted to copy and distribute verbatim copies
6729 of this license document, but changing it is not allowed.
6732 @unnumberedsec Preamble
6734 The licenses for most software are designed to take away your
6735 freedom to share and change it. By contrast, the GNU General Public
6736 License is intended to guarantee your freedom to share and change free
6737 software---to make sure the software is free for all its users. This
6738 General Public License applies to most of the Free Software
6739 Foundation's software and to any other program whose authors commit to
6740 using it. (Some other Free Software Foundation software is covered by
6741 the GNU Library General Public License instead.) You can apply it to
6744 When we speak of free software, we are referring to freedom, not
6745 price. Our General Public Licenses are designed to make sure that you
6746 have the freedom to distribute copies of free software (and charge for
6747 this service if you wish), that you receive source code or can get it
6748 if you want it, that you can change the software or use pieces of it
6749 in new free programs; and that you know you can do these things.
6751 To protect your rights, we need to make restrictions that forbid
6752 anyone to deny you these rights or to ask you to surrender the rights.
6753 These restrictions translate to certain responsibilities for you if you
6754 distribute copies of the software, or if you modify it.
6756 For example, if you distribute copies of such a program, whether
6757 gratis or for a fee, you must give the recipients all the rights that
6758 you have. You must make sure that they, too, receive or can get the
6759 source code. And you must show them these terms so they know their
6762 We protect your rights with two steps: (1) copyright the software, and
6763 (2) offer you this license which gives you legal permission to copy,
6764 distribute and/or modify the software.
6766 Also, for each author's protection and ours, we want to make certain
6767 that everyone understands that there is no warranty for this free
6768 software. If the software is modified by someone else and passed on, we
6769 want its recipients to know that what they have is not the original, so
6770 that any problems introduced by others will not reflect on the original
6771 authors' reputations.
6773 Finally, any free program is threatened constantly by software
6774 patents. We wish to avoid the danger that redistributors of a free
6775 program will individually obtain patent licenses, in effect making the
6776 program proprietary. To prevent this, we have made it clear that any
6777 patent must be licensed for everyone's free use or not licensed at all.
6779 The precise terms and conditions for copying, distribution and
6780 modification follow.
6783 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6786 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6791 This License applies to any program or other work which contains
6792 a notice placed by the copyright holder saying it may be distributed
6793 under the terms of this General Public License. The ``Program'', below,
6794 refers to any such program or work, and a ``work based on the Program''
6795 means either the Program or any derivative work under copyright law:
6796 that is to say, a work containing the Program or a portion of it,
6797 either verbatim or with modifications and/or translated into another
6798 language. (Hereinafter, translation is included without limitation in
6799 the term ``modification''.) Each licensee is addressed as ``you''.
6801 Activities other than copying, distribution and modification are not
6802 covered by this License; they are outside its scope. The act of
6803 running the Program is not restricted, and the output from the Program
6804 is covered only if its contents constitute a work based on the
6805 Program (independent of having been made by running the Program).
6806 Whether that is true depends on what the Program does.
6809 You may copy and distribute verbatim copies of the Program's
6810 source code as you receive it, in any medium, provided that you
6811 conspicuously and appropriately publish on each copy an appropriate
6812 copyright notice and disclaimer of warranty; keep intact all the
6813 notices that refer to this License and to the absence of any warranty;
6814 and give any other recipients of the Program a copy of this License
6815 along with the Program.
6817 You may charge a fee for the physical act of transferring a copy, and
6818 you may at your option offer warranty protection in exchange for a fee.
6821 You may modify your copy or copies of the Program or any portion
6822 of it, thus forming a work based on the Program, and copy and
6823 distribute such modifications or work under the terms of Section 1
6824 above, provided that you also meet all of these conditions:
6828 You must cause the modified files to carry prominent notices
6829 stating that you changed the files and the date of any change.
6832 You must cause any work that you distribute or publish, that in
6833 whole or in part contains or is derived from the Program or any
6834 part thereof, to be licensed as a whole at no charge to all third
6835 parties under the terms of this License.
6838 If the modified program normally reads commands interactively
6839 when run, you must cause it, when started running for such
6840 interactive use in the most ordinary way, to print or display an
6841 announcement including an appropriate copyright notice and a
6842 notice that there is no warranty (or else, saying that you provide
6843 a warranty) and that users may redistribute the program under
6844 these conditions, and telling the user how to view a copy of this
6845 License. (Exception: if the Program itself is interactive but
6846 does not normally print such an announcement, your work based on
6847 the Program is not required to print an announcement.)
6850 These requirements apply to the modified work as a whole. If
6851 identifiable sections of that work are not derived from the Program,
6852 and can be reasonably considered independent and separate works in
6853 themselves, then this License, and its terms, do not apply to those
6854 sections when you distribute them as separate works. But when you
6855 distribute the same sections as part of a whole which is a work based
6856 on the Program, the distribution of the whole must be on the terms of
6857 this License, whose permissions for other licensees extend to the
6858 entire whole, and thus to each and every part regardless of who wrote it.
6860 Thus, it is not the intent of this section to claim rights or contest
6861 your rights to work written entirely by you; rather, the intent is to
6862 exercise the right to control the distribution of derivative or
6863 collective works based on the Program.
6865 In addition, mere aggregation of another work not based on the Program
6866 with the Program (or with a work based on the Program) on a volume of
6867 a storage or distribution medium does not bring the other work under
6868 the scope of this License.
6871 You may copy and distribute the Program (or a work based on it,
6872 under Section 2) in object code or executable form under the terms of
6873 Sections 1 and 2 above provided that you also do one of the following:
6877 Accompany it with the complete corresponding machine-readable
6878 source code, which must be distributed under the terms of Sections
6879 1 and 2 above on a medium customarily used for software interchange; or,
6882 Accompany it with a written offer, valid for at least three
6883 years, to give any third party, for a charge no more than your
6884 cost of physically performing source distribution, a complete
6885 machine-readable copy of the corresponding source code, to be
6886 distributed under the terms of Sections 1 and 2 above on a medium
6887 customarily used for software interchange; or,
6890 Accompany it with the information you received as to the offer
6891 to distribute corresponding source code. (This alternative is
6892 allowed only for noncommercial distribution and only if you
6893 received the program in object code or executable form with such
6894 an offer, in accord with Subsection b above.)
6897 The source code for a work means the preferred form of the work for
6898 making modifications to it. For an executable work, complete source
6899 code means all the source code for all modules it contains, plus any
6900 associated interface definition files, plus the scripts used to
6901 control compilation and installation of the executable. However, as a
6902 special exception, the source code distributed need not include
6903 anything that is normally distributed (in either source or binary
6904 form) with the major components (compiler, kernel, and so on) of the
6905 operating system on which the executable runs, unless that component
6906 itself accompanies the executable.
6908 If distribution of executable or object code is made by offering
6909 access to copy from a designated place, then offering equivalent
6910 access to copy the source code from the same place counts as
6911 distribution of the source code, even though third parties are not
6912 compelled to copy the source along with the object code.
6915 You may not copy, modify, sublicense, or distribute the Program
6916 except as expressly provided under this License. Any attempt
6917 otherwise to copy, modify, sublicense or distribute the Program is
6918 void, and will automatically terminate your rights under this License.
6919 However, parties who have received copies, or rights, from you under
6920 this License will not have their licenses terminated so long as such
6921 parties remain in full compliance.
6924 You are not required to accept this License, since you have not
6925 signed it. However, nothing else grants you permission to modify or
6926 distribute the Program or its derivative works. These actions are
6927 prohibited by law if you do not accept this License. Therefore, by
6928 modifying or distributing the Program (or any work based on the
6929 Program), you indicate your acceptance of this License to do so, and
6930 all its terms and conditions for copying, distributing or modifying
6931 the Program or works based on it.
6934 Each time you redistribute the Program (or any work based on the
6935 Program), the recipient automatically receives a license from the
6936 original licensor to copy, distribute or modify the Program subject to
6937 these terms and conditions. You may not impose any further
6938 restrictions on the recipients' exercise of the rights granted herein.
6939 You are not responsible for enforcing compliance by third parties to
6943 If, as a consequence of a court judgment or allegation of patent
6944 infringement or for any other reason (not limited to patent issues),
6945 conditions are imposed on you (whether by court order, agreement or
6946 otherwise) that contradict the conditions of this License, they do not
6947 excuse you from the conditions of this License. If you cannot
6948 distribute so as to satisfy simultaneously your obligations under this
6949 License and any other pertinent obligations, then as a consequence you
6950 may not distribute the Program at all. For example, if a patent
6951 license would not permit royalty-free redistribution of the Program by
6952 all those who receive copies directly or indirectly through you, then
6953 the only way you could satisfy both it and this License would be to
6954 refrain entirely from distribution of the Program.
6956 If any portion of this section is held invalid or unenforceable under
6957 any particular circumstance, the balance of the section is intended to
6958 apply and the section as a whole is intended to apply in other
6961 It is not the purpose of this section to induce you to infringe any
6962 patents or other property right claims or to contest validity of any
6963 such claims; this section has the sole purpose of protecting the
6964 integrity of the free software distribution system, which is
6965 implemented by public license practices. Many people have made
6966 generous contributions to the wide range of software distributed
6967 through that system in reliance on consistent application of that
6968 system; it is up to the author/donor to decide if he or she is willing
6969 to distribute software through any other system and a licensee cannot
6972 This section is intended to make thoroughly clear what is believed to
6973 be a consequence of the rest of this License.
6976 If the distribution and/or use of the Program is restricted in
6977 certain countries either by patents or by copyrighted interfaces, the
6978 original copyright holder who places the Program under this License
6979 may add an explicit geographical distribution limitation excluding
6980 those countries, so that distribution is permitted only in or among
6981 countries not thus excluded. In such case, this License incorporates
6982 the limitation as if written in the body of this License.
6985 The Free Software Foundation may publish revised and/or new versions
6986 of the General Public License from time to time. Such new versions will
6987 be similar in spirit to the present version, but may differ in detail to
6988 address new problems or concerns.
6990 Each version is given a distinguishing version number. If the Program
6991 specifies a version number of this License which applies to it and ``any
6992 later version'', you have the option of following the terms and conditions
6993 either of that version or of any later version published by the Free
6994 Software Foundation. If the Program does not specify a version number of
6995 this License, you may choose any version ever published by the Free Software
6999 If you wish to incorporate parts of the Program into other free
7000 programs whose distribution conditions are different, write to the author
7001 to ask for permission. For software which is copyrighted by the Free
7002 Software Foundation, write to the Free Software Foundation; we sometimes
7003 make exceptions for this. Our decision will be guided by the two goals
7004 of preserving the free status of all derivatives of our free software and
7005 of promoting the sharing and reuse of software generally.
7008 @heading NO WARRANTY
7015 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
7016 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
7017 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
7018 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
7019 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
7020 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
7021 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
7022 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
7023 REPAIR OR CORRECTION.
7026 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
7027 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
7028 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
7029 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
7030 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
7031 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
7032 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
7033 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
7034 POSSIBILITY OF SUCH DAMAGES.
7038 @heading END OF TERMS AND CONDITIONS
7041 @center END OF TERMS AND CONDITIONS
7045 @unnumberedsec Applying These Terms to Your New Programs
7047 If you develop a new program, and you want it to be of the greatest
7048 possible use to the public, the best way to achieve this is to make it
7049 free software which everyone can redistribute and change under these terms.
7051 To do so, attach the following notices to the program. It is safest
7052 to attach them to the start of each source file to most effectively
7053 convey the exclusion of warranty; and each file should have at least
7054 the ``copyright'' line and a pointer to where the full notice is found.
7057 @var{one line to give the program's name and an idea of what it does.}
7058 Copyright (C) 19@var{yy} @var{name of author}
7060 This program is free software; you can redistribute it and/or
7061 modify it under the terms of the GNU General Public License
7062 as published by the Free Software Foundation; either version 2
7063 of the License, or (at your option) any later version.
7065 This program is distributed in the hope that it will be useful,
7066 but WITHOUT ANY WARRANTY; without even the implied warranty of
7067 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
7068 GNU General Public License for more details.
7070 You should have received a copy of the GNU General Public License
7071 along with this program; if not, write to the
7072 Free Software Foundation, Inc., 675 Mass Ave,
7073 Cambridge, MA 02139, USA.
7076 Also add information on how to contact you by electronic and paper mail.
7078 If the program is interactive, make it output a short notice like this
7079 when it starts in an interactive mode:
7082 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
7083 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
7084 type `show w'. This is free software, and you are welcome
7085 to redistribute it under certain conditions; type `show c'
7089 The hypothetical commands @samp{show w} and @samp{show c} should show
7090 the appropriate parts of the General Public License. Of course, the
7091 commands you use may be called something other than @samp{show w} and
7092 @samp{show c}; they could even be mouse-clicks or menu items---whatever
7095 You should also get your employer (if you work as a programmer) or your
7096 school, if any, to sign a ``copyright disclaimer'' for the program, if
7097 necessary. Here is a sample; alter the names:
7100 Yoyodyne, Inc., hereby disclaims all copyright interest in
7101 the program `Gnomovision' (which makes passes at compilers)
7102 written by James Hacker.
7104 @var{signature of Ty Coon}, 1 April 1989
7105 Ty Coon, President of Vice
7108 This General Public License does not permit incorporating your program into
7109 proprietary programs. If your program is a subroutine library, you may
7110 consider it more useful to permit linking proprietary applications with the
7111 library. If this is what you want to do, use the GNU Library General
7112 Public License instead of this License.