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 @setfilename _AS__.info
12 @settitle Using _AS__ (_HOST__)
14 @setchapternewpage odd
22 * As: (as). The GNU assembler.
32 NOTE: this manual is marked up for preprocessing with a collection
33 of m4 macros called "pretex.m4".
35 THIS IS THE FULL SOURCE. The full source needs to be run through m4
36 before either tex- or info- formatting: for example,
37 m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
38 will produce (assuming your path finds either GNU or SysV m4; Berkeley
39 won't do) a file, configured for the M680x0 version of GAS, suitable for
40 formatting. See the text in "pretex.m4" for a fuller explanation (and
41 the macro definitions).
46 This file documents the GNU Assembler "_AS__".
48 Copyright (C) 1991 Free Software Foundation, Inc.
50 Permission is granted to make and distribute verbatim copies of
51 this manual provided the copyright notice and this permission notice
52 are preserved on all copies.
55 Permission is granted to process this file through Tex and print the
56 results, provided the printed document carries copying permission
57 notice identical to this one except for the removal of this paragraph
58 (this paragraph not being relevant to the printed manual).
61 Permission is granted to copy and distribute modified versions of this
62 manual under the conditions for verbatim copying, provided also that the
63 section entitled ``GNU General Public License'' is included exactly as
64 in the original, and provided that the entire resulting derived work is
65 distributed under the terms of a permission notice identical to this
68 Permission is granted to copy and distribute translations of this manual
69 into another language, under the above conditions for modified versions,
70 except that the section entitled ``GNU General Public License'' may be
71 included in a translation approved by the Free Software Foundation
72 instead of in the original English.
77 @subtitle The GNU Assembler
79 @subtitle for the _HOST__ family
82 @subtitle January 1992
85 The Free Software Foundation Inc. thanks The Nice Computer
86 Company of Australia for loaning Dean Elsner to write the
87 first (Vax) version of @code{as} for Project GNU.
88 The proprietors, management and staff of TNCCA thank FSF for
89 distracting the boss while they got some work
92 @author Dean Elsner, Jay Fenlason & friends
93 @c edited by: pesch@cygnus.com
96 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
97 \xdef\manvers{\$Revision$} % For use in headers, footers too
99 \hfill {\it Using {\tt _AS__}} \manvers\par
100 \hfill \TeX{}info \texinfoversion\par
101 \hfill Edited by Roland Pesch for Cygnus Support\par
103 %"boxit" macro for figures:
104 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
105 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
106 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
107 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
108 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
111 @vskip 0pt plus 1filll
112 Copyright @copyright{} 1991 Free Software Foundation, Inc.
114 Permission is granted to make and distribute verbatim copies of
115 this manual provided the copyright notice and this permission notice
116 are preserved on all copies.
118 Permission is granted to copy and distribute modified versions of this
119 manual under the conditions for verbatim copying, provided also that the
120 section entitled ``GNU General Public License'' is included exactly as
121 in the original, and provided that the entire resulting derived work is
122 distributed under the terms of a permission notice identical to this
125 Permission is granted to copy and distribute translations of this manual
126 into another language, under the above conditions for modified versions,
127 except that the section entitled ``GNU General Public License'' may be
128 included in a translation approved by the Free Software Foundation
129 instead of in the original English.
132 @node Top, Overview, (dir), (dir)
134 This file is a user guide to the GNU assembler @code{_AS__}.
136 This version of the file describes @code{_AS__} configured to generate
137 code for _HOST__ architectures.
141 * Overview:: Overview
142 * Invoking:: Command-Line Options
144 * Sections:: Sections and Relocation
146 * Expressions:: Expressions
147 * Pseudo Ops:: Assembler Directives
148 * _MACH_DEP__:: Machine Dependent Features
149 * Copying:: GNU GENERAL PUBLIC LICENSE
153 @node Overview, Invoking, Top, Top
156 This manual is a user guide to the GNU assembler @code{_AS__}.
158 This version of the manual describes @code{_AS__} configured to generate
159 code for _HOST__ architectures.
163 @cindex invocation summary
164 @cindex option summary
165 @cindex summary of options
166 Here is a brief summary of how to invoke @code{_AS__}. For details,
167 @pxref{Invoking,,Comand-Line Options}.
169 @c We don't use deffn and friends for the following because they seem
170 @c to be limited to one line for the header.
172 _AS__ [ -a | -al | -as ] [ -D ] [ -f ]
173 [ -I @var{path} ] [ -K ] [ -L ]
174 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
176 @c am29k has no machine-dependent assembler options
179 @c h8/300 has no machine-dependent assembler options
182 @c see md_parse_option in i960.c
183 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
187 [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
189 [ -- | @var{files} @dots{} ]
194 Turn on assembly listings; @samp{-al}, listing only, @samp{-as}, symbols
195 only, @samp{-a}, everything.
198 This option is accepted only for script compatibility with calls to
199 other assemblers; it has no effect on @code{_AS__}.
202 ``fast''---skip preprocessing (assume source is compiler output)
205 Add @var{path} to the search list for @code{.include} directives
208 _if__((!_GENERIC__) && !_DIFFTABKLUG__)
209 This option is accepted but has no effect on the _HOST__ family.
210 _fi__((!_GENERIC__) && !_DIFFTABKLUG__)
211 _if__(_GENERIC__ || _DIFFTABKLUG__)
212 Issue warnings when difference tables altered for long displacements.
213 _fi__(_GENERIC__ || _DIFFTABKLUG__)
216 Keep (in symbol table) local symbols, starting with @samp{L}
218 @item -o @var{objfile}
219 Name the object-file output from @code{_AS__}
222 Fold data section into text section
225 Announce @code{as} version
228 Suppress warning messages
231 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
233 (When configured for Intel 960).
235 Specify which variant of the 960 architecture is the target.
239 (When configured for Intel 960).
241 Add code to collect statistics about branches taken.
245 (When configured for Intel 960).
247 Do not alter compare-and-branch instructions for long displacements;
254 (When configured for Motorola 68000).
256 Shorten references to undefined symbols, to one word instead of two
258 @item -mc68000 | -mc68010 | -mc68020
260 (When configured for Motorola 68000).
262 Specify what processor in the 68000 family is the target (default 68020)
265 @item -- | @var{files} @dots{}
266 Standard input, or source files to assemble
270 * Manual:: Structure of this Manual
271 * GNU Assembler:: _AS__, the GNU Assembler
272 * Object Formats:: Object File Formats
273 * Command Line:: Command Line
274 * Input Files:: Input Files
275 * Object:: Output (Object) File
276 * Errors:: Error and Warning Messages
279 @node Manual, GNU Assembler, Overview, Overview
280 @section Structure of this Manual
282 @cindex manual, structure and purpose
283 This manual is intended to describe what you need to know to use
284 @sc{gnu} @code{_AS__}. We cover the syntax expected in source files, including
285 notation for symbols, constants, and expressions; the directives that
286 @code{_AS__} understands; and of course how to invoke @code{_AS__}.
289 We also cover special features in the _HOST__
290 configuration of @code{_AS__}, including assembler directives.
293 This manual also describes some of the machine-dependent features of
294 various flavors of the assembler.
297 This manual also describes how the assembler works internally, and
298 provides some information that may be useful to people attempting to
299 port the assembler to another machine.
303 @cindex machine instructions (not covered)
304 On the other hand, this manual is @emph{not} intended as an introduction
305 to programming in assembly language---let alone programming in general!
306 In a similar vein, we make no attempt to introduce the machine
307 architecture; we do @emph{not} describe the instruction set, standard
308 mnemonics, registers or addressing modes that are standard to a
309 particular architecture.
311 You may want to consult the manufacturer's
312 machine architecture manual for this information.
314 _if__(_H8__&&!_GENERIC__)
315 For information on the H8/300 machine instruction set, see @cite{H8/300
316 Series Programming Manual} (Hitachi ADE--602--025).
317 _fi__(_H8__&&!_GENERIC__)
320 @c I think this is premature---pesch@cygnus.com, 17jan1991
322 Throughout this manual, we assume that you are running @dfn{GNU},
323 the portable operating system from the @dfn{Free Software
324 Foundation, Inc.}. This restricts our attention to certain kinds of
325 computer (in particular, the kinds of computers that GNU can run on);
326 once this assumption is granted examples and definitions need less
329 @code{_AS__} is part of a team of programs that turn a high-level
330 human-readable series of instructions into a low-level
331 computer-readable series of instructions. Different versions of
332 @code{_AS__} are used for different kinds of computer.
335 @c There used to be a section "Terminology" here, which defined
336 @c "contents", "byte", "word", and "long". Defining "word" to any
337 @c particular size is confusing when the .word directive may generate 16
338 @c bits on one machine and 32 bits on another; in general, for the user
339 @c version of this manual, none of these terms seem essential to define.
340 @c They were used very little even in the former draft of the manual;
341 @c this draft makes an effort to avoid them (except in names of
344 @node GNU Assembler, Object Formats, Manual, Overview
345 @section _AS__, the GNU Assembler
347 GNU @code{as} is really a family of assemblers.
349 This manual describes @code{_AS__}, a member of that family which is
350 configured for the _HOST__ architectures.
352 If you use (or have used) the GNU assembler on one architecture, you
353 should find a fairly similar environment when you use it on another
354 architecture. Each version has much in common with the others,
355 including object file formats, most assembler directives (often called
356 @dfn{pseudo-ops)} and assembler syntax.@refill
358 _if__(_GENERIC__||!_H8__)
359 @cindex purpose of @sc{gnu} @code{_AS__}
360 @code{_AS__} is primarily intended to assemble the output of the GNU C
361 compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless,
362 we've tried to make @code{_AS__} assemble correctly everything that the native
364 _fi__(_GENERIC__||!_H8__)
366 Any exceptions are documented explicitly (@pxref{_MACH_DEP__}).
368 _if__(_GENERIC__||_M680X0__)
369 This doesn't mean @code{_AS__} always uses the same syntax as another
370 assembler for the same architecture; for example, we know of several
371 incompatible versions of 680x0 assembly language syntax.
372 _fi__(_GENERIC__||_M680X0__)
374 Unlike older assemblers, @code{_AS__} is designed to assemble a source
375 program in one pass of the source file. This has a subtle impact on the
376 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
378 @node Object Formats, Command Line, GNU Assembler, Overview
379 @section Object File Formats
381 @cindex object file format
382 The GNU assembler can be configured to produce several alternative
383 object file formats. For the most part, this does not affect how you
384 write assembly language programs; but directives for debugging symbols
385 are typically different in different file formats. @xref{Symbol
386 Attributes,,Symbol Attributes}.
388 _if__(!(_I960__||_A29K__))
389 _if__(_AOUT__ && (!_COFF__) && (!_ELF__))
390 On the _HOST__, @code{_AS__} is configured to produce @code{a.out} format object
392 _fi__(_AOUT__ && (!_COFF__) && (!_ELF__))
393 _if__((!_AOUT__) && _COFF__ && (!_ELF__))
394 On the _HOST__, @code{_AS__} is configured to produce COFF format object
396 _fi__((!_AOUT__) && _COFF__ && (!_ELF__))
397 _fi__(!(_I960__||_A29K__))
399 On the _HOST__, @code{_AS__} can be configured to produce either
400 @code{a.out} or COFF format object files.
403 On the _HOST__, @code{_AS__} can be configured to produce either @code{b.out} or COFF
408 @node Command Line, Input Files, Object Formats, Overview
409 @section Command Line
411 @cindex command line conventions
412 After the program name @code{_AS__}, the command line may contain
413 options and file names. Options may appear in any order, and may be
414 before, after, or between file names. The order of file names is
417 @cindex standard input, as input file
419 @file{--} (two hyphens) by itself names the standard input file
420 explicitly, as one of the files for @code{_AS__} to assemble.
422 @cindex options, command line
423 Except for @samp{--} any command line argument that begins with a
424 hyphen (@samp{-}) is an option. Each option changes the behavior of
425 @code{_AS__}. No option changes the way another option works. An
426 option is a @samp{-} followed by one or more letters; the case of
427 the letter is important. All options are optional.
429 Some options expect exactly one file name to follow them. The file
430 name may either immediately follow the option's letter (compatible
431 with older assemblers) or it may be the next command argument (GNU
432 standard). These two command lines are equivalent:
435 _AS__ -o my-object-file.o mumble.s
436 _AS__ -omy-object-file.o mumble.s
439 @node Input Files, Object, Command Line, Overview
443 @cindex source program
445 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
446 describe the program input to one run of @code{_AS__}. The program may
447 be in one or more files; how the source is partitioned into files
448 doesn't change the meaning of the source.
450 @c I added "con" prefix to "catenation" just to prove I can overcome my
451 @c APL training... pesch@cygnus.com
452 The source program is a concatenation of the text in all the files, in the
455 Each time you run @code{_AS__} it assembles exactly one source
456 program. The source program is made up of one or more files.
457 (The standard input is also a file.)
459 You give @code{_AS__} a command line that has zero or more input file
460 names. The input files are read (from left file name to right). A
461 command line argument (in any position) that has no special meaning
462 is taken to be an input file name.
464 If you give @code{_AS__} no file names it attempts to read one input file
465 from the @code{_AS__} standard input, which is normally your terminal. You
466 may have to type @key{ctl-D} to tell @code{_AS__} there is no more program
469 Use @samp{--} if you need to explicitly name the standard input file
470 in your command line.
472 If the source is empty, @code{_AS__} will produce a small, empty object
475 @subheading Filenames and Line-numbers
477 @cindex input file linenumbers
478 @cindex line numbers, in input files
479 There are two ways of locating a line in the input file (or files) and
480 either may be used in reporting error messages. One way refers to a line
481 number in a physical file; the other refers to a line number in a
482 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
484 @dfn{Physical files} are those files named in the command line given
487 @dfn{Logical files} are simply names declared explicitly by assembler
488 directives; they bear no relation to physical files. Logical file names
489 help error messages reflect the original source file, when @code{_AS__}
490 source is itself synthesized from other files.
491 @xref{App-File,,@code{.app-file}}.
493 @node Object, Errors, Input Files, Overview
494 @section Output (Object) File
500 Every time you run @code{_AS__} it produces an output file, which is
501 your assembly language program translated into numbers. This file
502 is the object file, named @code{a.out} unless you tell @code{_AS__} to
503 give it another name by using the @code{-o} option. Conventionally,
504 object file names end with @file{.o}. The default name of
505 @file{a.out} is used for historical reasons: older assemblers were
506 capable of assembling self-contained programs directly into a
508 @c This may still work, but hasn't been tested.
512 The object file is meant for input to the linker @code{_LD__}. It contains
513 assembled program code, information to help @code{_LD__} integrate
514 the assembled program into a runnable file, and (optionally) symbolic
515 information for the debugger.
517 @c link above to some info file(s) like the description of a.out.
518 @c don't forget to describe GNU info as well as Unix lossage.
520 @node Errors, , Object, Overview
521 @section Error and Warning Messages
523 @cindex error messsages
524 @cindex warning messages
525 @cindex messages from @code{_AS__}
526 @code{_AS__} may write warnings and error messages to the standard error
527 file (usually your terminal). This should not happen when a compiler
528 runs @code{_AS__} automatically. Warnings report an assumption made so
529 that @code{_AS__} could keep assembling a flawed program; errors report a
530 grave problem that stops the assembly.
532 @cindex format of warning messages
533 Warning messages have the format
536 file_name:@b{NNN}:Warning Message Text
540 @cindex line numbers, in warnings/errors
541 (where @b{NNN} is a line number). If a logical file name has
542 been given (@pxref{App-File,,@code{.app-file}}) it is used for the filename, otherwise the
543 name of the current input file is used. If a logical line number was
546 (@pxref{Line,,@code{.line}})
549 (@pxref{Ln,,@code{.ln}})
551 then it is used to calculate the number printed,
552 otherwise the actual line in the current source file is printed. The
553 message text is intended to be self explanatory (in the grand Unix
556 @cindex format of error messages
557 Error messages have the format
559 file_name:@b{NNN}:FATAL:Error Message Text
561 The file name and line number are derived as for warning
562 messages. The actual message text may be rather less explanatory
563 because many of them aren't supposed to happen.
565 @node Invoking, Syntax, Overview, Top
566 @chapter Command-Line Options
568 @cindex options, all versions of @code{_AS__}
569 This chapter describes command-line options available in @emph{all}
570 versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific
575 to particular machine architectures.
578 @section Enable Listings: @code{-a}, @code{-al}, @code{-as}
583 @cindex listings, enabling
584 @cindex assembly listings, enabling
585 These options enable listing output from the assembler. @samp{-a} by
586 itself requests all listing output; @samp{-al} requests only the
587 output-program listing, and @samp{-as} requests only a symbol table
590 Once you have specified one of these options, you can further control
591 listing output and its appearance using the directives @code{.list},
592 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
595 If you do not request listing output with one of the @samp{-a} options, the
596 listing-control directives have no effect.
601 This option has no effect whatsoever, but it is accepted to make it more
602 likely that scripts written for other assemblers will also work with
605 @section Work Faster: @code{-f}
608 @cindex trusted compiler
609 @cindex faster processing (@code{-f})
610 @samp{-f} should only be used when assembling programs written by a
611 (trusted) compiler. @samp{-f} stops the assembler from pre-processing
612 the input file(s) before assembling them. @xref{Pre-processing,
616 @emph{Warning:} if the files actually need to be pre-processed (if they
617 contain comments, for example), @code{_AS__} will not work correctly if
621 @section @code{.include} search path: @code{-I} @var{path}
623 @kindex -I @var{path}
624 @cindex paths for @code{.include}
625 @cindex search path for @code{.include}
626 @cindex @code{include} directive search path
627 Use this option to add a @var{path} to the list of directories
628 @code{_AS__} will search for files specified in @code{.include}
629 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
630 many times as necessary to include a variety of paths. The current
631 working directory is always searched first; after that, @code{_AS__}
632 searches any @samp{-I} directories in the same order as they were
633 specified (left to right) on the command line.
635 @section Difference Tables: @code{-K}
638 _if__((!_GENERIC__) && (!_DIFFTABKLUG__))
639 On the _HOST__ family, this option is allowed, but has no effect. It is
640 permitted for compatibility with the GNU assembler on other platforms,
641 where it can be used to warn when the assembler alters the machine code
642 generated for @samp{.word} directives in difference tables. The _HOST__
643 family does not have the addressing limitations that sometimes lead to this
644 alteration on other platforms.
645 _fi__((!_GENERIC__) && (!_DIFFTABKLUG__))
647 _if__(_GENERIC__ || _DIFFTABKLUG__ )
648 @cindex difference tables, warning
649 @cindex warning for altered difference tables
650 @code{_AS__} sometimes alters the code emitted for directives of the form
651 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
652 You can use the @samp{-K} option if you want a warning issued when this
654 _fi__(_GENERIC__ || _DIFFTABKLUG__ )
656 @section Include Local Labels: @code{-L}
659 @cindex local labels, retaining in output
660 Labels beginning with @samp{L} (upper case only) are called @dfn{local
661 labels}. @xref{Symbol Names}. Normally you don't see such labels when
662 debugging, because they are intended for the use of programs (like
663 compilers) that compose assembler programs, not for your notice.
664 Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't
665 normally debug with them.
667 This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols
668 in the object file. Usually if you do this you also tell the linker
669 @code{_LD__} to preserve symbols whose names begin with @samp{L}.
671 @section Name the Object File: @code{-o}
674 @cindex naming object file
675 @cindex object file name
676 There is always one object file output when you run @code{_AS__}. By
677 default it has the name @file{a.out}. You use this option (which
678 takes exactly one filename) to give the object file a different name.
680 Whatever the object file is called, @code{_AS__} will overwrite any
681 existing file of the same name.
683 @section Join Data and Text Sections: @code{-R}
686 @cindex data and text sections, joining
687 @cindex text and data sections, joining
688 @cindex joining text and data sections
689 @cindex merging text and data sections
690 @code{-R} tells @code{_AS__} to write the object file as if all
691 data-section data lives in the text section. This is only done at
692 the very last moment: your binary data are the same, but data
693 section parts are relocated differently. The data section part of
694 your object file is zero bytes long because all it bytes are
695 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
697 When you specify @code{-R} it would be possible to generate shorter
698 address displacements (because we don't have to cross between text and
699 data section). We refrain from doing this simply for compatibility with
700 older versions of @code{_AS__}. In future, @code{-R} may work this way.
703 When @code{_AS__} is configured for COFF output,
704 this option is only useful if you use sections named @samp{.text} and
708 @section Announce Version: @code{-v}
712 @cindex @code{_AS__} version
713 @cindex version of @code{_AS__}
714 You can find out what version of as is running by including the
715 option @samp{-v} (which you can also spell as @samp{-version}) on the
718 @section Suppress Warnings: @code{-W}
721 @cindex suppressing warnings
722 @cindex warnings, suppressing
723 @code{_AS__} should never give a warning or error message when
724 assembling compiler output. But programs written by people often
725 cause @code{_AS__} to give a warning that a particular assumption was
726 made. All such warnings are directed to the standard error file.
727 If you use this option, no warnings are issued. This option only
728 affects the warning messages: it does not change any particular of how
729 @code{_AS__} assembles your file. Errors, which stop the assembly, are
732 @node Syntax, Sections, Invoking, Top
735 @cindex machine-independent syntax
736 @cindex syntax, machine-independent
737 This chapter describes the machine-independent syntax allowed in a
738 source file. @code{_AS__} syntax is similar to what many other assemblers
739 use; it is inspired in BSD 4.2
744 assembler, except that @code{_AS__} does not assemble Vax bit-fields.
748 * Pre-processing:: Pre-processing
749 * Whitespace:: Whitespace
750 * Comments:: Comments
751 * Symbol Intro:: Symbols
752 * Statements:: Statements
753 * Constants:: Constants
756 @node Pre-processing, Whitespace, Syntax, Syntax
757 @section Pre-Processing
759 @cindex preprocessing
762 @cindex whitespace, removed by preprocessor
764 adjusts and removes extra whitespace. It leaves one space or tab before
765 the keywords on a line, and turns any other whitespace on the line into
768 @cindex comments, removed by preprocessor
770 removes all comments, replacing them with a single space, or an
771 appropriate number of newlines.
773 @cindex constants, converted by preprocessor
775 converts character constants into the appropriate numeric values.
778 Excess whitespace, comments, and character constants
779 cannot be used in the portions of the input text that are not
782 @cindex turning preprocessing on and off
783 @cindex preprocessing, turning on and off
786 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
787 option is given, the input file will not be pre-processed. Within such
788 an input file, parts of the file can be pre-processed by putting a line
789 that says @code{#APP} before the text that should be pre-processed, and
790 putting a line that says @code{#NO_APP} after them. This feature is
791 mainly intend to support @code{asm} statements in compilers whose output
792 normally does not need to be pre-processed.
794 @node Whitespace, Comments, Pre-processing, Syntax
798 @dfn{Whitespace} is one or more blanks or tabs, in any order.
799 Whitespace is used to separate symbols, and to make programs neater for
800 people to read. Unless within character constants
801 (@pxref{Characters,,Character Constants}), any whitespace means the same
802 as exactly one space.
804 @node Comments, Symbol Intro, Whitespace, Syntax
808 There are two ways of rendering comments to @code{_AS__}. In both
809 cases the comment is equivalent to one space.
811 Anything from @samp{/*} through the next @samp{*/} is a comment.
812 This means you may not nest these comments.
816 The only way to include a newline ('\n') in a comment
817 is to use this sort of comment.
820 /* This sort of comment does not nest. */
823 @cindex line comment character
824 Anything from the @dfn{line comment} character to the next newline
825 is considered a comment and is ignored. The line comment character is
830 @samp{#} on the i960;
833 @samp{|} on the 680x0;
836 @samp{;} for the AMD 29K family;
839 @samp{;} for the _HOST__ family;
841 @pxref{_MACH_DEP__}. @refill
842 @c FIXME: fill in SPARC line comment char
845 On some machines there are two different line comment characters. One
846 will only begin a comment if it is the first non-whitespace character on
847 a line, while the other will always begin a comment.
851 @cindex lines starting with @code{#}
852 @cindex logical line numbers
853 To be compatible with past assemblers, a special interpretation is
854 given to lines that begin with @samp{#}. Following the @samp{#} an
855 absolute expression (@pxref{Expressions}) is expected: this will be
856 the logical line number of the @b{next} line. Then a string
857 (@xref{Strings}.) is allowed: if present it is a new logical file
858 name. The rest of the line, if any, should be whitespace.
860 If the first non-whitespace characters on the line are not numeric,
861 the line is ignored. (Just like a comment.)
863 # This is an ordinary comment.
864 # 42-6 "new_file_name" # New logical file name
865 # This is logical line # 36.
867 This feature is deprecated, and may disappear from future versions
870 @node Symbol Intro, Statements, Comments, Syntax
873 @cindex characters used in symbols
874 A @dfn{symbol} is one or more characters chosen from the set of all
875 letters (both upper and lower case), digits and
877 the three characters @samp{_.$}
880 the two characters @samp{_.}
882 On most machines, you can also use @code{$} in symbol names; exceptions
883 are noted in @ref{_MACH_DEP__}.
886 No symbol may begin with a digit. Case is significant.
887 There is no length limit: all characters are significant. Symbols are
888 delimited by characters not in that set, or by the beginning of a file
889 (since the source program must end with a newline, the end of a file is
890 not a possible symbol delimiter). @xref{Symbols}.
891 @cindex length of symbols
893 @node Statements, Constants, Symbol Intro, Syntax
896 @cindex statements, structure of
897 @cindex line separator character
898 @cindex statement separator character
900 _if__(!(_A29K__||_H8__))
901 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
902 semicolon (@samp{;}). The newline or semicolon is considered part of
903 the preceding statement. Newlines and semicolons within character
904 constants are an exception: they don't end statements.
905 _fi__(!(_A29K__||_H8__))
907 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
908 sign (@samp{@@}). The newline or at sign is considered part of the
909 preceding statement. Newlines and at signs within character constants
910 are an exception: they don't end statements.
913 A @dfn{statement} ends at a newline character (@samp{\n}) or a dollar
914 sign (@samp{$}). The newline or dollar sign is considered part of the
915 preceding statement. Newlines and dollar signs within character constants
916 are an exception: they don't end statements.
920 A @dfn{statement} ends at a newline character (@samp{\n}) or line
921 separator character. (The line separator is usually @samp{;}, unless
922 this conflicts with the comment character; @pxref{_MACH_DEP__}.) The
923 newline or separator character is considered part of the preceding
924 statement. Newlines and separators within character constants are an
925 exception: they don't end statements.
928 @cindex newline, required at file end
929 @cindex EOF, newline must precede
930 It is an error to end any statement with end-of-file: the last
931 character of any input file should be a newline.@refill
933 @cindex continuing statements
934 @cindex multi-line statements
935 @cindex statement on multiple lines
936 You may write a statement on more than one line if you put a
937 backslash (@kbd{\}) immediately in front of any newlines within the
938 statement. When @code{_AS__} reads a backslashed newline both
939 characters are ignored. You can even put backslashed newlines in
940 the middle of symbol names without changing the meaning of your
943 An empty statement is allowed, and may include whitespace. It is ignored.
945 @cindex instructions and directives
946 @cindex directives and instructions
947 @c "key symbol" is not used elsewhere in the document; seems pedantic to
948 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
950 A statement begins with zero or more labels, optionally followed by a
951 key symbol which determines what kind of statement it is. The key
952 symbol determines the syntax of the rest of the statement. If the
953 symbol begins with a dot @samp{.} then the statement is an assembler
954 directive: typically valid for any computer. If the symbol begins with
955 a letter the statement is an assembly language @dfn{instruction}: it
956 will assemble into a machine language instruction.
958 Different versions of @code{_AS__} for different computers will
959 recognize different instructions. In fact, the same symbol may
960 represent a different instruction in a different computer's assembly
964 @cindex @code{:} (label)
965 @cindex label (@code{:})
966 A label is a symbol immediately followed by a colon (@code{:}).
967 Whitespace before a label or after a colon is permitted, but you may not
968 have whitespace between a label's symbol and its colon. @xref{Labels}.
971 label: .directive followed by something
972 another_label: # This is an empty statement.
973 instruction operand_1, operand_2, @dots{}
976 @node Constants, , Statements, Syntax
980 A constant is a number, written so that its value is known by
981 inspection, without knowing any context. Like this:
983 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
984 .ascii "Ring the bell\7" # A string constant.
985 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
986 .float 0f-314159265358979323846264338327\
987 95028841971.693993751E-40 # - pi, a flonum.
991 * Characters:: Character Constants
992 * Numbers:: Number Constants
995 @node Characters, Numbers, Constants, Constants
996 @subsection Character Constants
998 @cindex character constants
999 @cindex constants, character
1000 There are two kinds of character constants. A @dfn{character} stands
1001 for one character in one byte and its value may be used in
1002 numeric expressions. String constants (properly called string
1003 @emph{literals}) are potentially many bytes and their values may not be
1004 used in arithmetic expressions.
1008 * Chars:: Characters
1011 @node Strings, Chars, Characters, Characters
1012 @subsubsection Strings
1014 @cindex string constants
1015 @cindex constants, string
1016 A @dfn{string} is written between double-quotes. It may contain
1017 double-quotes or null characters. The way to get special characters
1018 into a string is to @dfn{escape} these characters: precede them with
1019 a backslash @samp{\} character. For example @samp{\\} represents
1020 one backslash: the first @code{\} is an escape which tells
1021 @code{_AS__} to interpret the second character literally as a backslash
1022 (which prevents @code{_AS__} from recognizing the second @code{\} as an
1023 escape character). The complete list of escapes follows.
1025 @cindex escape codes, character
1026 @cindex character escape codes
1029 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1032 @cindex @code{\b} (backspace character)
1033 @cindex backspace (@code{\b})
1034 Mnemonic for backspace; for ASCII this is octal code 010.
1037 @c Mnemonic for EOText; for ASCII this is octal code 004.
1040 @cindex @code{\f} (formfeed character)
1041 @cindex formfeed (@code{\f})
1042 Mnemonic for FormFeed; for ASCII this is octal code 014.
1045 @cindex @code{\n} (newline character)
1046 @cindex newline (@code{\n})
1047 Mnemonic for newline; for ASCII this is octal code 012.
1050 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1053 @cindex @code{\r} (carriage return character)
1054 @cindex carriage return (@code{\r})
1055 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1058 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1059 @c other assemblers.
1062 @cindex @code{\t} (tab)
1063 @cindex tab (@code{\t})
1064 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1067 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1068 @c @item \x @var{digit} @var{digit} @var{digit}
1069 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1071 @item \ @var{digit} @var{digit} @var{digit}
1072 @cindex @code{\@var{ddd}} (octal character code)
1073 @cindex octal character code (@code{\@var{ddd}})
1074 An octal character code. The numeric code is 3 octal digits.
1075 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1076 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1079 @cindex @code{\\} (@samp{\} character)
1080 @cindex backslash (@code{\\})
1081 Represents one @samp{\} character.
1084 @c Represents one @samp{'} (accent acute) character.
1085 @c This is needed in single character literals
1086 @c (@xref{Characters,,Character Constants}.) to represent
1090 @cindex @code{\"} (doublequote character)
1091 @cindex doublequote (@code{\"})
1092 Represents one @samp{"} character. Needed in strings to represent
1093 this character, because an unescaped @samp{"} would end the string.
1095 @item \ @var{anything-else}
1096 Any other character when escaped by @kbd{\} will give a warning, but
1097 assemble as if the @samp{\} was not present. The idea is that if
1098 you used an escape sequence you clearly didn't want the literal
1099 interpretation of the following character. However @code{_AS__} has no
1100 other interpretation, so @code{_AS__} knows it is giving you the wrong
1101 code and warns you of the fact.
1104 Which characters are escapable, and what those escapes represent,
1105 varies widely among assemblers. The current set is what we think
1106 the BSD 4.2 assembler recognizes, and is a subset of what most C
1107 compilers recognize. If you are in doubt, don't use an escape
1110 @node Chars, , Strings, Characters
1111 @subsubsection Characters
1113 @cindex single character constant
1114 @cindex character, single
1115 @cindex constant, single character
1116 A single character may be written as a single quote immediately
1117 followed by that character. The same escapes apply to characters as
1118 to strings. So if you want to write the character backslash, you
1119 must write @kbd{'\\} where the first @code{\} escapes the second
1120 @code{\}. As you can see, the quote is an acute accent, not a
1121 grave accent. A newline
1123 _if__(!(_A29K__||_H8__))
1124 (or semicolon @samp{;})
1125 _fi__(!(_A29K__||_H8__))
1127 (or at sign @samp{@@})
1130 (or dollar sign @samp{$})
1133 immediately following an acute accent is taken as a literal character
1134 and does not count as the end of a statement. The value of a character
1135 constant in a numeric expression is the machine's byte-wide code for
1136 that character. @code{_AS__} assumes your character code is ASCII:
1137 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1139 @node Numbers, , Characters, Constants
1140 @subsection Number Constants
1142 @cindex constants, number
1143 @cindex number constants
1144 @code{_AS__} distinguishes three kinds of numbers according to how they
1145 are stored in the target machine. @emph{Integers} are numbers that
1146 would fit into an @code{int} in the C language. @emph{Bignums} are
1147 integers, but they are stored in more than 32 bits. @emph{Flonums}
1148 are floating point numbers, described below.
1151 * Integers:: Integers
1154 _if__(_I960__&&!_GENERIC__)
1155 * Bit Fields:: Bit Fields
1156 _fi__(_I960__&&!_GENERIC__)
1159 @node Integers, Bignums, Numbers, Numbers
1160 @subsubsection Integers
1162 @cindex constants, integer
1164 @cindex binary integers
1165 @cindex integers, binary
1166 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1167 the binary digits @samp{01}.
1169 @cindex octal integers
1170 @cindex integers, octal
1171 An octal integer is @samp{0} followed by zero or more of the octal
1172 digits (@samp{01234567}).
1174 @cindex decimal integers
1175 @cindex integers, decimal
1176 A decimal integer starts with a non-zero digit followed by zero or
1177 more digits (@samp{0123456789}).
1179 @cindex hexadecimal integers
1180 @cindex integers, hexadecimal
1181 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1182 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1184 Integers have the usual values. To denote a negative integer, use
1185 the prefix operator @samp{-} discussed under expressions
1186 (@pxref{Prefix Ops,,Prefix Operators}).
1188 @node Bignums, Flonums, Integers, Numbers
1189 @subsubsection Bignums
1192 @cindex constants, bignum
1193 A @dfn{bignum} has the same syntax and semantics as an integer
1194 except that the number (or its negative) takes more than 32 bits to
1195 represent in binary. The distinction is made because in some places
1196 integers are permitted while bignums are not.
1198 _if__(_I960__&&!_GENERIC__)
1199 @node Flonums, Bit Fields, Bignums, Numbers
1200 _fi__(_I960__&&!_GENERIC__)
1201 _if__(_GENERIC__||!_I960__)
1202 @node Flonums, , Bignums, Numbers
1203 _fi__(_GENERIC__||!_I960__)
1204 @subsubsection Flonums
1206 @cindex floating point numbers
1207 @cindex constants, floating point
1209 @cindex precision, floating point
1210 A @dfn{flonum} represents a floating point number. The translation is
1211 indirect: a decimal floating point number from the text is converted by
1212 @code{_AS__} to a generic binary floating point number of more than
1213 sufficient precision. This generic floating point number is converted
1214 to a particular computer's floating point format (or formats) by a
1215 portion of @code{_AS__} specialized to that computer.
1217 A flonum is written by writing (in order)
1222 A letter, to tell @code{_AS__} the rest of the number is a flonum.
1224 @kbd{e} is recommended. Case is not important.
1226 @c FIXME: verify if flonum syntax really this vague for most cases
1227 (Any otherwise illegal letter
1228 will work here, but that might be changed. Vax BSD 4.2 assembler seems
1229 to allow any of @samp{defghDEFGH}.)
1232 _if__(_A29K__||_H8__)
1234 On the AMD 29K and H8/300 architectures, the letter must be:
1236 One of the letters @samp{DFPRSX} (in upper or lower case).
1237 _fi__(_A29K__||_H8__)
1240 On the Intel 960 architecture, the letter must be:
1242 One of the letters @samp{DFT} (in upper or lower case).
1245 An optional sign: either @samp{+} or @samp{-}.
1247 An optional @dfn{integer part}: zero or more decimal digits.
1249 An optional @dfn{fractional part}: @samp{.} followed by zero
1250 or more decimal digits.
1252 An optional exponent, consisting of:
1255 An @samp{E} or @samp{e}.
1256 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1257 @c principle this can perfectly well be different on different targets.
1259 Optional sign: either @samp{+} or @samp{-}.
1261 One or more decimal digits.
1265 At least one of the integer part or the fractional part must be
1266 present. The floating point number has the usual base-10 value.
1268 @code{_AS__} does all processing using integers. Flonums are computed
1269 independently of any floating point hardware in the computer running
1272 _if__(_I960__&&!_GENERIC__)
1273 @c Bit fields are written as a general facility but are also controlled
1274 @c by a conditional-compilation flag---which is as of now (21mar91)
1275 @c turned on only by the i960 config of GAS.
1276 @node Bit Fields, , Flonums, Numbers
1277 @subsubsection Bit Fields
1280 @cindex constants, bit field
1281 You can also define numeric constants as @dfn{bit fields}.
1282 specify two numbers separated by a colon---
1284 @var{mask}:@var{value}
1287 the first will act as a mask; @code{_AS__} will bitwise-and it with the
1290 The resulting number is then packed
1292 @c this conditional paren in case bit fields turned on elsewhere than 960
1293 (in host-dependent byte order)
1295 into a field whose width depends on which assembler directive has the
1296 bit-field as its argument. Overflow (a result from the bitwise and
1297 requiring more binary digits to represent) is not an error; instead,
1298 more constants are generated, of the specified width, beginning with the
1299 least significant digits.@refill
1301 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1302 @code{.short}, and @code{.word} accept bit-field arguments.
1303 _fi__(_I960__&&!_GENERIC__)
1305 @node Sections, Symbols, Syntax, Top
1306 @chapter Sections and Relocation
1311 * Secs Background:: Background
1312 * _LD__ Sections:: _LD__ Sections
1313 * _AS__ Sections:: _AS__ Internal Sections
1314 * Sub-Sections:: Sub-Sections
1318 @node Secs Background, _LD__ Sections, Sections, Sections
1321 Roughly, a section is a range of addresses, with no gaps; all data
1322 ``in'' those addresses is treated the same for some particular purpose.
1323 For example there may be a ``read only'' section.
1325 @cindex linker, and assembler
1326 @cindex assembler, and linker
1327 The linker @code{_LD__} reads many object files (partial programs) and
1328 combines their contents to form a runnable program. When @code{_AS__}
1329 emits an object file, the partial program is assumed to start at address
1330 0. @code{_LD__} will assign the final addresses the partial program
1331 occupies, so that different partial programs don't overlap. This is
1332 actually an over-simplification, but it will suffice to explain how
1333 @code{_AS__} uses sections.
1335 @code{_LD__} moves blocks of bytes of your program to their run-time
1336 addresses. These blocks slide to their run-time addresses as rigid
1337 units; their length does not change and neither does the order of bytes
1338 within them. Such a rigid unit is called a @emph{section}. Assigning
1339 run-time addresses to sections is called @dfn{relocation}. It includes
1340 the task of adjusting mentions of object-file addresses so they refer to
1341 the proper run-time addresses.
1343 For the H8/300, @code{_AS__} pads sections if needed to ensure they end
1344 on a word (sixteen bit) boundary.
1347 @cindex standard @code{_AS__} sections
1348 An object file written by @code{_AS__} has at least three sections, any
1349 of which may be empty. These are named @dfn{text}, @dfn{data} and
1354 When it generates COFF output,
1356 @code{_AS__} can also generate whatever other named sections you specify
1357 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1358 If you don't use any directives that place output in the @samp{.text}
1359 or @samp{.data} sections, these sections will still exist, but will be empty.
1362 Within the object file, the text section starts at address @code{0}, the
1363 data section follows, and the bss section follows the data section.
1365 To let @code{_LD__} know which data will change when the sections are
1366 relocated, and how to change that data, @code{_AS__} also writes to the
1367 object file details of the relocation needed. To perform relocation
1368 @code{_LD__} must know, each time an address in the object
1372 Where in the object file is the beginning of this reference to
1375 How long (in bytes) is this reference?
1377 Which section does the address refer to? What is the numeric value of
1379 (@var{address}) @minus{} (@var{start-address of section})?
1382 Is the reference to an address ``Program-Counter relative''?
1385 @cindex addresses, format of
1386 @cindex section-relative addressing
1387 In fact, every address @code{_AS__} ever uses is expressed as
1389 (@var{section}) + (@var{offset into section})
1392 Further, every expression @code{_AS__} computes is of this section-relative
1393 nature. @dfn{Absolute expression} means an expression with section
1394 ``absolute'' (@pxref{_LD__ Sections}). A @dfn{pass1 expression} means
1395 an expression with section ``pass1'' (@pxref{_AS__ Sections,,_AS__
1396 Internal Sections}). In this manual we use the notation @{@var{secname}
1397 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1399 Apart from text, data and bss sections you need to know about the
1400 @dfn{absolute} section. When @code{_LD__} mixes partial programs,
1401 addresses in the absolute section remain unchanged. For example, address
1402 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}.
1403 Although two partial programs' data sections will not overlap addresses
1404 after linking, @emph{by definition} their absolute sections will overlap.
1405 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1406 address when the program is running as address @code{@{absolute@ 239@}} in any
1407 other partial program.
1409 The idea of sections is extended to the @dfn{undefined} section. Any
1410 address whose section is unknown at assembly time is by definition
1411 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1412 Since numbers are always defined, the only way to generate an undefined
1413 address is to mention an undefined symbol. A reference to a named
1414 common block would be such a symbol: its value is unknown at assembly
1415 time so it has section @emph{undefined}.
1417 By analogy the word @emph{section} is used to describe groups of sections in
1418 the linked program. @code{_LD__} puts all partial programs' text
1419 sections in contiguous addresses in the linked program. It is
1420 customary to refer to the @emph{text section} of a program, meaning all
1421 the addresses of all partial program's text sections. Likewise for
1422 data and bss sections.
1424 Some sections are manipulated by @code{_LD__}; others are invented for
1425 use of @code{_AS__} and have no meaning except during assembly.
1427 @node _LD__ Sections, _AS__ Sections, Secs Background, Sections
1428 @section _LD__ Sections
1429 @code{_LD__} deals with just four kinds of sections, summarized below.
1433 _if__(_GENERIC__||_COFF__)
1434 @cindex named sections
1435 @cindex sections, named
1436 @item named sections
1437 _fi__(_GENERIC__||_COFF__)
1438 _if__(_AOUT__||_BOUT__)
1439 @cindex text section
1440 @cindex data section
1443 _fi__(_AOUT__||_BOUT__)
1444 These sections hold your program. @code{_AS__} and @code{_LD__} treat them as
1445 separate but equal sections. Anything you can say of one section is
1447 _if__(_AOUT__||_BOUT__)
1448 When the program is running, however, it is
1449 customary for the text section to be unalterable. The
1450 text section is often shared among processes: it will contain
1451 instructions, constants and the like. The data section of a running
1452 program is usually alterable: for example, C variables would be stored
1453 in the data section.
1454 _fi__(_AOUT__||_BOUT__)
1458 This section contains zeroed bytes when your program begins running. It
1459 is used to hold unitialized variables or common storage. The length of
1460 each partial program's bss section is important, but because it starts
1461 out containing zeroed bytes there is no need to store explicit zero
1462 bytes in the object file. The bss section was invented to eliminate
1463 those explicit zeros from object files.
1465 @cindex absolute section
1466 @item absolute section
1467 Address 0 of this section is always ``relocated'' to runtime address 0.
1468 This is useful if you want to refer to an address that @code{_LD__} must
1469 not change when relocating. In this sense we speak of absolute
1470 addresses being ``unrelocatable'': they don't change during relocation.
1472 @cindex undefined section
1473 @item undefined section
1474 This ``section'' is a catch-all for address references to objects not in
1475 the preceding sections.
1476 @c FIXME: ref to some other doc on obj-file formats could go here.
1479 @cindex relocation example
1480 An idealized example of three relocatable sections follows.
1482 The example uses the traditional section names @samp{.text} and @samp{.data}.
1484 Memory addresses are on the horizontal axis.
1488 @c END TEXI2ROFF-KILL
1491 partial program # 1: |ttttt|dddd|00|
1498 partial program # 2: |TTT|DDD|000|
1501 +--+---+-----+--+----+---+-----+~~
1502 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1503 +--+---+-----+--+----+---+-----+~~
1505 addresses: 0 @dots{}
1509 @c FIXME make sure no page breaks inside figure!!
1512 \line{\it Partial program \#1: \hfil}
1513 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1514 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1516 \line{\it Partial program \#2: \hfil}
1517 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1518 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1520 \line{\it linked program: \hfil}
1521 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1522 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1523 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1524 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1526 \line{\it addresses: \hfil}
1530 @c END TEXI2ROFF-KILL
1532 @node _AS__ Sections, Sub-Sections, _LD__ Sections, Sections
1533 @section _AS__ Internal Sections
1535 @cindex internal @code{_AS__} sections
1536 @cindex sections in messages, internal
1537 These sections are meant only for the internal use of @code{_AS__}. They
1538 have no meaning at run-time. You don't really need to know about these
1539 sections for most purposes; but they can be mentioned in @code{_AS__}
1540 warning messages, so it might be helpful to have an idea of their
1541 meanings to @code{_AS__}. These sections are used to permit the
1542 value of every expression in your assembly language program to be a
1543 section-relative address.
1547 @cindex absent (internal section)
1548 An expression was expected and none was found.
1550 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1551 @cindex assembler internal logic error
1552 An internal assembler logic error has been found. This means there is a
1553 bug in the assembler.
1556 @cindex bignum/flonum (internal section)
1557 If a number can't be written as a C @code{int} constant (a bignum or a
1558 flonum, but not an integer), it is recorded as belonging to this
1559 ``section''. @code{_AS__} has to remember that a flonum or a bignum
1560 does not fit into 32 bits, and cannot be an argument (@pxref{Arguments})
1561 in an expression: this is done by making a flonum or bignum be in a
1562 separate internal section. This is purely for internal @code{_AS__}
1563 convenience; bignum/flonum section behaves similarly to absolute
1567 @cindex pass1 (internal section)
1568 The expression was impossible to evaluate in the first pass. The
1569 assembler will attempt a second pass (second reading of the source) to
1570 evaluate the expression. Your expression mentioned an undefined symbol
1571 in a way that defies the one-pass (section + offset in section) assembly
1572 process. No compiler need emit such an expression.
1575 @emph{Warning:} the second pass is currently not implemented. @code{_AS__}
1576 will abort with an error message if one is required.
1579 @item difference section
1580 @cindex difference (internal section)
1581 As an assist to the C compiler, expressions of the forms
1583 (@var{undefined symbol}) @minus{} (@var{expression})
1584 @var{something} @minus{} (@var{undefined symbol})
1585 (@var{undefined symbol}) @minus{} (@var{undefined symbol})
1588 are permitted, and belong to the difference section. @code{_AS__}
1589 re-evaluates such expressions after the source file has been read and
1590 the symbol table built. If by that time there are no undefined symbols
1591 in the expression then the expression assumes a new section. The
1592 intention is to permit statements like
1593 @samp{.word label - base_of_table}
1594 to be assembled in one pass where both @code{label} and
1595 @code{base_of_table} are undefined. This is useful for compiling C and
1596 Algol switch statements, Pascal case statements, FORTRAN computed goto
1597 statements and the like.
1599 @c FIXME item transfer[t] vector preload
1600 @c FIXME item transfer[t] vector postload
1601 @c FIXME item register
1604 @node Sub-Sections, bss, _AS__ Sections, Sections
1605 @section Sub-Sections
1607 @cindex numbered subsections
1608 @cindex grouping data
1609 _if__(_AOUT__||_BOUT__)
1614 fall into two sections: text and data.
1615 _fi__(_AOUT__||_BOUT__)
1616 You may have separate groups of
1617 _if__(_COFF__||_GENERIC__)
1618 data in named sections
1619 _fi__(_COFF__||_GENERIC__)
1620 _if__((_AOUT__||_BOUT__)&&!_GENERIC__)
1622 _fi__((_AOUT__||_BOUT__)&&!_GENERIC__)
1623 that you want to end up near to each other in the object
1624 file, even though they are not contiguous in the assembler source.
1625 @code{_AS__} allows you to use @dfn{subsections} for this purpose.
1626 Within each section, there can be numbered subsections with
1627 values from 0 to 8192. Objects assembled into the same subsection will
1628 be grouped with other objects in the same subsection when they are all
1629 put into the object file. For example, a compiler might want to store
1630 constants in the text section, but might not want to have them
1631 interspersed with the program being assembled. In this case, the
1632 compiler could issue a @samp{.text 0} before each section of code being
1633 output, and a @samp{.text 1} before each group of constants being output.
1635 Subsections are optional. If you don't use subsections, everything
1636 will be stored in subsection number zero.
1639 Each subsection is zero-padded up to a multiple of four bytes.
1640 (Subsections may be padded a different amount on different flavors
1645 On the H8/300 platform, each subsection is zero-padded to a word
1646 boundary (two bytes).
1649 @c FIXME section padding (alignment)?
1650 @c Rich Pixley says padding here depends on target obj code format; that
1651 @c doesn't seem particularly useful to say without further elaboration,
1652 @c so for now I say nothing about it. If this is a generic BFD issue,
1653 @c these paragraphs might need to vanish from this manual, and be
1654 @c discussed in BFD chapter of binutils (or some such).
1657 On the AMD 29K family, no particular padding is added to section or
1658 subsection sizes; _AS__ forces no alignment on this platform.
1662 Subsections appear in your object file in numeric order, lowest numbered
1663 to highest. (All this to be compatible with other people's assemblers.)
1664 The object file contains no representation of subsections; @code{_LD__} and
1665 other programs that manipulate object files will see no trace of them.
1666 They just see all your text subsections as a text section, and all your
1667 data subsections as a data section.
1669 To specify which subsection you want subsequent statements assembled
1670 into, use a numeric argument to specify it, in a @samp{.text
1671 @var{expression}} or a @samp{.data @var{expression}} statement.
1674 When generating COFF output, you
1679 can also use an extra subsection
1680 argument with arbitrary named sections: @samp{.section @var{name},
1683 @var{Expression} should be an absolute expression.
1684 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
1685 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
1686 begins in @code{text 0}. For instance:
1688 .text 0 # The default subsection is text 0 anyway.
1689 .ascii "This lives in the first text subsection. *"
1691 .ascii "But this lives in the second text subsection."
1693 .ascii "This lives in the data section,"
1694 .ascii "in the first data subsection."
1696 .ascii "This lives in the first text section,"
1697 .ascii "immediately following the asterisk (*)."
1700 Each section has a @dfn{location counter} incremented by one for every
1701 byte assembled into that section. Because subsections are merely a
1702 convenience restricted to @code{_AS__} there is no concept of a subsection
1703 location counter. There is no way to directly manipulate a location
1704 counter---but the @code{.align} directive will change it, and any label
1705 definition will capture its current value. The location counter of the
1706 section that statements are being assembled into is said to be the
1707 @dfn{active} location counter.
1709 @node bss, , Sub-Sections, Sections
1710 @section bss Section
1713 @cindex common variable storage
1714 The bss section is used for local common variable storage.
1715 You may allocate address space in the bss section, but you may
1716 not dictate data to load into it before your program executes. When
1717 your program starts running, all the contents of the bss
1718 section are zeroed bytes.
1720 Addresses in the bss section are allocated with special directives; you
1721 may not assemble anything directly into the bss section. Hence there
1722 are no bss subsections. @xref{Comm,,@code{.comm}},
1723 @pxref{Lcomm,,@code{.lcomm}}.
1725 @node Symbols, Expressions, Sections, Top
1729 Symbols are a central concept: the programmer uses symbols to name
1730 things, the linker uses symbols to link, and the debugger uses symbols
1734 @cindex debuggers, and symbol order
1735 @emph{Warning:} @code{_AS__} does not place symbols in the object file in
1736 the same order they were declared. This may break some debuggers.
1741 * Setting Symbols:: Giving Symbols Other Values
1742 * Symbol Names:: Symbol Names
1743 * Dot:: The Special Dot Symbol
1744 * Symbol Attributes:: Symbol Attributes
1747 @node Labels, Setting Symbols, Symbols, Symbols
1751 A @dfn{label} is written as a symbol immediately followed by a colon
1752 @samp{:}. The symbol then represents the current value of the
1753 active location counter, and is, for example, a suitable instruction
1754 operand. You are warned if you use the same symbol to represent two
1755 different locations: the first definition overrides any other
1758 @node Setting Symbols, Symbol Names, Labels, Symbols
1759 @section Giving Symbols Other Values
1761 @cindex assigning values to symbols
1762 @cindex symbol values, assigning
1763 A symbol can be given an arbitrary value by writing a symbol, followed
1764 by an equals sign @samp{=}, followed by an expression
1765 (@pxref{Expressions}). This is equivalent to using the @code{.set}
1766 directive. @xref{Set,,@code{.set}}.
1768 @node Symbol Names, Dot, Setting Symbols, Symbols
1769 @section Symbol Names
1771 @cindex symbol names
1772 @cindex names, symbol
1773 Symbol names begin with a letter or with one of
1780 (On most machines, you can also use @code{$} in symbol names; exceptions
1781 are noted in @ref{_MACH_DEP__}.)
1784 That character may be followed by any string of digits, letters,
1786 underscores and dollar signs.
1790 dollar signs (unless otherwise noted in @ref{_MACH_DEP__}),
1794 Case of letters is significant:
1795 @code{foo} is a different symbol name than @code{Foo}.
1798 For the AMD 29K family, @samp{?} is also allowed in the
1799 body of a symbol name, though not at its beginning.
1802 Each symbol has exactly one name. Each name in an assembly language
1803 program refers to exactly one symbol. You may use that symbol name any
1804 number of times in a program.
1806 @subheading Local Symbol Names
1808 @cindex local symbol names
1809 @cindex symbol names, local
1810 @cindex temporary symbol names
1811 @cindex symbol names, temporary
1812 Local symbols help compilers and programmers use names temporarily.
1813 There are ten local symbol names, which are re-used throughout the
1814 program. You may refer to them using the names @samp{0} @samp{1}
1815 @dots{} @samp{9}. To define a local symbol, write a label of the form
1816 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
1817 recent previous definition of that symbol write @samp{@b{N}b}, using the
1818 same digit as when you defined the label. To refer to the next
1819 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
1820 a choice of 10 forward references. The @samp{b} stands for
1821 ``backwards'' and the @samp{f} stands for ``forwards''.
1823 Local symbols are not emitted by the current GNU C compiler.
1825 There is no restriction on how you can use these labels, but
1826 remember that at any point in the assembly you can refer to at most
1827 10 prior local labels and to at most 10 forward local labels.
1829 Local symbol names are only a notation device. They are immediately
1830 transformed into more conventional symbol names before the assembler
1831 uses them. The symbol names stored in the symbol table, appearing in
1832 error messages and optionally emitted to the object file have these
1837 All local labels begin with @samp{L}. Normally both @code{_AS__} and
1838 @code{_LD__} forget symbols that start with @samp{L}. These labels are
1839 used for symbols you are never intended to see. If you give the
1840 @samp{-L} option then @code{_AS__} will retain these symbols in the
1841 object file. If you also instruct @code{_LD__} to retain these symbols,
1842 you may use them in debugging.
1845 If the label is written @samp{0:} then the digit is @samp{0}.
1846 If the label is written @samp{1:} then the digit is @samp{1}.
1847 And so on up through @samp{9:}.
1850 This unusual character is included so you don't accidentally invent
1851 a symbol of the same name. The character has ASCII value
1854 @item @emph{ordinal number}
1855 This is a serial number to keep the labels distinct. The first
1856 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
1857 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
1861 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
1862 @code{3:} is named @code{L3@ctrl{A}44}.
1864 @node Dot, Symbol Attributes, Symbol Names, Symbols
1865 @section The Special Dot Symbol
1867 @cindex dot (symbol)
1868 @cindex @code{.} (symbol)
1869 @cindex current address
1870 @cindex location counter
1871 The special symbol @samp{.} refers to the current address that
1872 @code{_AS__} is assembling into. Thus, the expression @samp{melvin:
1873 .long .} will cause @code{melvin} to contain its own address.
1874 Assigning a value to @code{.} is treated the same as a @code{.org}
1875 directive. Thus, the expression @samp{.=.+4} is the same as saying
1883 @node Symbol Attributes, , Dot, Symbols
1884 @section Symbol Attributes
1886 @cindex symbol attributes
1887 @cindex attributes, symbol
1888 Every symbol has, as well as its name, the attributes ``Value'' and
1889 ``Type''. Depending on output format, symbols can also have auxiliary
1892 The detailed definitions are in _0__<a.out.h>_1__.
1895 If you use a symbol without defining it, @code{_AS__} assumes zero for
1896 all these attributes, and probably won't warn you. This makes the
1897 symbol an externally defined symbol, which is generally what you
1901 * Symbol Value:: Value
1902 * Symbol Type:: Type
1903 _if__(_AOUT__||_BOUT__)
1904 _if__(_GENERIC__||!_BOUT__)
1905 * a.out Symbols:: Symbol Attributes: @code{a.out}
1906 _fi__(_GENERIC__||!_BOUT__)
1907 _if__(_BOUT__&&!_GENERIC__)
1908 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
1909 _fi__(_BOUT__&&!_GENERIC__)
1910 _fi__(_AOUT__||_BOUT__)
1912 * COFF Symbols:: Symbol Attributes for COFF
1916 @node Symbol Value, Symbol Type, Symbol Attributes, Symbol Attributes
1919 @cindex value of a symbol
1920 @cindex symbol value
1921 The value of a symbol is (usually) 32 bits. For a symbol which labels a
1922 location in the text, data, bss or absolute sections the value is the
1923 number of addresses from the start of that section to the label.
1924 Naturally for text, data and bss sections the value of a symbol changes
1925 as @code{_LD__} changes section base addresses during linking. Absolute
1926 symbols' values do not change during linking: that is why they are
1929 The value of an undefined symbol is treated in a special way. If it is
1930 0 then the symbol is not defined in this assembler source program, and
1931 @code{_LD__} will try to determine its value from other programs it is
1932 linked with. You make this kind of symbol simply by mentioning a symbol
1933 name without defining it. A non-zero value represents a @code{.comm}
1934 common declaration. The value is how much common storage to reserve, in
1935 bytes (addresses). The symbol refers to the first address of the
1938 _if__(!(_AOUT__||_BOUT__))
1939 @node Symbol Type, COFF Symbols, Symbol Value, Symbol Attributes
1940 _fi__(!(_AOUT__||_BOUT__))
1941 _if__((_AOUT__||_BOUT__))
1942 @node Symbol Type, a.out Symbols, Symbol Value, Symbol Attributes
1943 _fi__((_AOUT__||_BOUT__))
1946 @cindex type of a symbol
1948 The type attribute of a symbol contains relocation (section)
1949 information, any flag settings indicating that a symbol is external, and
1950 (optionally), other information for linkers and debuggers. The exact
1951 format depends on the object-code output format in use.
1953 _if__(_AOUT__||_BOUT__)
1955 @node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes
1958 @node a.out Symbols, , Symbol Type, Symbol Attributes
1960 _if__(_BOUT__&&!_GENERIC__)
1961 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
1963 @cindex @code{b.out} symbol attributes
1964 @cindex symbol attributes, @code{b.out}
1965 These symbol attributes appear only when @code{_AS__} is configured for
1966 one of the Berkeley-descended object output formats.
1967 _fi__(_BOUT__&&!_GENERIC__)
1968 _if__(_GENERIC__||!_BOUT__)
1969 @subsection Symbol Attributes: @code{a.out}
1970 _fi__(_GENERIC__||!_BOUT__)
1972 @cindex @code{a.out} symbol attributes
1973 @cindex symbol attributes, @code{a.out}
1976 * Symbol Desc:: Descriptor
1977 * Symbol Other:: Other
1980 @node Symbol Desc, Symbol Other, a.out Symbols, a.out Symbols
1981 @subsubsection Descriptor
1983 @cindex descriptor, of @code{a.out} symbol
1984 This is an arbitrary 16-bit value. You may establish a symbol's
1985 descriptor value by using a @code{.desc} statement
1986 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
1989 @node Symbol Other, , Symbol Desc, a.out Symbols
1990 @subsubsection Other
1992 @cindex other attribute, of @code{a.out} symbol
1993 This is an arbitrary 8-bit value. It means nothing to @code{_AS__}.
1994 _fi__(_AOUT__||_BOUT__)
1997 _if__(!(_AOUT__||_BOUT__))
1998 @node COFF Symbols, , Symbol Type, Symbol Attributes
1999 _fi__(!(_AOUT__||_BOUT__))
2000 _if__(_AOUT__||_BOUT__)
2001 @node COFF Symbols, , a.out Symbols, Symbol Attributes
2002 _fi__(_AOUT__||_BOUT__)
2003 @subsection Symbol Attributes for COFF
2005 @cindex COFF symbol attributes
2006 @cindex symbol attributes, COFF
2008 The COFF format supports a multitude of auxiliary symbol attributes;
2009 like the primary symbol attributes, they are set between @code{.def} and
2010 @code{.endef} directives.
2012 @subsubsection Primary Attributes
2014 @cindex primary attributes, COFF symbols
2015 The symbol name is set with @code{.def}; the value and type,
2016 respectively, with @code{.val} and @code{.type}.
2018 @subsubsection Auxiliary Attributes
2020 @cindex auxiliary attributes, COFF symbols
2021 The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl},
2022 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2023 information for COFF.
2026 @node Expressions, Pseudo Ops, Symbols, Top
2027 @chapter Expressions
2031 @cindex numeric values
2032 An @dfn{expression} specifies an address or numeric value.
2033 Whitespace may precede and/or follow an expression.
2036 * Empty Exprs:: Empty Expressions
2037 * Integer Exprs:: Integer Expressions
2040 @node Empty Exprs, Integer Exprs, Expressions, Expressions
2041 @section Empty Expressions
2043 @cindex empty expressions
2044 @cindex expressions, empty
2045 An empty expression has no value: it is just whitespace or null.
2046 Wherever an absolute expression is required, you may omit the
2047 expression and @code{_AS__} will assume a value of (absolute) 0. This
2048 is compatible with other assemblers.
2050 @node Integer Exprs, , Empty Exprs, Expressions
2051 @section Integer Expressions
2053 @cindex integer expressions
2054 @cindex expressions, integer
2055 An @dfn{integer expression} is one or more @emph{arguments} delimited
2056 by @emph{operators}.
2059 * Arguments:: Arguments
2060 * Operators:: Operators
2061 * Prefix Ops:: Prefix Operators
2062 * Infix Ops:: Infix Operators
2065 @node Arguments, Operators, Integer Exprs, Integer Exprs
2066 @subsection Arguments
2068 @cindex expression arguments
2069 @cindex arguments in expressions
2070 @cindex operands in expressions
2071 @cindex arithmetic operands
2072 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2073 contexts arguments are sometimes called ``arithmetic operands''. In
2074 this manual, to avoid confusing them with the ``instruction operands'' of
2075 the machine language, we use the term ``argument'' to refer to parts of
2076 expressions only, reserving the word ``operand'' to refer only to machine
2077 instruction operands.
2079 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2080 @var{section} is one of text, data, bss, absolute,
2081 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2084 Numbers are usually integers.
2086 A number can be a flonum or bignum. In this case, you are warned
2087 that only the low order 32 bits are used, and @code{_AS__} pretends
2088 these 32 bits are an integer. You may write integer-manipulating
2089 instructions that act on exotic constants, compatible with other
2092 @cindex subexpressions
2093 Subexpressions are a left parenthesis @samp{(} followed by an integer
2094 expression, followed by a right parenthesis @samp{)}; or a prefix
2095 operator followed by an argument.
2097 @node Operators, Prefix Ops, Arguments, Integer Exprs
2098 @subsection Operators
2100 @cindex operators, in expressions
2101 @cindex arithmetic functions
2102 @cindex functions, in expressions
2103 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2104 operators are followed by an argument. Infix operators appear
2105 between their arguments. Operators may be preceded and/or followed by
2108 @node Prefix Ops, Infix Ops, Operators, Integer Exprs
2109 @subsection Prefix Operator
2111 @cindex prefix operators
2112 @code{_AS__} has the following @dfn{prefix operators}. They each take
2113 one argument, which must be absolute.
2115 @c the tex/end tex stuff surrounding this small table is meant to make
2116 @c it align, on the printed page, with the similar table in the next
2117 @c section (which is inside an enumerate).
2119 \global\advance\leftskip by \itemindent
2124 @dfn{Negation}. Two's complement negation.
2126 @dfn{Complementation}. Bitwise not.
2130 \global\advance\leftskip by -\itemindent
2133 @node Infix Ops, , Prefix Ops, Integer Exprs
2134 @subsection Infix Operators
2136 @cindex infix operators
2137 @cindex operators, permitted arguments
2138 @dfn{Infix operators} take two arguments, one on either side. Operators
2139 have precedence, but operations with equal precedence are performed left
2140 to right. Apart from @code{+} or @code{-}, both arguments must be
2141 absolute, and the result is absolute.
2144 @cindex operator precedence
2145 @cindex precedence of operators
2152 @dfn{Multiplication}.
2155 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2162 @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__}
2166 @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__}
2170 Intermediate precedence
2175 @dfn{Bitwise Inclusive Or}.
2181 @dfn{Bitwise Exclusive Or}.
2184 @dfn{Bitwise Or Not}.
2192 @cindex addition, permitted arguments
2193 @cindex plus, permitted arguments
2194 @cindex arguments for addition
2195 @dfn{Addition}. If either argument is absolute, the result
2196 has the section of the other argument.
2197 If either argument is pass1 or undefined, the result is pass1.
2198 Otherwise @code{+} is illegal.
2201 @cindex subtraction, permitted arguments
2202 @cindex minus, permitted arguments
2203 @cindex arguments for subtraction
2204 @dfn{Subtraction}. If the right argument is absolute, the
2205 result has the section of the left argument.
2206 If either argument is pass1 the result is pass1.
2207 If either argument is undefined the result is difference section.
2208 If both arguments are in the same section, the result is absolute---provided
2209 that section is one of text, data or bss.
2210 Otherwise subtraction is illegal.
2214 The sense of the rule for addition is that it's only meaningful to add
2215 the @emph{offsets} in an address; you can only have a defined section in
2216 one of the two arguments.
2218 Similarly, you can't subtract quantities from two different sections.
2220 @node Pseudo Ops, _MACH_DEP__, Expressions, Top
2221 @chapter Assembler Directives
2223 @cindex directives, machine independent
2224 @cindex pseudo-ops, machine independent
2225 @cindex machine independent directives
2226 All assembler directives have names that begin with a period (@samp{.}).
2227 The rest of the name is letters, usually in lower case.
2229 This chapter discusses directives present regardless of the target
2230 machine configuration for the GNU assembler.
2232 @xref{_MACH_DEP__} for additional directives.
2236 * Abort:: @code{.abort}
2238 * coff-ABORT:: @code{.ABORT}
2240 _if__(_BOUT__&&!_COFF__)
2241 * bout-ABORT:: @code{.ABORT}
2242 _fi__(_BOUT__&&!_COFF__)
2243 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2244 * App-File:: @code{.app-file @var{string}}
2245 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2246 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2247 * Byte:: @code{.byte @var{expressions}}
2248 * Comm:: @code{.comm @var{symbol} , @var{length} }
2249 * Data:: @code{.data @var{subsection}}
2250 _if__(_COFF__||_BOUT__)
2251 * Def:: @code{.def @var{name}}
2252 _fi__(_COFF__||_BOUT__)
2253 _if__(_AOUT__||_BOUT__)
2254 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2255 _fi__(_AOUT__||_BOUT__)
2256 _if__(_COFF__||_BOUT__)
2258 _fi__(_COFF__||_BOUT__)
2259 * Double:: @code{.double @var{flonums}}
2260 * Eject:: @code{.eject}
2261 * Else:: @code{.else}
2262 _if__(_COFF__||_BOUT__)
2263 * Endef:: @code{.endef}
2264 _fi__(_COFF__||_BOUT__)
2265 * Endif:: @code{.endif}
2266 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2267 * Extern:: @code{.extern}
2268 _if__(_GENERIC__||!_A29K__)
2269 * File:: @code{.file @var{string}}
2270 _fi__(_GENERIC__||!_A29K__)
2271 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2272 * Float:: @code{.float @var{flonums}}
2273 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2274 * hword:: @code{.hword @var{expressions}}
2275 * Ident:: @code{.ident}
2276 * If:: @code{.if @var{absolute expression}}
2277 * Include:: @code{.include "@var{file}"}
2278 * Int:: @code{.int @var{expressions}}
2279 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2280 * Lflags:: @code{.lflags}
2281 _if__(_GENERIC__||!_A29K__)
2282 * Line:: @code{.line @var{line-number}}
2283 _fi__(_GENERIC__||!_A29K__)
2284 * Ln:: @code{.ln @var{line-number}}
2285 * List:: @code{.list}
2286 * Long:: @code{.long @var{expressions}}
2287 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2288 * Nolist:: @code{.nolist}
2289 * Octa:: @code{.octa @var{bignums}}
2290 * Org:: @code{.org @var{new-lc} , @var{fill}}
2291 * Psize:: @code{.psize @var{lines}, @var{columns}}
2292 * Quad:: @code{.quad @var{bignums}}
2293 * Sbttl:: @code{.sbttl "@var{subheading}"}
2294 _if__(_COFF__||_BOUT__)
2295 * Scl:: @code{.scl @var{class}}
2296 _fi__(_COFF__||_BOUT__)
2298 * Section:: @code{.section @var{name}, @var{subsection}}
2300 * Set:: @code{.set @var{symbol}, @var{expression}}
2301 * Short:: @code{.short @var{expressions}}
2302 * Single:: @code{.single @var{flonums}}
2303 _if__(_COFF__||_BOUT__)
2304 * Size:: @code{.size}
2305 _fi__(_COFF__||_BOUT__)
2306 * Space:: @code{.space @var{size} , @var{fill}}
2307 _if__(_GENERIC__||!_H8__)
2308 * Stab:: @code{.stabd, .stabn, .stabs}
2309 _fi__(_GENERIC__||!_H8__)
2310 _if__(_COFF__||_BOUT__)
2311 * Tag:: @code{.tag @var{structname}}
2312 _fi__(_COFF__||_BOUT__)
2313 * Text:: @code{.text @var{subsection}}
2314 * Title:: @code{.title "@var{heading}"}
2315 _if__(_COFF__||_BOUT__)
2316 * Type:: @code{.type @var{int}}
2317 * Val:: @code{.val @var{addr}}
2318 _fi__(_COFF__||_BOUT__)
2319 * Word:: @code{.word @var{expressions}}
2320 * Deprecated:: Deprecated Directives
2324 @node Abort, coff-ABORT, Pseudo Ops, Pseudo Ops
2326 _if__((!_COFF__) && _BOUT__)
2327 @node Abort, bout-ABORT, Pseudo Ops, Pseudo Ops
2328 _fi__((!_COFF__) && _BOUT__)
2329 _if__(! (_BOUT__ || _COFF__) )
2330 @node Abort, Align, Pseudo Ops, Pseudo Ops
2331 _fi__(! (_BOUT__ || _COFF__) )
2332 @section @code{.abort}
2334 @cindex @code{abort} directive
2335 @cindex stopping the assembly
2336 This directive stops the assembly immediately. It is for
2337 compatibility with other assemblers. The original idea was that the
2338 assembly language source would be piped into the assembler. If the sender
2339 of the source quit, it could use this directive tells @code{_AS__} to
2340 quit also. One day @code{.abort} will not be supported.
2343 @node coff-ABORT, Align, Abort, Pseudo Ops
2344 @section @code{.ABORT}
2346 @cindex @code{ABORT} directive
2347 When producing COFF output, @code{_AS__} accepts this directive as a
2348 synonym for @samp{.abort}.
2353 @node bout-ABORT, Align, Abort, Pseudo Ops
2354 @section @code{.ABORT}
2356 @cindex @code{ABORT} directive
2359 When producing @code{b.out} output, @code{_AS__} accepts this directive,
2363 _if__( ! (_COFF__ || _BOUT__) )
2364 @node Align, App-File, Abort, Pseudo Ops
2365 _fi__( ! (_COFF__ || _BOUT__) )
2367 @node Align, App-File, coff-ABORT, Pseudo Ops
2369 _if__( _BOUT__ && (! _COFF__))
2370 @node Align, App-File, bout-ABORT, Pseudo Ops
2371 _fi__( _BOUT__ && (! _COFF__))
2372 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2374 @cindex padding the location counter
2375 @cindex @code{align} directive
2376 Pad the location counter (in the current subsection) to a particular
2377 storage boundary. The first expression (which must be absolute) is the
2378 number of low-order zero bits the location counter will have after
2379 advancement. For example @samp{.align 3} will advance the location
2380 counter until it a multiple of 8. If the location counter is already a
2381 multiple of 8, no change is needed.
2383 The second expression (also absolute) gives the value to be stored in
2384 the padding bytes. It (and the comma) may be omitted. If it is
2385 omitted, the padding bytes are zero.
2387 @node App-File, Ascii, Align, Pseudo Ops
2388 @section @code{.app-file @var{string}}
2390 @cindex logical file name
2391 @cindex file name, logical
2392 @cindex @code{app-file} directive
2395 (which may also be spelled @samp{.file})
2397 tells @code{_AS__} that we are about to start a new
2398 logical file. @var{string} is the new file name. In general, the
2399 filename is recognized whether or not it is surrounded by quotes @samp{"};
2400 but if you wish to specify an empty file name is permitted,
2401 you must give the quotes--@code{""}. This statement may go away in
2402 future: it is only recognized to be compatible with old @code{_AS__}
2405 @node Ascii, Asciz, App-File, Pseudo Ops
2406 @section @code{.ascii "@var{string}"}@dots{}
2408 @cindex @code{ascii} directive
2409 @cindex string literals
2410 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2411 separated by commas. It assembles each string (with no automatic
2412 trailing zero byte) into consecutive addresses.
2414 @node Asciz, Byte, Ascii, Pseudo Ops
2415 @section @code{.asciz "@var{string}"}@dots{}
2417 @cindex @code{asciz} directive
2418 @cindex zero-terminated strings
2419 @cindex null-terminated strings
2420 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2421 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2423 @node Byte, Comm, Asciz, Pseudo Ops
2424 @section @code{.byte @var{expressions}}
2426 @cindex @code{byte} directive
2427 @cindex integers, one byte
2428 @code{.byte} expects zero or more expressions, separated by commas.
2429 Each expression is assembled into the next byte.
2431 @node Comm, Data, Byte, Pseudo Ops
2432 @section @code{.comm @var{symbol} , @var{length} }
2434 @cindex @code{comm} directive
2435 @cindex symbol, common
2436 @code{.comm} declares a named common area in the bss section. Normally
2437 @code{_LD__} reserves memory addresses for it during linking, so no partial
2438 program defines the location of the symbol. Use @code{.comm} to tell
2439 @code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__}
2440 will allocate space for each @code{.comm} symbol that is at least as
2441 long as the longest @code{.comm} request in any of the partial programs
2442 linked. @var{length} is an absolute expression.
2444 _if__(_COFF__ || _BOUT__)
2445 @node Data, Def, Comm, Pseudo Ops
2446 _fi__(_COFF__ || _BOUT__)
2447 _if__(!(_COFF__ || _BOUT__) && _AOUT__)
2448 @node Data, Desc, Comm, Pseudo Ops
2449 _fi__(!(_COFF__ || _BOUT__) && _AOUT__)
2450 _if__(! (_COFF__ || _BOUT__ || _AOUT__) )
2451 @c Well, this *might* happen...
2452 @node Data, Double, Comm, Pseudo Ops
2453 _fi__(! (_COFF__ || _BOUT__ || _AOUT__) )
2454 @section @code{.data @var{subsection}}
2456 @cindex @code{data} directive
2457 @code{.data} tells @code{_AS__} to assemble the following statements onto the
2458 end of the data subsection numbered @var{subsection} (which is an
2459 absolute expression). If @var{subsection} is omitted, it defaults
2462 _if__(_COFF__ || _BOUT__)
2463 _if__(_AOUT__ || _BOUT__)
2464 @node Def, Desc, Data, Pseudo Ops
2465 _fi__(_AOUT__ || _BOUT__)
2466 _if__(!(_AOUT__ || _BOUT__))
2467 @node Def, Dim, Data, Pseudo Ops
2468 _fi__(!(_AOUT__ || _BOUT__))
2469 @section @code{.def @var{name}}
2471 @cindex @code{def} directive
2472 @cindex COFF symbols, debugging
2473 @cindex debugging COFF symbols
2474 Begin defining debugging information for a symbol @var{name}; the
2475 definition extends until the @code{.endef} directive is encountered.
2478 This directive is only observed when @code{_AS__} is configured for COFF
2479 format output; when producing @code{b.out}, @samp{.def} is recognized,
2482 _fi__(_COFF__ || _BOUT__)
2484 _if__(_AOUT__||_BOUT__)
2485 _if__(_COFF__||_BOUT__)
2486 @node Desc, Dim, Def, Pseudo Ops
2487 _fi__(_COFF__||_BOUT__)
2488 _if__(!(_COFF__||_BOUT__))
2489 @node Desc, Double, Data, Pseudo Ops
2490 _fi__(!(_COFF__||_BOUT__))
2491 @section @code{.desc @var{symbol}, @var{abs-expression}}
2493 @cindex @code{desc} directive
2494 @cindex COFF symbol descriptor
2495 @cindex symbol descriptor, COFF
2496 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2497 to the low 16 bits of an absolute expression.
2500 The @samp{.desc} directive is not available when @code{_AS__} is
2501 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2502 object format. For the sake of compatibility, @code{_AS__} will accept
2503 it, but produce no output, when configured for COFF.
2505 _fi__(_AOUT__||_BOUT__)
2507 _if__(_COFF__ || _BOUT__)
2508 _if__(_AOUT__ || _BOUT__)
2509 @node Dim, Double, Desc, Pseudo Ops
2510 _fi__(_AOUT__ || _BOUT__)
2511 _if__(!(_AOUT__ || _BOUT__))
2512 @node Dim, Double, Def, Pseudo Ops
2513 _fi__(!(_AOUT__ || _BOUT__))
2514 @section @code{.dim}
2516 @cindex @code{dim} directive
2517 @cindex COFF auxiliary symbol information
2518 @cindex auxiliary symbol information, COFF
2519 This directive is generated by compilers to include auxiliary debugging
2520 information in the symbol table. It is only permitted inside
2521 @code{.def}/@code{.endef} pairs.
2524 @samp{.dim} is only meaningful when generating COFF format output; when
2525 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2528 _fi__(_COFF__ || _BOUT__)
2530 _if__(_COFF__||_BOUT__)
2531 @node Double, Eject, Dim, Pseudo Ops
2532 _fi__(_COFF__||_BOUT__)
2533 _if__(!(_COFF__||_BOUT__))
2534 @node Double, Eject, Desc, Pseudo Ops
2535 _fi__(!(_COFF__||_BOUT__))
2536 @section @code{.double @var{flonums}}
2538 @cindex @code{double} directive
2539 @cindex floating point numbers (double)
2540 @code{.double} expects zero or more flonums, separated by commas. It
2541 assembles floating point numbers.
2543 The exact kind of floating point numbers emitted depends on how
2544 @code{_AS__} is configured. @xref{_MACH_DEP__}.
2546 _if__((!_GENERIC__) && _IEEEFLOAT__)
2547 On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers
2548 in @sc{ieee} format.
2549 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2551 @node Eject, Else, Double, Pseudo Ops
2552 @section @code{.eject}
2554 @cindex @code{eject} directive
2555 @cindex new page, in listings
2556 @cindex page, in listings
2557 @cindex listing control: new page
2558 Force a page break at this point, when generating assembly listings.
2560 _if__(_COFF__||_BOUT__)
2561 @node Else, Endef, Eject, Pseudo Ops
2562 _fi__(_COFF__||_BOUT__)
2563 _if__(!(_COFF__||_BOUT__))
2564 @node Else, Endif, Eject, Pseudo Ops
2565 _fi__(!(_COFF__||_BOUT__))
2566 @section @code{.else}
2568 @cindex @code{else} directive
2569 @code{.else} is part of the @code{_AS__} support for conditional
2570 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2571 of code to be assembled if the condition for the preceding @code{.if}
2575 @node End, Endef, Else, Pseudo Ops
2576 @section @code{.end}
2578 @cindex @code{end} directive
2579 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2580 meant to do something eventually (which is why it isn't documented here
2581 as "for compatibility with blah").
2584 _if__(_COFF__||_BOUT__)
2585 @node Endef, Endif, Else, Pseudo Ops
2586 @section @code{.endef}
2588 @cindex @code{endef} directive
2589 This directive flags the end of a symbol definition begun with
2593 @samp{.endef} is only meaningful when generating COFF format output; if
2594 @code{_AS__} is configured to generate @code{b.out}, it accepts this
2595 directive but ignores it.
2597 _fi__(_COFF__||_BOUT__)
2599 _if__(_COFF__||_BOUT__)
2600 @node Endif, Equ, Endef, Pseudo Ops
2601 _fi__(_COFF__||_BOUT__)
2602 _if__(!(_COFF__||_BOUT__))
2603 @node Endif, Equ, Else, Pseudo Ops
2604 _fi__(!(_COFF__||_BOUT__))
2605 @section @code{.endif}
2607 @cindex @code{endif} directive
2608 @code{.endif} is part of the @code{_AS__} support for conditional assembly;
2609 it marks the end of a block of code that is only assembled
2610 conditionally. @xref{If,,@code{.if}}.
2612 @node Equ, Extern, Endif, Pseudo Ops
2613 @section @code{.equ @var{symbol}, @var{expression}}
2615 @cindex @code{equ} directive
2616 @cindex assigning values to symbols
2617 @cindex symbols, assigning values to
2618 This directive sets the value of @var{symbol} to @var{expression}.
2619 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2621 _if__(_GENERIC__||!_A29K__)
2622 @node Extern, File, Equ, Pseudo Ops
2623 _fi__(_GENERIC__||!_A29K__)
2624 _if__(_A29K__&&!_GENERIC__)
2625 @node Extern, Fill, Equ, Pseudo Ops
2626 _fi__(_A29K__&&!_GENERIC__)
2627 @section @code{.extern}
2629 @cindex @code{extern} directive
2630 @code{.extern} is accepted in the source program---for compatibility
2631 with other assemblers---but it is ignored. @code{_AS__} treats
2632 all undefined symbols as external.
2634 _if__(_GENERIC__||!_A29K__)
2635 @node File, Fill, Extern, Pseudo Ops
2636 @section @code{.file @var{string}}
2638 @cindex @code{file} directive
2639 @cindex logical file name
2640 @cindex file name, logical
2641 @code{.file} (which may also be spelled @samp{.app-file}) tells
2642 @code{_AS__} that we are about to start a new logical file.
2643 @var{string} is the new file name. In general, the filename is
2644 recognized whether or not it is surrounded by quotes @samp{"}; but if
2645 you wish to specify an empty file name, you must give the
2646 quotes--@code{""}. This statement may go away in future: it is only
2647 recognized to be compatible with old @code{_AS__} programs.
2649 In some configurations of @code{_AS__}, @code{.file} has already been
2650 removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}.
2652 _fi__(_GENERIC__||!_A29K__)
2654 _if__(_GENERIC__||!_A29K__)
2655 @node Fill, Float, File, Pseudo Ops
2656 _fi__(_GENERIC__||!_A29K__)
2657 _if__(_A29K__&&!_GENERIC__)
2658 @node Fill, Float, Extern, Pseudo Ops
2659 _fi__(_A29K__&&!_GENERIC__)
2660 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2662 @cindex @code{fill} directive
2663 @cindex writing patterns in memory
2664 @cindex patterns, writing in memory
2665 @var{result}, @var{size} and @var{value} are absolute expressions.
2666 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2667 may be zero or more. @var{Size} may be zero or more, but if it is
2668 more than 8, then it is deemed to have the value 8, compatible with
2669 other people's assemblers. The contents of each @var{repeat} bytes
2670 is taken from an 8-byte number. The highest order 4 bytes are
2671 zero. The lowest order 4 bytes are @var{value} rendered in the
2672 byte-order of an integer on the computer @code{_AS__} is assembling for.
2673 Each @var{size} bytes in a repetition is taken from the lowest order
2674 @var{size} bytes of this number. Again, this bizarre behavior is
2675 compatible with other people's assemblers.
2677 @var{size} and @var{value} are optional.
2678 If the second comma and @var{value} are absent, @var{value} is
2679 assumed zero. If the first comma and following tokens are absent,
2680 @var{size} is assumed to be 1.
2682 @node Float, Global, Fill, Pseudo Ops
2683 @section @code{.float @var{flonums}}
2685 @cindex floating point numbers (single)
2686 @cindex @code{float} directive
2687 This directive assembles zero or more flonums, separated by commas. It
2688 has the same effect as @code{.single}.
2690 The exact kind of floating point numbers emitted depends on how
2691 @code{_AS__} is configured.
2694 _if__((!_GENERIC__) && _IEEEFLOAT__)
2695 On the _HOST__ family, @code{.float} emits 32-bit floating point numbers
2696 in @sc{ieee} format.
2697 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2699 @node Global, hword, Float, Pseudo Ops
2700 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2702 @cindex @code{global} directive
2703 @cindex symbol, making visible to linker
2704 @code{.global} makes the symbol visible to @code{_LD__}. If you define
2705 @var{symbol} in your partial program, its value is made available to
2706 other partial programs that are linked with it. Otherwise,
2707 @var{symbol} will take its attributes from a symbol of the same name
2708 from another partial program it is linked with.
2710 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2711 compatibility with other assemblers.
2713 _if__(_AOUT__||_BOUT__||_COFF__)
2714 @node hword, Ident, Global, Pseudo Ops
2715 _fi__(_AOUT__||_BOUT__||_COFF__)
2716 _if__(!(_AOUT__||_BOUT__||_COFF__))
2717 @node hword, If, Global, Pseudo Ops
2718 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2719 @section @code{.hword @var{expressions}}
2721 @cindex @code{hword} directive
2722 @cindex integers, 16-bit
2723 @cindex numbers, 16-bit
2724 @cindex sixteen bit integers
2725 This expects zero or more @var{expressions}, and emits
2726 a 16 bit number for each.
2729 This directive is a synonym for @samp{.short}; depending on the target
2730 architecture, it may also be a synonym for @samp{.word}.
2732 _if__( _W32__ && !_GENERIC__ )
2733 This directive is a synonym for @samp{.short}.
2734 _fi__( _W32__ && !_GENERIC__ )
2735 _if__(_W16__ && !_GENERIC__ )
2736 This directive is a synonym for both @samp{.short} and @samp{.word}.
2737 _fi__(_W16__ && !_GENERIC__ )
2739 _if__(_AOUT__||_BOUT__||_COFF__)
2740 @node Ident, If, hword, Pseudo Ops
2741 @section @code{.ident}
2743 @cindex @code{ident} directive
2744 This directive is used by some assemblers to place tags in object files.
2745 @code{_AS__} simply accepts the directive for source-file
2746 compatibility with such assemblers, but does not actually emit anything
2748 _fi__(_AOUT__||_BOUT__||_COFF__)
2750 _if__(_AOUT__||_BOUT__||_COFF__)
2751 @node If, Include, Ident, Pseudo Ops
2752 _fi__(_AOUT__||_BOUT__||_COFF__)
2753 _if__(!(_AOUT__||_BOUT__||_COFF__))
2754 @node If, Include, hword, Pseudo Ops
2755 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2756 @section @code{.if @var{absolute expression}}
2758 @cindex conditional assembly
2759 @cindex @code{if} directive
2760 @code{.if} marks the beginning of a section of code which is only
2761 considered part of the source program being assembled if the argument
2762 (which must be an @var{absolute expression}) is non-zero. The end of
2763 the conditional section of code must be marked by @code{.endif}
2764 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
2765 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
2767 The following variants of @code{.if} are also supported:
2769 @item .ifdef @var{symbol}
2770 @cindex @code{ifdef} directive
2771 Assembles the following section of code if the specified @var{symbol}
2776 @cindex @code{ifeqs} directive
2777 Not yet implemented.
2780 @item .ifndef @var{symbol}
2781 @itemx ifnotdef @var{symbol}
2782 @cindex @code{ifndef} directive
2783 @cindex @code{ifnotdef} directive
2784 Assembles the following section of code if the specified @var{symbol}
2785 has not been defined. Both spelling variants are equivalent.
2789 Not yet implemented.
2793 @node Include, Int, If, Pseudo Ops
2794 @section @code{.include "@var{file}"}
2796 @cindex @code{include} directive
2797 @cindex supporting files, including
2798 @cindex files, including
2799 This directive provides a way to include supporting files at specified
2800 points in your source program. The code from @var{file} is assembled as
2801 if it followed the point of the @code{.include}; when the end of the
2802 included file is reached, assembly of the original file continues. You
2803 can control the search paths used with the @samp{-I} command-line option
2804 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
2807 @node Int, Lcomm, Include, Pseudo Ops
2808 @section @code{.int @var{expressions}}
2810 @cindex @code{int} directive
2811 _if__(_GENERIC__||!_H8__)
2812 @cindex integers, 32-bit
2813 _fi__(_GENERIC__||!_H8__)
2814 Expect zero or more @var{expressions}, of any section, separated by
2815 commas. For each expression, emit a
2816 _if__(_GENERIC__||!_H8__)
2818 _fi__(_GENERIC__||!_H8__)
2819 _if__(_H8__&&!_GENERIC__)
2821 _fi__(_H8__&&!_GENERIC__)
2822 number that will, at run
2823 time, be the value of that expression. The byte order of the
2824 expression depends on what kind of computer will run the program.
2826 @node Lcomm, Lflags, Int, Pseudo Ops
2827 @section @code{.lcomm @var{symbol} , @var{length}}
2829 @cindex @code{lcomm} directive
2830 @cindex local common symbols
2831 @cindex symbols, local common
2832 Reserve @var{length} (an absolute expression) bytes for a local common
2833 denoted by @var{symbol}. The section and value of @var{symbol} are
2834 those of the new local common. The addresses are allocated in the bss
2835 section, so at run-time the bytes will start off zeroed. @var{Symbol}
2836 is not declared global (@pxref{Global,,@code{.global}}), so is normally
2837 not visible to @code{_LD__}.
2839 _if__(_GENERIC__||(!_A29K__))
2840 @node Lflags, Line, Lcomm, Pseudo Ops
2841 _fi__(_GENERIC__||(!_A29K__))
2842 _if__((!_GENERIC__)&& _A29K__)
2843 @node Lflags, Ln, Lcomm, Pseudo Ops
2844 _fi__((!_GENERIC__)&& _A29K__)
2845 @section @code{.lflags}
2847 @cindex @code{lflags} directive (ignored)
2848 @code{_AS__} accepts this directive, for compatibility with other
2849 assemblers, but ignores it.
2851 _if__(_GENERIC__ || !_A29K__)
2852 @node Line, Ln, Lflags, Pseudo Ops
2853 @section @code{.line @var{line-number}}
2855 @cindex @code{line} directive
2856 _fi__(_GENERIC__ || (!_A29K__))
2857 _if__(_A29K__ && (!_GENERIC__))
2858 @node Ln, List, Lflags, Pseudo Ops
2859 @section @code{.ln @var{line-number}}
2861 @cindex @code{ln} directive
2862 _fi__(_A29K__ && (!_GENERIC__))
2863 @cindex logical line number
2864 _if__(_AOUT__||_BOUT__)
2865 Tell @code{_AS__} to change the logical line number. @var{line-number} must be
2866 an absolute expression. The next line will have that logical line
2867 number. So any other statements on the current line (after a statement
2873 _if__(! (_A29K__||_H8__) )
2875 _fi__(! (_A29K__||_H8__) )
2877 character @samp{@@})
2883 will be reported as on logical line number
2884 @var{line-number} @minus{} 1.
2885 One day this directive will be unsupported: it is used only
2886 for compatibility with existing assembler programs. @refill
2888 _if__(_GENERIC__ && _A29K__)
2889 @emph{Warning:} In the AMD29K configuration of _AS__, this command is
2890 only available with the name @code{.ln}, rather than as either
2891 @code{.line} or @code{.ln}.
2892 _fi__(_GENERIC__ && _A29K__)
2893 _fi__(_AOUT__||_BOUT__)
2896 Even though this is a directive associated with the @code{a.out} or
2897 @code{b.out} object-code formats, @code{_AS__} will still recognize it
2898 when producing COFF output, and will treat @samp{.line} as though it
2899 were the COFF @samp{.ln} @emph{if} it is found outside a
2900 @code{.def}/@code{.endef} pair.
2902 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
2903 used by compilers to generate auxiliary symbol information for
2907 _if__(_AOUT__&&(_GENERIC__||!_A29K__))
2908 @node Ln, List, Line, Pseudo Ops
2909 @section @code{.ln @var{line-number}}
2911 @cindex @code{ln} directive
2912 @samp{.ln} is a synonym for @samp{.line}.
2913 _fi__(_AOUT__&&(_GENERIC__||!_A29K__))
2914 _if__(_COFF__&&!_AOUT__)
2915 @node Ln, List, Line, Pseudo Ops
2916 @section @code{.ln @var{line-number}}
2918 @cindex @code{ln} directive
2919 Tell @code{_AS__} to change the logical line number. @var{line-number}
2920 must be an absolute expression. The next line will have that logical
2921 line number, so any other statements on the current line (after a
2922 statement separator character @code{;}) will be reported as on logical
2923 line number @var{line-number} @minus{} 1.
2926 This directive is accepted, but ignored, when @code{_AS__} is configured for
2927 @code{b.out}; its effect is only associated with COFF output format.
2929 _fi__(_COFF__&&!_AOUT__)
2931 @node List, Long, Ln, Pseudo Ops
2932 @section @code{.list}
2934 @cindex @code{list} directive
2935 @cindex listing control, turning on
2936 Control (in conjunction with the @code{.nolist} directive) whether or
2937 not assembly listings are generated. These two directives maintain an
2938 internal counter (which is zero initially). @code{.list} increments the
2939 counter, and @code{.nolist} decrements it. Assembly listings are
2940 generated whenever the counter is greater than zero.
2942 By default, listings are disabled. When you enable them (with the
2943 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
2944 the initial value of the listing counter is one.
2946 @node Long, Lsym, List, Pseudo Ops
2947 @section @code{.long @var{expressions}}
2949 @cindex @code{long} directive
2950 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
2952 @node Lsym, Nolist, Long, Pseudo Ops
2953 @section @code{.lsym @var{symbol}, @var{expression}}
2955 @cindex @code{lsym} directive
2956 @cindex symbol, not referenced in assembly
2957 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
2958 the hash table, ensuring it cannot be referenced by name during the
2959 rest of the assembly. This sets the attributes of the symbol to be
2960 the same as the expression value:
2962 @var{other} = @var{descriptor} = 0
2963 @var{type} = @r{(section of @var{expression})}
2964 @var{value} = @var{expression}
2967 The new symbol is not flagged as external.
2969 @node Nolist, Octa, Lsym, Pseudo Ops
2970 @section @code{.nolist}
2972 @cindex @code{nolist} directive
2973 @cindex listing control, turning off
2974 Control (in conjunction with the @code{.list} directive) whether or
2975 not assembly listings are generated. These two directives maintain an
2976 internal counter (which is zero initially). @code{.list} increments the
2977 counter, and @code{.nolist} decrements it. Assembly listings are
2978 generated whenever the counter is greater than zero.
2980 @node Octa, Org, Nolist, Pseudo Ops
2981 @section @code{.octa @var{bignums}}
2983 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
2984 @cindex @code{octa} directive
2985 @cindex integer, 16-byte
2986 @cindex sixteen byte integer
2987 This directive expects zero or more bignums, separated by commas. For each
2988 bignum, it emits a 16-byte integer.
2990 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
2991 hence @emph{octa}-word for 16 bytes.
2993 @node Org, Psize, Octa, Pseudo Ops
2994 @section @code{.org @var{new-lc} , @var{fill}}
2996 @cindex @code{org} directive
2997 @cindex location counter, advancing
2998 @cindex advancing location counter
2999 @cindex current address, advancing
3000 @code{.org} will advance the location counter of the current section to
3001 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3002 expression with the same section as the current subsection. That is,
3003 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3004 wrong section, the @code{.org} directive is ignored. To be compatible
3005 with former assemblers, if the section of @var{new-lc} is absolute,
3006 @code{_AS__} will issue a warning, then pretend the section of @var{new-lc}
3007 is the same as the current subsection.
3009 @code{.org} may only increase the location counter, or leave it
3010 unchanged; you cannot use @code{.org} to move the location counter
3013 @c double negative used below "not undefined" because this is a specific
3014 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3015 @c section. pesch@cygnus.com 18feb91
3016 Because @code{_AS__} tries to assemble programs in one pass @var{new-lc}
3017 may not be undefined. If you really detest this restriction we eagerly await
3018 a chance to share your improved assembler.
3020 Beware that the origin is relative to the start of the section, not
3021 to the start of the subsection. This is compatible with other
3022 people's assemblers.
3024 When the location counter (of the current subsection) is advanced, the
3025 intervening bytes are filled with @var{fill} which should be an
3026 absolute expression. If the comma and @var{fill} are omitted,
3027 @var{fill} defaults to zero.
3029 @node Psize, Quad, Org, Pseudo Ops
3030 @section @code{.psize @var{lines} , @var{columns}}
3032 @cindex @code{psize} directive
3033 @cindex listing control: paper size
3034 @cindex paper size, for listings
3035 Use this directive to declare the number of lines---and, optionally, the
3036 number of columns---to use for each page, when generating listings.
3038 If you don't use @code{.psize}, listings will use a default line-count
3039 of 60. You may omit the comma and @var{columns} specification; the
3040 default width is 200 columns.
3042 @code{_AS__} will generate formfeeds whenever the specified number of
3043 lines is exceeded (or whenever you explicitly request one, using
3046 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3047 those explicitly specified with @code{.eject}.
3049 @node Quad, Sbttl, Psize, Pseudo Ops
3050 @section @code{.quad @var{bignums}}
3052 @cindex @code{quad} directive
3053 @code{.quad} expects zero or more bignums, separated by commas. For
3054 each bignum, it emits
3055 _if__(_GENERIC__||(!_I960__))
3056 an 8-byte integer. If the bignum won't fit in 8
3057 bytes, it prints a warning message; and just takes the lowest order 8
3058 bytes of the bignum.@refill
3059 @cindex eight-byte integer
3060 @cindex integer, 8-byte
3062 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3063 hence @emph{quad}-word for 8 bytes.
3064 _fi__(_GENERIC__||(!_I960__))
3065 _if__(_I960__&&(!_GENERIC__))
3066 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3067 warning message; and just takes the lowest order 16 bytes of the
3069 @cindex sixteen-byte integer
3070 @cindex integer, 16-byte
3071 _fi__(_I960__&&(!_GENERIC__))
3073 _if__(_COFF__||_BOUT__)
3074 @node Sbttl, Scl, Quad, Pseudo Ops
3075 _fi__(_COFF__||_BOUT__)
3076 _if__(!(_COFF__||_BOUT__))
3077 @node Sbttl, Set, Quad, Pseudo Ops
3078 _fi__(!(_COFF__||_BOUT__))
3079 @section @code{.sbttl "@var{subheading}"}
3081 @cindex @code{sbttl} directive
3082 @cindex subtitles for listings
3083 @cindex listing control: subtitle
3084 Use @var{subheading} as the title (third line, immediately after the
3085 title line) when generating assembly listings.
3087 This directive affects subsequent pages, as well as the current page if
3088 it appears within ten lines of the top of a page.
3090 _if__(_COFF__||_BOUT__)
3092 @node Scl, Set, Sbttl, Pseudo Ops
3095 @node Scl, Section, Sbttl, Pseudo Ops
3097 @section @code{.scl @var{class}}
3099 @cindex @code{scl} directive
3100 @cindex symbol storage class (COFF)
3101 @cindex COFF symbol storage class
3102 Set the storage-class value for a symbol. This directive may only be
3103 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3104 whether a symbol is static or external, or it may record further
3105 symbolic debugging information.
3108 The @samp{.scl} directive is primarily associated with COFF output; when
3109 configured to generate @code{b.out} output format, @code{_AS__} will
3110 accept this directive but ignore it.
3112 _fi__(_COFF__||_BOUT__)
3115 @node Section, Set, Scl, Pseudo Ops
3116 @section @code{.section @var{name}, @var{subsection}}
3118 @cindex @code{section} directive
3119 @cindex named section (COFF)
3120 @cindex COFF named section
3121 Assemble the following code into end of subsection numbered
3122 @var{subsection} in the COFF named section @var{name}. If you omit
3123 @var{subsection}, @code{_AS__} uses subsection number zero.
3124 @samp{.section .text} is equivalent to the @code{.text} directive;
3125 @samp{.section .data} is equivalent to the @code{.data} directive.
3127 @node Set, Short, Section, Pseudo Ops
3129 _if__(_BOUT__&&!_COFF__)
3130 @node Set, Short, Scl, Pseudo Ops
3131 _fi__(_BOUT__&&!_COFF__)
3132 _if__(!(_COFF__||_BOUT__))
3133 @node Set, Short, Quad, Pseudo Ops
3134 _fi__(!(_COFF__||_BOUT__))
3135 @section @code{.set @var{symbol}, @var{expression}}
3137 @cindex @code{set} directive
3138 @cindex symbol value, setting
3139 This directive sets the value of @var{symbol} to @var{expression}. This
3140 will change @var{symbol}'s value and type to conform to
3141 @var{expression}. If @var{symbol} was flagged as external, it remains
3142 flagged. (@xref{Symbol Attributes}.)
3144 You may @code{.set} a symbol many times in the same assembly.
3145 If the expression's section is unknowable during pass 1, a second
3146 pass over the source program will be forced. The second pass is
3147 currently not implemented. @code{_AS__} will abort with an error
3148 message if one is required.
3150 If you @code{.set} a global symbol, the value stored in the object
3151 file is the last value stored into it.
3153 @node Short, Single, Set, Pseudo Ops
3154 @section @code{.short @var{expressions}}
3156 @cindex @code{short} directive
3157 _if__(_GENERIC__ || _W16__)
3158 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3160 In some configurations, however, @code{.short} and @code{.word} generate
3161 numbers of different lengths; @pxref{_MACH_DEP__}.
3163 _fi__(_GENERIC__|| _W16__)
3164 _if__((!_GENERIC__) && _W32__)
3165 This expects zero or more @var{expressions}, and emits
3166 a 16 bit number for each.
3167 _fi__((!_GENERIC__) && _W32__)
3168 _if__(_COFF__||_BOUT__)
3169 @node Single, Size, Short, Pseudo Ops
3170 _fi__(_COFF__||_BOUT__)
3171 _if__(!(_COFF__||_BOUT__))
3172 @node Single, Space, Short, Pseudo Ops
3173 _fi__(!(_COFF__||_BOUT__))
3174 @section @code{.single @var{flonums}}
3176 @cindex @code{single} directive
3177 @cindex floating point numbers (single)
3178 This directive assembles zero or more flonums, separated by commas. It
3179 has the same effect as @code{.float}.
3181 The exact kind of floating point numbers emitted depends on how
3182 @code{_AS__} is configured. @xref{_MACH_DEP__}.
3184 _if__((!_GENERIC__) && _IEEEFLOAT__)
3185 On the _HOST__ family, @code{.single} emits 32-bit floating point
3186 numbers in @sc{ieee} format.
3187 _fi__((!_GENERIC__) && _IEEEFLOAT__)
3189 _if__(_COFF__||_BOUT__)
3190 @node Size, Space, Single, Pseudo Ops
3191 @section @code{.size}
3193 @cindex @code{size} directive
3194 This directive is generated by compilers to include auxiliary debugging
3195 information in the symbol table. It is only permitted inside
3196 @code{.def}/@code{.endef} pairs.
3199 @samp{.size} is only meaningful when generating COFF format output; when
3200 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3203 _fi__(_COFF__||_BOUT__)
3205 _if__(_H8__&&!_GENERIC__)
3206 @node Space, Tag, Size, Pseudo Ops
3207 _fi__(_H8__&&!_GENERIC__)
3208 _if__(_GENERIC__||!_H8__)
3209 _if__(_COFF__||_BOUT__)
3210 @node Space, Stab, Size, Pseudo Ops
3211 _fi__(_COFF__||_BOUT__)
3212 _if__(!(_COFF__||_BOUT__))
3213 @node Space, Stab, Single, Pseudo Ops
3214 _fi__(!(_COFF__||_BOUT__))
3215 _fi__(_GENERIC__||!_H8__)
3216 _if__(_GENERIC__ || !_A29K__)
3217 @section @code{.space @var{size} , @var{fill}}
3219 @cindex @code{space} directive
3220 @cindex filling memory
3221 This directive emits @var{size} bytes, each of value @var{fill}. Both
3222 @var{size} and @var{fill} are absolute expressions. If the comma
3223 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3224 _fi__(_GENERIC__ || !_A29K__)
3228 @section @code{.space}
3229 @cindex @code{space} directive
3231 On the AMD 29K, this directive is ignored; it is accepted for
3232 compatibility with other AMD 29K assemblers.
3235 @emph{Warning:} In other versions of the GNU assembler, the directive
3236 @code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}.
3240 _if__(_GENERIC__||!_H8__)
3241 _if__(_AOUT__||_BOUT__||_COFF__)
3242 _if__(_COFF__||_BOUT__)
3243 @node Stab, Tag, Space, Pseudo Ops
3244 _fi__(_COFF__||_BOUT__)
3245 _if__(!(_COFF__||_BOUT__))
3246 @node Stab, Text, Space, Pseudo Ops
3247 _fi__(!(_COFF__||_BOUT__))
3248 @section @code{.stabd, .stabn, .stabs}
3250 @cindex symbolic debuggers, information for
3251 @cindex @code{stab@var{x}} directives
3252 There are three directives that begin @samp{.stab}.
3253 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3254 The symbols are not entered in the @code{_AS__} hash table: they
3255 cannot be referenced elsewhere in the source file.
3256 Up to five fields are required:
3259 This is the symbol's name. It may contain any character except @samp{\000},
3260 so is more general than ordinary symbol names. Some debuggers used to
3261 code arbitrarily complex structures into symbol names using this field.
3263 An absolute expression. The symbol's type is set to the low 8
3264 bits of this expression.
3265 Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on
3268 An absolute expression.
3269 The symbol's ``other'' attribute is set to the low 8 bits of this expression.
3271 An absolute expression.
3272 The symbol's descriptor is set to the low 16 bits of this expression.
3274 An absolute expression which becomes the symbol's value.
3277 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3278 or @code{.stabs} statement, the symbol has probably already been created
3279 and you will get a half-formed symbol in your object file. This is
3280 compatible with earlier assemblers!
3283 @cindex @code{stabd} directive
3284 @item .stabd @var{type} , @var{other} , @var{desc}
3286 The ``name'' of the symbol generated is not even an empty string.
3287 It is a null pointer, for compatibility. Older assemblers used a
3288 null pointer so they didn't waste space in object files with empty
3291 The symbol's value is set to the location counter,
3292 relocatably. When your program is linked, the value of this symbol
3293 will be where the location counter was when the @code{.stabd} was
3296 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3297 @cindex @code{stabn} directive
3298 The name of the symbol is set to the empty string @code{""}.
3300 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3301 @cindex @code{stabs} directive
3302 All five fields are specified.
3304 _fi__(_AOUT__||_BOUT__||_COFF__)
3305 _fi__(_GENERIC__||!_H8__)
3307 _if__(_COFF__||_BOUT__)
3308 _if__(_GENERIC__||!_H8__)
3309 @node Tag, Text, Stab, Pseudo Ops
3310 _fi__(_GENERIC__||!_H8__)
3311 _if__(_H8__&&!_GENERIC__)
3312 @node Tag, Text, Space, Pseudo Ops
3313 _fi__(_H8__&&!_GENERIC__)
3314 @section @code{.tag @var{structname}}
3316 @cindex COFF structure debugging
3317 @cindex structure debugging, COFF
3318 @cindex @code{tag} directive
3319 This directive is generated by compilers to include auxiliary debugging
3320 information in the symbol table. It is only permitted inside
3321 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3322 definitions in the symbol table with instances of those structures.
3325 @samp{.tag} is only used when generating COFF format output; when
3326 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3329 _fi__(_COFF__||_BOUT__)
3331 _if__(_COFF__||_BOUT__)
3332 @node Text, Title, Tag, Pseudo Ops
3333 _fi__(_COFF__||_BOUT__)
3334 _if__(!(_COFF__||_BOUT__))
3335 @node Text, Title, Stab, Pseudo Ops
3336 _fi__(!(_COFF__||_BOUT__))
3337 @section @code{.text @var{subsection}}
3339 @cindex @code{text} directive
3340 Tells @code{_AS__} to assemble the following statements onto the end of
3341 the text subsection numbered @var{subsection}, which is an absolute
3342 expression. If @var{subsection} is omitted, subsection number zero
3345 _if__(_COFF__||_BOUT__)
3346 @node Title, Type, Text, Pseudo Ops
3347 _fi__(_COFF__||_BOUT__)
3348 _if__(!(_COFF__||_BOUT__))
3349 @node Title, Word, Text, Pseudo Ops
3350 _fi__(!(_COFF__||_BOUT__))
3351 @section @code{.title "@var{heading}"}
3353 @cindex @code{title} directive
3354 @cindex listing control: title line
3355 Use @var{heading} as the title (second line, immediately after the
3356 source file name and pagenumber) when generating assembly listings.
3358 This directive affects subsequent pages, as well as the current page if
3359 it appears within ten lines of the top of a page.
3361 _if__(_COFF__||_BOUT__)
3362 @node Type, Val, Title, Pseudo Ops
3363 @section @code{.type @var{int}}
3365 @cindex COFF symbol type
3366 @cindex symbol type, COFF
3367 @cindex @code{type} directive
3368 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3369 records the integer @var{int} as the type attribute of a symbol table entry.
3372 @samp{.type} is associated only with COFF format output; when
3373 @code{_AS__} is configured for @code{b.out} output, it accepts this
3374 directive but ignores it.
3376 _fi__(_COFF__||_BOUT__)
3378 _if__(_COFF__||_BOUT__)
3379 @node Val, Word, Type, Pseudo Ops
3380 @section @code{.val @var{addr}}
3382 @cindex @code{val} directive
3383 @cindex COFF value attribute
3384 @cindex value attribute, COFF
3385 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3386 records the address @var{addr} as the value attribute of a symbol table
3390 @samp{.val} is used only for COFF output; when @code{_AS__} is
3391 configured for @code{b.out}, it accepts this directive but ignores it.
3393 _fi__(_COFF__||_BOUT__)
3395 _if__(_COFF__||_BOUT__)
3396 @node Word, Deprecated, Val, Pseudo Ops
3397 _fi__(_COFF__||_BOUT__)
3398 _if__(!(_COFF__||_BOUT__))
3399 @node Word, Deprecated, Text, Pseudo Ops
3400 _fi__(!(_COFF__||_BOUT__))
3401 @section @code{.word @var{expressions}}
3403 @cindex @code{word} directive
3404 This directive expects zero or more @var{expressions}, of any section,
3405 separated by commas.
3406 _if__((!_GENERIC__) && _W32__)
3407 For each expression, @code{_AS__} emits a 32-bit number.
3408 _fi__((!_GENERIC__) && _W32__)
3409 _if__((!_GENERIC__) && _W16__)
3410 For each expression, @code{_AS__} emits a 16-bit number.
3411 _fi__((!_GENERIC__) && _W16__)
3414 The size of the number emitted, and its byte order,
3415 depends on what kind of computer will run the program.
3418 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3419 @c happen---32-bit addressability, period; no long/short jumps.
3420 _if__(_GENERIC__ || _DIFFTABKLUG__)
3421 @cindex difference tables altered
3422 @cindex altered difference tables
3424 @emph{Warning: Special Treatment to support Compilers}
3428 Machines with a 32-bit address space, but that do less than 32-bit
3429 addressing, require the following special treatment. If the machine of
3430 interest to you does 32-bit addressing (or doesn't require it;
3431 @pxref{_MACH_DEP__}), you can ignore this issue.
3434 In order to assemble compiler output into something that will work,
3435 @code{_AS__} will occasionlly do strange things to @samp{.word} directives.
3436 Directives of the form @samp{.word sym1-sym2} are often emitted by
3437 compilers as part of jump tables. Therefore, when @code{_AS__} assembles a
3438 directive of the form @samp{.word sym1-sym2}, and the difference between
3439 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will
3440 create a @dfn{secondary jump table}, immediately before the next label.
3441 This secondary jump table will be preceded by a short-jump to the
3442 first byte after the secondary table. This short-jump prevents the flow
3443 of control from accidentally falling into the new table. Inside the
3444 table will be a long-jump to @code{sym2}. The original @samp{.word}
3445 will contain @code{sym1} minus the address of the long-jump to
3448 If there were several occurrences of @samp{.word sym1-sym2} before the
3449 secondary jump table, all of them will be adjusted. If there was a
3450 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3451 long-jump to @code{sym4} will be included in the secondary jump table,
3452 and the @code{.word} directives will be adjusted to contain @code{sym3}
3453 minus the address of the long-jump to @code{sym4}; and so on, for as many
3454 entries in the original jump table as necessary.
3457 @emph{This feature may be disabled by compiling @code{_AS__} with the
3458 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3459 assembly language programmers.
3461 _fi__(_GENERIC__ || _DIFFTABKLUG__)
3463 @node Deprecated, , Word, Pseudo Ops
3464 @section Deprecated Directives
3466 @cindex deprecated directives
3467 @cindex obsolescent directives
3468 One day these directives won't work.
3469 They are included for compatibility with older assemblers.
3476 @node _MACH_DEP__, Copying, Pseudo Ops, Top
3478 @chapter Machine Dependent Features
3480 @cindex machine dependencies
3481 The machine instruction sets are (almost by definition) different on
3482 each machine where @code{_AS__} runs. Floating point representations
3483 vary as well, and @code{_AS__} often supports a few additional
3484 directives or command-line options for compatibility with other
3485 assemblers on a particular platform. Finally, some versions of
3486 @code{_AS__} support special pseudo-instructions for branch
3489 This chapter discusses most of these differences, though it does not
3490 include details on any machine's instruction set. For details on that
3491 subject, see the hardware manufacturer's manual.
3495 * Vax-Dependent:: VAX Dependent Features
3498 * AMD29K-Dependent:: AMD 29K Dependent Features
3501 * H8/300-Dependent:: AMD 29K Dependent Features
3504 * i960-Dependent:: Intel 80960 Dependent Features
3507 * M68K-Dependent:: M680x0 Dependent Features
3510 * Sparc-Dependent:: SPARC Dependent Features
3513 * i386-Dependent:: 80386 Dependent Features
3520 @node Vax-Dependent, AMD29K-Dependent, Machine Dependent, Machine Dependent
3522 _CHAPSEC__(0+_GENERIC__) VAX Dependent Features
3526 * Vax-Opts:: VAX Command-Line Options
3527 * VAX-float:: VAX Floating Point
3528 * VAX-directives:: Vax Machine Directives
3529 * VAX-opcodes:: VAX Opcodes
3530 * VAX-branch:: VAX Branch Improvement
3531 * VAX-operands:: VAX Operands
3532 * VAX-no:: Not Supported on VAX
3535 @node Vax-Opts, VAX-float, Vax-Dependent, Vax-Dependent
3536 _CHAPSEC__(1+_GENERIC__) VAX Command-Line Options
3538 @cindex command-line options ignored, VAX
3539 @cindex VAX command-line options ignored
3540 The Vax version of @code{_AS__} accepts any of the following options,
3541 gives a warning message that the option was ignored and proceeds.
3542 These options are for compatibility with scripts designed for other
3543 people's assemblers.
3546 @item @kbd{-D} (Debug)
3547 @itemx @kbd{-S} (Symbol Table)
3548 @itemx @kbd{-T} (Token Trace)
3549 @cindex @code{-D}, ignored on VAX
3550 @cindex @code{-S}, ignored on VAX
3551 @cindex @code{-T}, ignored on VAX
3552 These are obsolete options used to debug old assemblers.
3554 @item @kbd{-d} (Displacement size for JUMPs)
3555 @cindex @code{-d}, VAX option
3556 This option expects a number following the @kbd{-d}. Like options
3557 that expect filenames, the number may immediately follow the
3558 @kbd{-d} (old standard) or constitute the whole of the command line
3559 argument that follows @kbd{-d} (GNU standard).
3561 @item @kbd{-V} (Virtualize Interpass Temporary File)
3562 @cindex @code{-V}, redundant on VAX
3563 Some other assemblers use a temporary file. This option
3564 commanded them to keep the information in active memory rather
3565 than in a disk file. @code{_AS__} always does this, so this
3566 option is redundant.
3568 @item @kbd{-J} (JUMPify Longer Branches)
3569 @cindex @code{-J}, ignored on VAX
3570 Many 32-bit computers permit a variety of branch instructions
3571 to do the same job. Some of these instructions are short (and
3572 fast) but have a limited range; others are long (and slow) but
3573 can branch anywhere in virtual memory. Often there are 3
3574 flavors of branch: short, medium and long. Some other
3575 assemblers would emit short and medium branches, unless told by
3576 this option to emit short and long branches.
3578 @item @kbd{-t} (Temporary File Directory)
3579 @cindex @code{-t}, ignored on VAX
3580 Some other assemblers may use a temporary file, and this option
3581 takes a filename being the directory to site the temporary
3582 file. @code{_AS__} does not use a temporary disk file, so this
3583 option makes no difference. @kbd{-t} needs exactly one
3587 @cindex VMS (VAX) options
3588 @cindex options for VAX/VMS
3589 @cindex VAX/VMS options
3590 @cindex @code{-h} option, VAX/VMS
3591 @cindex @code{-+} option, VAX/VMS
3592 @cindex Vax-11 C compatibility
3593 @cindex symbols with lowercase, VAX/VMS
3594 @c FIXME! look into "I think" below, correct if needed, delete.
3595 The Vax version of the assembler accepts two options when
3596 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
3597 @kbd{-h} option prevents @code{_AS__} from modifying the
3598 symbol-table entries for symbols that contain lowercase
3599 characters (I think). The @kbd{-+} option causes @code{_AS__} to
3600 print warning messages if the FILENAME part of the object file,
3601 or any symbol name is larger than 31 characters. The @kbd{-+}
3602 option also insertes some code following the @samp{_main}
3603 symbol so that the object file will be compatible with Vax-11
3606 @node VAX-float, VAX-directives, Vax-Opts, Vax-Dependent
3607 _CHAPSEC__(1+_GENERIC__) VAX Floating Point
3609 @cindex VAX floating point
3610 @cindex floating point, VAX
3611 Conversion of flonums to floating point is correct, and
3612 compatible with previous assemblers. Rounding is
3613 towards zero if the remainder is exactly half the least significant bit.
3615 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3618 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3619 are rendered correctly. Again, rounding is towards zero in the
3622 @cindex @code{float} directive, VAX
3623 @cindex @code{double} directive, VAX
3624 The @code{.float} directive produces @code{f} format numbers.
3625 The @code{.double} directive produces @code{d} format numbers.
3627 @node VAX-directives, VAX-opcodes, VAX-float, Vax-Dependent
3628 _CHAPSEC__(1+_GENERIC__) Vax Machine Directives
3630 @cindex machine directives, VAX
3631 @cindex VAX machine directives
3632 The Vax version of the assembler supports four directives for
3633 generating Vax floating point constants. They are described in the
3636 @cindex wide floating point directives, VAX
3639 @cindex @code{dfloat} directive, VAX
3640 This expects zero or more flonums, separated by commas, and
3641 assembles Vax @code{d} format 64-bit floating point constants.
3644 @cindex @code{ffloat} directive, VAX
3645 This expects zero or more flonums, separated by commas, and
3646 assembles Vax @code{f} format 32-bit floating point constants.
3649 @cindex @code{gfloat} directive, VAX
3650 This expects zero or more flonums, separated by commas, and
3651 assembles Vax @code{g} format 64-bit floating point constants.
3654 @cindex @code{hfloat} directive, VAX
3655 This expects zero or more flonums, separated by commas, and
3656 assembles Vax @code{h} format 128-bit floating point constants.
3660 @node VAX-opcodes, VAX-branch, VAX-directives, Vax-Dependent
3661 _CHAPSEC__(1+_GENERIC__) VAX Opcodes
3663 @cindex VAX opcode mnemonics
3664 @cindex opcode mnemonics, VAX
3665 @cindex mnemonics for opcodes, VAX
3666 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3667 instructions have exactly 3 operands. The dispatch table that
3668 follows the @code{case@dots{}} instruction should be made with
3669 @code{.word} statements. This is compatible with all unix
3670 assemblers we know of.
3672 @node VAX-branch, VAX-operands, VAX-opcodes, Vax-Dependent
3673 _CHAPSEC__(1+_GENERIC__) VAX Branch Improvement
3675 @cindex VAX branch improvement
3676 @cindex branch improvement, VAX
3677 @cindex pseudo-ops for branch, VAX
3678 Certain pseudo opcodes are permitted. They are for branch
3679 instructions. They expand to the shortest branch instruction that
3680 will reach the target. Generally these mnemonics are made by
3681 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3682 This feature is included both for compatibility and to help
3683 compilers. If you don't need this feature, don't use these
3684 opcodes. Here are the mnemonics, and the code they can expand into.
3688 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3690 @item (byte displacement)
3692 @item (word displacement)
3694 @item (long displacement)
3699 Unconditional branch.
3701 @item (byte displacement)
3703 @item (word displacement)
3705 @item (long displacement)
3709 @var{COND} may be any one of the conditional branches
3710 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
3711 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
3712 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
3713 @var{COND} may also be one of the bit tests
3714 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
3715 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
3716 @var{NOTCOND} is the opposite condition to @var{COND}.
3718 @item (byte displacement)
3719 @kbd{b@var{COND} @dots{}}
3720 @item (word displacement)
3721 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
3722 @item (long displacement)
3723 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
3726 @var{X} may be one of @code{b d f g h l w}.
3728 @item (word displacement)
3729 @kbd{@var{OPCODE} @dots{}}
3730 @item (long displacement)
3732 @var{OPCODE} @dots{}, foo ;
3739 @var{YYY} may be one of @code{lss leq}.
3741 @var{ZZZ} may be one of @code{geq gtr}.
3743 @item (byte displacement)
3744 @kbd{@var{OPCODE} @dots{}}
3745 @item (word displacement)
3747 @var{OPCODE} @dots{}, foo ;
3749 foo: brw @var{destination} ;
3752 @item (long displacement)
3754 @var{OPCODE} @dots{}, foo ;
3756 foo: jmp @var{destination} ;
3765 @item (byte displacement)
3766 @kbd{@var{OPCODE} @dots{}}
3767 @item (word displacement)
3769 @var{OPCODE} @dots{}, foo ;
3771 foo: brw @var{destination} ;
3774 @item (long displacement)
3776 @var{OPCODE} @dots{}, foo ;
3778 foo: jmp @var{destination} ;
3784 @node VAX-operands, VAX-no, VAX-branch, Vax-Dependent
3785 _CHAPSEC__(1+_GENERIC__) VAX Operands
3787 @cindex VAX operand notation
3788 @cindex operand notation, VAX
3789 @cindex immediate character, VAX
3790 @cindex VAX immediate character
3791 The immediate character is @samp{$} for Unix compatibility, not
3792 @samp{#} as DEC writes it.
3794 @cindex indirect character, VAX
3795 @cindex VAX indirect character
3796 The indirect character is @samp{*} for Unix compatibility, not
3797 @samp{@@} as DEC writes it.
3799 @cindex displacement sizing character, VAX
3800 @cindex VAX displacement sizing character
3801 The displacement sizing character is @samp{`} (an accent grave) for
3802 Unix compatibility, not @samp{^} as DEC writes it. The letter
3803 preceding @samp{`} may have either case. @samp{G} is not
3804 understood, but all other letters (@code{b i l s w}) are understood.
3806 @cindex register names, VAX
3807 @cindex VAX register names
3808 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
3809 pc}. Any case of letters will do.
3816 Any expression is permitted in an operand. Operands are comma
3819 @c There is some bug to do with recognizing expressions
3820 @c in operands, but I forget what it is. It is
3821 @c a syntax clash because () is used as an address mode
3822 @c and to encapsulate sub-expressions.
3824 @node VAX-no, , VAX-operands, Vax-Dependent
3825 _CHAPSEC__(1+_GENERIC__) Not Supported on VAX
3827 @cindex VAX bitfields not supported
3828 @cindex bitfields, not supported on VAX
3829 Vax bit fields can not be assembled with @code{_AS__}. Someone
3830 can add the required code if they really need it.
3835 @node AMD29K-Dependent, H8/300-Dependent, Vax-Dependent, Machine Dependent
3837 _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features
3839 @cindex AMD 29K support
3842 * AMD29K Options:: Options
3843 * AMD29K Syntax:: Syntax
3844 * AMD29K Floating Point:: Floating Point
3845 * AMD29K Directives:: AMD 29K Machine Directives
3846 * AMD29K Opcodes:: Opcodes
3849 @node AMD29K Options, AMD29K Syntax, AMD29K-Dependent, AMD29K-Dependent
3850 _CHAPSEC__(1+_GENERIC__) Options
3851 @cindex AMD 29K options (none)
3852 @cindex options for AMD29K (none)
3853 @code{_AS__} has no additional command-line options for the AMD
3856 @node AMD29K Syntax, AMD29K Floating Point, AMD29K Options, AMD29K-Dependent
3857 _CHAPSEC__(1+_GENERIC__) Syntax
3859 * AMD29K-Chars:: Special Characters
3860 * AMD29K-Regs:: Register Names
3863 @node AMD29K-Chars, AMD29K-Regs, AMD29K Syntax, AMD29K Syntax
3864 _CHAPSEC__(2+_GENERIC__) Special Characters
3866 @cindex line comment character, AMD 29K
3867 @cindex AMD 29K line comment character
3868 @samp{;} is the line comment character.
3870 @cindex line separator, AMD 29K
3871 @cindex AMD 29K line separator
3872 @cindex statement separator, AMD 29K
3873 @cindex AMD 29K statement separator
3874 @samp{@@} can be used instead of a newline to separate statements.
3876 @cindex identifiers, AMD 29K
3877 @cindex AMD 29K identifiers
3878 The character @samp{?} is permitted in identifiers (but may not begin
3881 @node AMD29K-Regs, , AMD29K-Chars, AMD29K Syntax
3882 _CHAPSEC__(2+_GENERIC__) Register Names
3884 @cindex AMD 29K register names
3885 @cindex register names, AMD 29K
3886 General-purpose registers are represented by predefined symbols of the
3887 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
3888 (for local registers), where @var{nnn} represents a number between
3889 @code{0} and @code{127}, written with no leading zeros. The leading
3890 letters may be in either upper or lower case; for example, @samp{gr13}
3891 and @samp{LR7} are both valid register names.
3893 You may also refer to general-purpose registers by specifying the
3894 register number as the result of an expression (prefixed with @samp{%%}
3895 to flag the expression as a register number):
3900 ---where @var{expression} must be an absolute expression evaluating to a
3901 number between @code{0} and @code{255}. The range [0, 127] refers to
3902 global registers, and the range [128, 255] to local registers.
3904 @cindex special purpose registers, AMD 29K
3905 @cindex AMD 29K special purpose registers
3906 @cindex protected registers, AMD 29K
3907 @cindex AMD 29K protected registers
3908 In addition, @code{_AS__} understands the following protected
3909 special-purpose register names for the AMD 29K family:
3919 These unprotected special-purpose register names are also recognized:
3927 @node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, AMD29K-Dependent
3928 _CHAPSEC__(1+_GENERIC__) Floating Point
3930 @cindex floating point, AMD 29K (@sc{ieee})
3931 @cindex AMD 29K floating point (@sc{ieee})
3932 The AMD 29K family uses @sc{ieee} floating-point numbers.
3934 @node AMD29K Directives, AMD29K Opcodes, AMD29K Floating Point, AMD29K-Dependent
3935 _CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives
3937 @cindex machine directives, AMD 29K
3938 @cindex AMD 29K machine directives
3940 @item .block @var{size} , @var{fill}
3941 @cindex @code{block} directive, AMD 29K
3942 This directive emits @var{size} bytes, each of value @var{fill}. Both
3943 @var{size} and @var{fill} are absolute expressions. If the comma
3944 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3946 In other versions of the GNU assembler, this directive is called
3952 @cindex @code{cputype} directive, AMD 29K
3953 This directive is ignored; it is accepted for compatibility with other
3957 @cindex @code{file} directive, AMD 29K
3958 This directive is ignored; it is accepted for compatibility with other
3962 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
3963 used for the directive called @code{.app-file} in the AMD 29K support.
3967 @cindex @code{line} directive, AMD 29K
3968 This directive is ignored; it is accepted for compatibility with other
3971 @item .reg @var{symbol}, @var{expression}
3972 @cindex @code{reg} directive, AMD 29K
3973 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
3976 @cindex @code{sect} directive, AMD 29K
3977 This directive is ignored; it is accepted for compatibility with other
3980 @item .use @var{section name}
3981 @cindex @code{use} directive, AMD 29K
3982 Establishes the section and subsection for the following code;
3983 @var{section name} may be one of @code{.text}, @code{.data},
3984 @code{.data1}, or @code{.lit}. With one of the first three @var{section
3985 name} options, @samp{.use} is equivalent to the machine directive
3986 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
3990 @node AMD29K Opcodes, , AMD29K Directives, AMD29K-Dependent
3991 _CHAPSEC__(1+_GENERIC__) Opcodes
3993 @cindex AMD 29K opcodes
3994 @cindex opcodes for AMD 29K
3995 @code{_AS__} implements all the standard AMD 29K opcodes. No
3996 additional pseudo-instructions are needed on this family.
3998 For information on the 29K machine instruction set, see @cite{Am29000
3999 User's Manual}, Advanced Micro Devices, Inc.
4004 @node H8/300-Dependent, i960-Dependent, AMD29K-Dependent, Machine Dependent
4006 _CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features
4008 @cindex H8/300 support
4010 * H8/300 Options:: Options
4011 * H8/300 Syntax:: Syntax
4012 * H8/300 Floating Point:: Floating Point
4013 * H8/300 Directives:: H8/300 Machine Directives
4014 * H8/300 Opcodes:: Opcodes
4017 @node H8/300 Options, H8/300 Syntax, H8/300-Dependent, H8/300-Dependent
4018 _CHAPSEC__(1+_GENERIC__) Options
4020 @cindex H8/300 options (none)
4021 @cindex options, H8/300 (none)
4022 @code{_AS__} has no additional command-line options for the Hitachi
4025 @node H8/300 Syntax, H8/300 Floating Point, H8/300 Options, H8/300-Dependent
4026 _CHAPSEC__(1+_GENERIC__) Syntax
4028 * H8/300-Chars:: Special Characters
4029 * H8/300-Regs:: Register Names
4030 * H8/300-Addressing:: Addressing Modes
4033 @node H8/300-Chars, H8/300-Regs, H8/300 Syntax, H8/300 Syntax
4034 _CHAPSEC__(2+_GENERIC__) Special Characters
4036 @cindex line comment character, H8/300
4037 @cindex H8/300 line comment character
4038 @samp{;} is the line comment character.
4040 @cindex line separator, H8/300
4041 @cindex statement separator, H8/300
4042 @cindex H8/300 line separator
4043 @samp{$} can be used instead of a newline to separate statements.
4044 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4046 @node H8/300-Regs, H8/300-Addressing, H8/300-Chars, H8/300 Syntax
4047 _CHAPSEC__(2+_GENERIC__) Register Names
4049 @cindex H8/300 registers
4050 @cindex registers, H8/300
4051 You can use predefined symbols of the form @samp{r@var{n}h} and
4052 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4053 general-purpose registers. @var{n} is a digit from @samp{0} to
4054 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4057 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4058 to the H8/300 registers as 16-bit registers (you must use this form for
4061 The two control registers are called @code{pc} (program counter; a
4062 16-bit register) and @code{ccr} (condition code register; an 8-bit
4063 register). @code{r7} is used as the stack pointer, and can also be
4066 @node H8/300-Addressing, , H8/300-Regs, H8/300 Syntax
4067 _CHAPSEC__(2+_GENERIC__) Addressing Modes
4069 @cindex addressing modes, H8/300
4070 @cindex H8/300 addressing modes
4071 _AS__ understands the following addressing modes for the H8/300:
4079 @item @@(@var{d}, r@var{n})
4080 @itemx @@(@var{d}:16, r@var{n})
4081 Register indirect: 16-bit displacement @var{d} from register @var{n}.
4082 (You may specify the @samp{:16} for clarity if you wish, but it is not
4083 required and has no effect.)
4086 Register indirect with post-increment
4089 Register indirect with pre-decrement
4091 @item @code{@@}@var{aa}
4092 @itemx @code{@@}@var{aa}:8
4093 @itemx @code{@@}@var{aa}:16
4094 Absolute address @code{aa}. You may specify the @samp{:8} or @samp{:16}
4095 for clarity, if you wish; but @code{_AS__} neither requires this nor
4096 uses it---the address size required is taken from context.
4101 Immediate data @var{xx}. You may specify the @samp{:8} or @samp{:16}
4102 for clarity, if you wish; but @code{_AS__} neither requires this nor
4103 uses it---the data size required is taken from context.
4105 @item @code{@@}@code{@@}@var{aa}
4106 @itemx @code{@@}@code{@@}@var{aa}:8
4107 Memory indirect. You may specify the @samp{:8} for clarity, if you
4108 wish; but @code{_AS__} neither requires this nor uses it.
4111 @node H8/300 Floating Point, H8/300 Directives, H8/300 Syntax, H8/300-Dependent
4112 _CHAPSEC__(1+_GENERIC__) Floating Point
4114 @cindex floating point, H8/300 (@sc{ieee})
4115 @cindex H8/300 floating point (@sc{ieee})
4116 The H8/300 family uses @sc{ieee} floating-point numbers.
4118 @node H8/300 Directives, H8/300 Opcodes, H8/300 Floating Point, H8/300-Dependent
4119 _CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives
4121 @cindex H8/300 machine directives (none)
4122 @cindex machine directives, H8/300 (none)
4123 @cindex @code{word} directive, H8/300
4124 @cindex @code{int} directive, H8/300
4125 @code{_AS__} has no machine-dependent directives for the H8/300.
4126 However, on this platform the @samp{.int} and @samp{.word} directives
4127 generate 16-bit numbers.
4129 @node H8/300 Opcodes, , H8/300 Directives, H8/300-Dependent
4130 _CHAPSEC__(1+_GENERIC__) Opcodes
4132 @cindex H8/300 opcode summary
4133 @cindex opcode summary, H8/300
4134 @cindex mnemonics, H8/300
4135 @cindex instruction summary, H8/300
4136 For detailed information on the H8/300 machine instruction set, see
4137 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025).
4139 @code{_AS__} implements all the standard H8/300 opcodes. No additional
4140 pseudo-instructions are needed on this family.
4142 The following table summarizes the opcodes and their arguments:
4143 @c kluge due to lack of group outside example
4147 Rs @r{source register}
4148 Rd @r{destination register}
4149 imm @r{immediate data}
4150 x:3 @r{a bit (as a number between 0 and 7)}
4151 d:8 @r{eight bit displacement from @code{pc}}
4152 d:16 @r{sixteen bit displacement from @code{Rs}}
4154 add.b Rs,Rd biand #x:3,Rd
4155 add.b #imm:8,Rd biand #x:3,@@Rd
4156 add.w Rs,Rd biand #x:3,@@aa:8
4157 adds #1,Rd bild #x:3,Rd
4158 adds #2,Rd bild #x:3,@@Rd
4159 addx #imm:8,Rd bild #x:3,@@aa:8
4160 addx Rs,Rd bior #x:3,Rd
4161 and #imm:8,Rd bior #x:3,@@Rd
4162 and Rs,Rd bior #x:3,@@aa:8
4163 andc #imm:8,ccr bist #x:3,Rd
4164 band #x:3,Rd bist #x:3,@@Rd
4165 band #x:3,@@Rd bist #x:3,@@aa:8
4166 bra d:8 bixor #x:3,Rd
4167 bt d:8 bixor #x:3,@@Rd
4168 brn d:8 bixor #x:3,@@aa:8
4170 bhi d:8 bld #x:3,@@Rd
4171 bls d:8 bld #x:3,@@aa:8
4172 bcc d:8 bnot #x:3,Rd
4173 bhs d:8 bnot #x:3,@@Rd
4174 bcs d:8 bnot #x:3,@@aa:8
4176 bne d:8 bnot Rs,@@Rd
4177 beq d:8 bnot Rs,@@aa:8
4179 bvs d:8 bor #x:3,@@Rd
4180 bpl d:8 bor #x:3,@@aa:8
4181 bmi d:8 bset #x:3,@@Rd
4182 bge d:8 bset #x:3,@@aa:8
4184 bgt d:8 bset Rs,@@Rd
4185 ble d:8 bset Rs,@@aa:8
4186 bclr #x:3,Rd bsr d:8
4187 bclr #x:3,@@Rd bst #x:3,Rd
4188 bclr #x:3,@@aa:8 bst #x:3,@@Rd
4189 bclr Rs,Rd bst #x:3,@@aa:8
4190 bclr Rs,@@Rd btst #x:3,Rd
4193 btst #x:3,@@Rd mov.w @@(d:16, Rs),Rd
4194 btst #x:3,@@aa:8 mov.w @@Rs+,Rd
4195 btst Rs,Rd mov.w @@aa:16,Rd
4196 btst Rs,@@Rd mov.w Rs,@@Rd
4197 btst Rs,@@aa:8 mov.w Rs,@@(d:16, Rd)
4198 bxor #x:3,Rd mov.w Rs,@@-Rd
4199 bxor #x:3,@@Rd mov.w Rs,@@aa:16
4200 bxor #x:3,@@aa:8 movfpe @@aa:16,Rd
4201 cmp.b #imm:8,Rd movtpe Rs,@@aa:16
4202 cmp.b Rs,Rd mulxu Rs,Rd
4207 divxu Rs,Rd or Rs,Rd
4208 eepmov orc #imm:8,ccr
4214 jsr @@aa:16 rotxr Rs
4219 mov.b #imm:8,Rd shll Rs
4220 mov.b @@Rs,Rd shlr Rs
4221 mov.b @@(d:16, Rs),Rd sleep
4222 mov.b @@Rs+,Rd stc ccr,Rd
4223 mov.b @@aa:16,Rd sub.b Rs,Rd
4224 mov.b @@aa:8,Rd sub.w Rs,Rd
4225 mov.b Rs,@@Rd subs #1,Rd
4226 mov.b Rs,@@(d:16, Rd) subs #2,Rd
4227 mov.b Rs,@@-Rd subx #imm:8,Rd
4228 mov.b Rs,@@aa:16 subx Rs,Rd
4229 mov.b Rs,@@aa:8 xor #imm:8,Rd
4230 mov.w Rs,Rd xor Rs,Rd
4231 mov.w #imm:16,Rd xorc #imm:8,ccr
4236 @cindex size suffixes, H8/300
4237 @cindex H8/300 size suffixes
4238 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4239 @code{sub}) are defined with variants using the suffixes @samp{.b} and
4240 @samp{.w} to specify the size of a memory operand. @code{_AS__}
4241 supports these suffixes, but does not require them; since one of the
4242 operands is always a register, @code{_AS__} can deduce the correct size.
4244 For example, since @code{r0} refers to a 16-bit register,
4247 @exdent is equivalent to
4251 If you use the size suffixes, @code{_AS__} will issue a warning if
4252 there's a mismatch between the suffix and the register size.
4257 @node i960-Dependent, M68K-Dependent, H8/300-Dependent, Machine Dependent
4259 _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features
4261 @cindex i960 support
4263 * Options-i960:: i960 Command-line Options
4264 * Floating Point-i960:: Floating Point
4265 * Directives-i960:: i960 Machine Directives
4266 * Opcodes for i960:: i960 Opcodes
4269 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
4270 @c long as they're not turned on for other machines than 960.
4271 @node Options-i960, Floating Point-i960, i960-Dependent, i960-Dependent
4273 _CHAPSEC__(1+_GENERIC__) i960 Command-line Options
4275 @cindex i960 options
4276 @cindex options, i960
4279 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
4280 @cindex i960 architecture options
4281 @cindex architecture options, i960
4282 @cindex @code{-A} options, i960
4283 Select the 80960 architecture. Instructions or features not supported
4284 by the selected architecture cause fatal errors.
4286 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
4287 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
4289 If none of these options is specified, @code{_AS__} will generate code for any
4290 instruction or feature that is supported by @emph{some} version of the
4291 960 (even if this means mixing architectures!). In principle,
4292 @code{_AS__} will attempt to deduce the minimal sufficient processor
4293 type if none is specified; depending on the object code format, the
4294 processor type may be recorded in the object file. If it is critical
4295 that the @code{_AS__} output match a specific architecture, specify that
4296 architecture explicitly.
4299 @cindex @code{-b} option, i960
4300 @cindex branch recording, i960
4301 @cindex i960 branch recording
4302 Add code to collect information about conditional branches taken, for
4303 later optimization using branch prediction bits. (The conditional branch
4304 instructions have branch prediction bits in the CA, CB, and CC
4305 architectures.) If @var{BR} represents a conditional branch instruction,
4306 the following represents the code generated by the assembler when
4307 @samp{-b} is specified:
4310 call @var{increment routine}
4311 .word 0 # pre-counter
4313 call @var{increment routine}
4314 .word 0 # post-counter
4317 The counter following a branch records the number of times that branch
4318 was @emph{not} taken; the differenc between the two counters is the
4319 number of times the branch @emph{was} taken.
4321 @cindex @code{gbr960}, i960 postprocessor
4322 @cindex branch statistics table, i960
4323 A table of every such @code{Label} is also generated, so that the
4324 external postprocessor @code{gbr960} (supplied by Intel) can locate all
4325 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
4326 this is a local symbol to permit collecting statistics for many separate
4327 object files. The table is word aligned, and begins with a two-word
4328 header. The first word, initialized to 0, is used in maintaining linked
4329 lists of branch tables. The second word is a count of the number of
4330 entries in the table, which follow immediately: each is a word, pointing
4331 to one of the labels illustrated above.
4335 @c END TEXI2ROFF-KILL
4337 +------------+------------+------------+ ... +------------+
4339 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
4341 +------------+------------+------------+ ... +------------+
4343 __BRANCH_TABLE__ layout
4349 \line{\leftskip=0pt\hskip\tableindent
4350 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
4351 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
4352 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
4354 @c END TEXI2ROFF-KILL
4356 The first word of the header is used to locate multiple branch tables,
4357 since each object file may contain one. Normally the links are
4358 maintained with a call to an initialization routine, placed at the
4359 beginning of each function in the file. The GNU C compiler will
4360 generate these calls automatically when you give it a @samp{-b} option.
4361 For further details, see the documentation of @samp{gbr960}.
4364 @cindex @code{-norelax} option, i960
4365 Normally, Compare-and-Branch instructions with targets that require
4366 displacements greater than 13 bits (or that have external targets) are
4367 replaced with the corresponding compare (or @samp{chkbit}) and branch
4368 instructions. You can use the @samp{-norelax} option to specify that
4369 @code{_AS__} should generate errors instead, if the target displacement
4370 is larger than 13 bits.
4372 This option does not affect the Compare-and-Jump instructions; the code
4373 emitted for them is @emph{always} adjusted when necessary (depending on
4374 displacement size), regardless of whether you use @samp{-norelax}.
4377 @node Floating Point-i960, Directives-i960, Options-i960, i960-Dependent
4378 _CHAPSEC__(1+_GENERIC__) Floating Point
4380 @cindex floating point, i960 (@sc{ieee})
4381 @cindex i960 floating point (@sc{ieee})
4382 @code{_AS__} generates @sc{ieee} floating-point numbers for the directives
4383 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
4385 @node Directives-i960, Opcodes for i960, Floating Point-i960, i960-Dependent
4386 _CHAPSEC__(1+_GENERIC__) i960 Machine Directives
4388 @cindex machine directives, i960
4389 @cindex i960 machine directives
4392 @cindex @code{bss} directive, i960
4393 @item .bss @var{symbol}, @var{length}, @var{align}
4394 Reserve @var{length} bytes in the bss section for a local @var{symbol},
4395 aligned to the power of two specified by @var{align}. @var{length} and
4396 @var{align} must be positive absolute expressions. This directive
4397 differs from @samp{.lcomm} only in that it permits you to specify
4398 an alignment. @xref{Lcomm,,@code{.lcomm}}.
4402 @item .extended @var{flonums}
4403 @cindex @code{extended} directive, i960
4404 @code{.extended} expects zero or more flonums, separated by commas; for
4405 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
4406 floating-point number.
4408 @item .leafproc @var{call-lab}, @var{bal-lab}
4409 @cindex @code{leafproc} directive, i960
4410 You can use the @samp{.leafproc} directive in conjunction with the
4411 optimized @code{callj} instruction to enable faster calls of leaf
4412 procedures. If a procedure is known to call no other procedures, you
4413 may define an entry point that skips procedure prolog code (and that does
4414 not depend on system-supplied saved context), and declare it as the
4415 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
4416 entry point that goes through the normal prolog, you can specify that
4417 entry point as @var{call-lab}.
4419 A @samp{.leafproc} declaration is meant for use in conjunction with the
4420 optimized call instruction @samp{callj}; the directive records the data
4421 needed later to choose between converting the @samp{callj} into a
4422 @code{bal} or a @code{call}.
4424 @var{call-lab} is optional; if only one argument is present, or if the
4425 two arguments are identical, the single argument is assumed to be the
4426 @code{bal} entry point.
4428 @item .sysproc @var{name}, @var{index}
4429 @cindex @code{sysproc} directive, i960
4430 The @samp{.sysproc} directive defines a name for a system procedure.
4431 After you define it using @samp{.sysproc}, you can use @var{name} to
4432 refer to the system procedure identified by @var{index} when calling
4433 procedures with the optimized call instruction @samp{callj}.
4435 Both arguments are required; @var{index} must be between 0 and 31
4439 @node Opcodes for i960, , Directives-i960, i960-Dependent
4440 _CHAPSEC__(1+_GENERIC__) i960 Opcodes
4442 @cindex opcodes, i960
4443 @cindex i960 opcodes
4444 All Intel 960 machine instructions are supported;
4445 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
4446 selecting the instruction subset for a particular 960
4447 architecture.@refill
4449 Some opcodes are processed beyond simply emitting a single corresponding
4450 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
4451 instructions with target displacements larger than 13 bits.
4454 * callj-i960:: @code{callj}
4455 * Compare-and-branch-i960:: Compare-and-Branch
4458 @node callj-i960, Compare-and-branch-i960, Opcodes for i960, Opcodes for i960
4459 _CHAPSEC__(2+_GENERIC__) @code{callj}
4461 @cindex @code{callj}, i960 pseudo-opcode
4462 @cindex i960 @code{callj} pseudo-opcode
4463 You can write @code{callj} to have the assembler or the linker determine
4464 the most appropriate form of subroutine call: @samp{call},
4465 @samp{bal}, or @samp{calls}. If the assembly source contains
4466 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
4467 defining the operand---then @code{_AS__} will translate the
4468 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
4469 for the linker to resolve.
4471 @node Compare-and-branch-i960, , callj-i960, Opcodes for i960
4472 _CHAPSEC__(2+_GENERIC__) Compare-and-Branch
4474 @cindex i960 compare/branch instructions
4475 @cindex compare/branch instructions, i960
4476 The 960 architectures provide combined Compare-and-Branch instructions
4477 that permit you to store the branch target in the lower 13 bits of the
4478 instruction word itself. However, if you specify a branch target far
4479 enough away that its address won't fit in 13 bits, the assembler can
4480 either issue an error, or convert your Compare-and-Branch instruction
4481 into separate instructions to do the compare and the branch.
4483 @cindex compare and jump expansions, i960
4484 @cindex i960 compare and jump expansions
4485 Whether @code{_AS__} gives an error or expands the instruction depends
4486 on two choices you can make: whether you use the @samp{-norelax} option,
4487 and whether you use a ``Compare and Branch'' instruction or a ``Compare
4488 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
4489 expanded if necessary; the ``Branch'' instructions are expanded when
4490 necessary @emph{unless} you specify @code{-norelax}---in which case
4491 @code{_AS__} gives an error instead.
4493 These are the Compare-and-Branch instructions, their ``Jump'' variants,
4494 and the instruction pairs they may expand into:
4498 @c END TEXI2ROFF-KILL
4501 Branch Jump Expanded to
4502 ------ ------ ------------
4505 cmpibe cmpije cmpi; be
4506 cmpibg cmpijg cmpi; bg
4507 cmpibge cmpijge cmpi; bge
4508 cmpibl cmpijl cmpi; bl
4509 cmpible cmpijle cmpi; ble
4510 cmpibno cmpijno cmpi; bno
4511 cmpibne cmpijne cmpi; bne
4512 cmpibo cmpijo cmpi; bo
4513 cmpobe cmpoje cmpo; be
4514 cmpobg cmpojg cmpo; bg
4515 cmpobge cmpojge cmpo; bge
4516 cmpobl cmpojl cmpo; bl
4517 cmpoble cmpojle cmpo; ble
4518 cmpobne cmpojne cmpo; bne
4524 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
4525 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
4526 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
4527 bbc& & chkbit; bno\cr
4528 bbs& & chkbit; bo\cr
4529 cmpibe& cmpije& cmpi; be\cr
4530 cmpibg& cmpijg& cmpi; bg\cr
4531 cmpibge& cmpijge& cmpi; bge\cr
4532 cmpibl& cmpijl& cmpi; bl\cr
4533 cmpible& cmpijle& cmpi; ble\cr
4534 cmpibno& cmpijno& cmpi; bno\cr
4535 cmpibne& cmpijne& cmpi; bne\cr
4536 cmpibo& cmpijo& cmpi; bo\cr
4537 cmpobe& cmpoje& cmpo; be\cr
4538 cmpobg& cmpojg& cmpo; bg\cr
4539 cmpobge& cmpojge& cmpo; bge\cr
4540 cmpobl& cmpojl& cmpo; bl\cr
4541 cmpoble& cmpojle& cmpo; ble\cr
4542 cmpobne& cmpojne& cmpo; bne\cr}
4544 @c END TEXI2ROFF-KILL
4549 @c FIXME! node conds are only sufficient for m68k alone, all, and vintage
4551 @node M68K-Dependent, Sparc-Dependent, i960-Dependent, Machine Dependent
4554 @node M68K-Dependent, Sparc-Dependent, Machine Dependent, Machine Dependent
4557 _CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features
4559 @cindex M680x0 support
4561 * M68K-Opts:: M680x0 Options
4562 * M68K-Syntax:: Syntax
4563 * M68K-Float:: Floating Point
4564 * M68K-Directives:: 680x0 Machine Directives
4565 * M68K-opcodes:: Opcodes
4568 @node M68K-Opts, M68K-Syntax, M68K-Dependent, M68K-Dependent
4569 _CHAPSEC__(1+_GENERIC__) M680x0 Options
4571 @cindex options, M680x0
4572 @cindex M680x0 options
4573 The Motorola 680x0 version of @code{_AS__} has two machine dependent options.
4574 One shortens undefined references from 32 to 16 bits, while the
4575 other is used to tell @code{_AS__} what kind of machine it is
4578 @cindex @code{-l} option, M680x0
4579 You can use the @kbd{-l} option to shorten the size of references to
4580 undefined symbols. If the @kbd{-l} option is not given, references to
4581 undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__}
4582 cannot know where these symbols will end up, @code{_AS__} can only allocate
4583 space for the linker to fill in later. Since @code{_AS__} doesn't know how
4584 far away these symbols will be, it allocates as much space as it can.)
4585 If this option is given, the references will only be one word wide (16
4586 bits). This may be useful if you want the object file to be as small as
4587 possible, and you know that the relevant symbols will be less than 17
4590 @cindex @code{-m68000} and related options
4591 @cindex architecture options, M680x0
4592 @cindex M680x0 architecture options
4593 The 680x0 version of @code{_AS__} is most frequently used to assemble
4594 programs for the Motorola MC68020 microprocessor. Occasionally it is
4595 used to assemble programs for the mostly similar, but slightly different
4596 MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options
4597 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
4598 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
4601 @node M68K-Syntax, M68K-Float, M68K-Opts, M68K-Dependent
4602 _CHAPSEC__(1+_GENERIC__) Syntax
4604 @cindex M680x0 syntax
4605 @cindex syntax, M680x0
4606 @cindex M680x0 size modifiers
4607 @cindex size modifiers, M680x0
4608 The 680x0 version of @code{_AS__} uses syntax similar to the Sun assembler.
4609 Size modifiers are appended directly to the end of the opcode without an
4610 intervening period. For example, write @samp{movl} rather than
4614 If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow
4615 Sun-style local labels of the form @samp{1$} through @samp{$9}.
4618 In the following table @dfn{apc} stands for any of the address
4619 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
4620 Program Counter (@samp{pc}), or the zero-address relative to the
4621 program counter (@samp{zpc}).
4623 @cindex M680x0 addressing modes
4624 @cindex addressing modes, M680x0
4625 The following addressing modes are understood:
4628 @samp{#@var{digits}}
4631 @samp{d0} through @samp{d7}
4633 @item Address Register
4634 @samp{a0} through @samp{a7}
4636 @item Address Register Indirect
4637 @samp{a0@@} through @samp{a7@@}
4639 @item Address Register Postincrement
4640 @samp{a0@@+} through @samp{a7@@+}
4642 @item Address Register Predecrement
4643 @samp{a0@@-} through @samp{a7@@-}
4645 @item Indirect Plus Offset
4646 @samp{@var{apc}@@(@var{digits})}
4649 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4651 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
4654 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4656 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
4659 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4661 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4663 @item Memory Indirect
4664 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
4667 @samp{@var{symbol}}, or @samp{@var{digits}}
4669 @c pesch@cygnus.com: gnu, rich concur the following needs careful
4670 @c research before documenting.
4671 , or either of the above followed
4672 by @samp{:b}, @samp{:w}, or @samp{:l}.
4676 @node M68K-Float, M68K-Directives, M68K-Syntax, M68K-Dependent
4677 _CHAPSEC__(1+_GENERIC__) Floating Point
4679 @cindex floating point, M680x0
4680 @cindex M680x0 floating point
4681 @c FIXME is this "not too well tested" crud STILL true?
4682 The floating point code is not too well tested, and may have
4685 Packed decimal (P) format floating literals are not supported.
4686 Feel free to add the code!
4688 The floating point formats generated by directives are these.
4692 @cindex @code{float} directive, M680x0
4693 @code{Single} precision floating point constants.
4696 @cindex @code{double} directive, M680x0
4697 @code{Double} precision floating point constants.
4700 There is no directive to produce regions of memory holding
4701 extended precision numbers, however they can be used as
4702 immediate operands to floating-point instructions. Adding a
4703 directive to create extended precision numbers would not be
4704 hard, but it has not yet seemed necessary.
4706 @node M68K-Directives, M68K-opcodes, M68K-Float, M68K-Dependent
4707 _CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives
4709 @cindex M680x0 directives
4710 @cindex directives, M680x0
4711 In order to be compatible with the Sun assembler the 680x0 assembler
4712 understands the following directives.
4716 @cindex @code{data1} directive, M680x0
4717 This directive is identical to a @code{.data 1} directive.
4720 @cindex @code{data2} directive, M680x0
4721 This directive is identical to a @code{.data 2} directive.
4724 @cindex @code{even} directive, M680x0
4725 This directive is identical to a @code{.align 1} directive.
4726 @c Is this true? does it work???
4729 @cindex @code{skip} directive, M680x0
4730 This directive is identical to a @code{.space} directive.
4733 @node M68K-opcodes, , M68K-Directives, M68K-Dependent
4734 _CHAPSEC__(1+_GENERIC__) Opcodes
4736 @cindex M680x0 opcodes
4737 @cindex opcodes, M680x0
4738 @cindex instruction set, M680x0
4739 @c pesch@cygnus.com: I don't see any point in the following
4740 @c paragraph. Bugs are bugs; how does saying this
4743 Danger: Several bugs have been found in the opcode table (and
4744 fixed). More bugs may exist. Be careful when using obscure
4749 * M68K-Branch:: Branch Improvement
4750 * M68K-Chars:: Special Characters
4753 @node M68K-Branch, M68K-Chars, M68K-opcodes, M68K-opcodes
4754 _CHAPSEC__(2+_GENERIC__) Branch Improvement
4756 @cindex pseudo-opcodes, M680x0
4757 @cindex M680x0 pseudo-opcodes
4758 @cindex branch improvement, M680x0
4759 @cindex M680x0 branch improvement
4760 Certain pseudo opcodes are permitted for branch instructions.
4761 They expand to the shortest branch instruction that will reach the
4762 target. Generally these mnemonics are made by substituting @samp{j} for
4763 @samp{b} at the start of a Motorola mnemonic.
4765 The following table summarizes the pseudo-operations. A @code{*} flags
4766 cases that are more fully described after the table:
4770 +-------------------------------------------------
4772 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
4773 +-------------------------------------------------
4774 jbsr |bsrs bsr bsrl jsr jsr
4775 jra |bras bra bral jmp jmp
4776 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
4777 * dbXX |dbXX dbXX dbXX; bra; jmpl
4778 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
4781 NX: negative of condition XX
4784 @center @code{*}---see full description below
4789 These are the simplest jump pseudo-operations; they always map to one
4790 particular machine instruction, depending on the displacement to the
4794 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
4795 where @var{XX} is a conditional branch or condition-code test. The full
4796 list of pseudo-ops in this family is:
4798 jhi jls jcc jcs jne jeq jvc
4799 jvs jpl jmi jge jlt jgt jle
4802 For the cases of non-PC relative displacements and long displacements on
4803 the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of
4804 @var{NX}, the opposite condition to @var{XX}:
4816 The full family of pseudo-operations covered here is
4818 dbhi dbls dbcc dbcs dbne dbeq dbvc
4819 dbvs dbpl dbmi dbge dblt dbgt dble
4823 Other than for word and byte displacements, when the source reads
4824 @samp{db@var{XX} foo}, @code{_AS__} will emit
4833 This family includes
4835 fjne fjeq fjge fjlt fjgt fjle fjf
4836 fjt fjgl fjgle fjnge fjngl fjngle fjngt
4837 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
4838 fjor fjseq fjsf fjsne fjst fjueq fjuge
4839 fjugt fjule fjult fjun
4842 For branch targets that are not PC relative, @code{_AS__} emits
4848 when it encounters @samp{fj@var{XX} foo}.
4852 @node M68K-Chars, , M68K-Branch, M68K-opcodes
4853 _CHAPSEC__(2+_GENERIC__) Special Characters
4855 @cindex special characters, M680x0
4856 @cindex M680x0 immediate character
4857 @cindex immediate character, M680x0
4858 @cindex M680x0 line comment character
4859 @cindex line comment character, M680x0
4860 @cindex comments, M680x0
4861 The immediate character is @samp{#} for Sun compatibility. The
4862 line-comment character is @samp{|}. If a @samp{#} appears at the
4863 beginning of a line, it is treated as a comment unless it looks like
4864 @samp{# line file}, in which case it is treated normally.
4868 @c pesch@cygnus.com: conditionalize on something other than 0 when filled in.
4871 The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to
4872 specify thiat it is compiling for a 32032 processor, or a
4873 @kbd{-m32532} to specify that it is compiling for a 32532 option.
4874 The default (if neither is specified) is chosen when the assembler
4878 I don't know anything about the 32x32 syntax assembled by
4879 @code{_AS__}. Someone who undersands the processor (I've never seen
4880 one) and the possible syntaxes should write this section.
4882 @subsection Floating Point
4883 The 32x32 uses @sc{ieee} floating point numbers, but @code{_AS__} will only
4884 create single or double precision values. I don't know if the 32x32
4885 understands extended precision numbers.
4887 @subsection 32x32 Machine Directives
4888 The 32x32 has no machine dependent directives.
4893 _if__(_I80386__&&_M680X0__)
4894 @node Sparc-Dependent, i386-Dependent, M68K-Dependent, Machine Dependent
4895 _fi__(_I80386__&&_M680X0__)
4896 _if__(_I80386__&&_I960__&&!_M680X0__)
4897 @node Sparc-Dependent, i386-Dependent, i960-Dependent, Machine Dependent
4898 _fi__(_I80386__&&_I960__&&!_M680X0__)
4899 _if__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
4900 @node Sparc-Dependent, i386-Dependent, AMD29K-Dependent, Machine Dependent
4901 _fi__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
4902 _if__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4903 @node Sparc-Dependent, i386-Dependent, Vax-Dependent, Machine Dependent
4904 _fi__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4905 _if__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4906 @node Sparc-Dependent, i386-Dependent, Machine Dependent, Machine Dependent
4907 _fi__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4908 _if__((!_I80386__)&&_M680X0__)
4909 @node Sparc-Dependent, , M68K-Dependent, Machine Dependent
4910 _fi__((!_I80386__)&&_M680X0__)
4911 _if__((!_I80386__)&&_I960__&&!_M680X0__)
4912 @node Sparc-Dependent, , i960-Dependent, Machine Dependent
4913 _fi__((!_I80386__)&&_I960__&&!_M680X0__)
4914 _if__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
4915 @node Sparc-Dependent, , AMD29K-Dependent, Machine Dependent
4916 _fi__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
4917 _if__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4918 @node Sparc-Dependent, , Vax-Dependent, Machine Dependent
4919 _fi__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4920 _if__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4921 @node Sparc-Dependent, , Machine Dependent, Machine Dependent
4922 _fi__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4924 _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features
4926 @cindex SPARC support
4928 * Sparc-Opts:: Options
4929 * Sparc-Float:: Floating Point
4930 * Sparc-Directives:: Sparc Machine Directives
4933 @node Sparc-Opts, Sparc-Float, Sparc-Dependent, Sparc-Dependent
4934 _CHAPSEC__(1+_GENERIC__) Options
4936 @cindex options for SPARC (none)
4937 @cindex SPARC options (none)
4938 The Sparc has no machine dependent options.
4941 @c FIXME: (sparc) Fill in "syntax" section!
4942 @c subsection syntax
4943 I don't know anything about Sparc syntax. Someone who does
4944 will have to write this section.
4947 @node Sparc-Float, Sparc-Directives, Sparc-Opts, Sparc-Dependent
4948 _CHAPSEC__(1+_GENERIC__) Floating Point
4950 @cindex floating point, SPARC (@sc{ieee})
4951 @cindex SPARC floating point (@sc{ieee})
4952 The Sparc uses @sc{ieee} floating-point numbers.
4954 @node Sparc-Directives, , Sparc-Float, Sparc-Dependent
4955 _CHAPSEC__(1+_GENERIC__) Sparc Machine Directives
4957 @cindex SPARC machine directives
4958 @cindex machine directives, SPARC
4959 The Sparc version of @code{_AS__} supports the following additional
4964 @cindex @code{common} directive, SPARC
4965 This must be followed by a symbol name, a positive number, and
4966 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
4967 syntax is different.
4970 @cindex @code{half} directive, SPARC
4971 This is functionally identical to @code{.short}.
4974 @cindex @code{proc} directive, SPARC
4975 This directive is ignored. Any text following it on the same
4976 line is also ignored.
4979 @cindex @code{reserve} directive, SPARC
4980 This must be followed by a symbol name, a positive number, and
4981 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
4982 syntax is different.
4985 @cindex @code{seg} directive, SPARC
4986 This must be followed by @code{"text"}, @code{"data"}, or
4987 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
4991 @cindex @code{skip} directive, SPARC
4992 This is functionally identical to the @code{.space} directive.
4995 @cindex @code{word} directive, SPARC
4996 On the Sparc, the .word directive produces 32 bit values,
4997 instead of the 16 bit values it produces on many other machines.
5003 @c FIXME! Conditionalize for all combinations in this section
5004 @node i386-Dependent, , Sparc-Dependent, Machine Dependent
5006 _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features
5008 @cindex i386 support
5009 @cindex i80306 support
5011 * i386-Options:: Options
5012 * i386-Syntax:: AT&T Syntax versus Intel Syntax
5013 * i386-Opcodes:: Opcode Naming
5014 * i386-Regs:: Register Naming
5015 * i386-prefixes:: Opcode Prefixes
5016 * i386-Memory:: Memory References
5017 * i386-jumps:: Handling of Jump Instructions
5018 * i386-Float:: Floating Point
5019 * i386-Notes:: Notes
5022 @node i386-Options, i386-Syntax, i386-Dependent, i386-Dependent
5023 _CHAPSEC__(1+_GENERIC__) Options
5025 @cindex options for i386 (none)
5026 @cindex i386 options (none)
5027 The 80386 has no machine dependent options.
5029 @node i386-Syntax, i386-Opcodes, i386-Options, i386-Dependent
5030 _CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax
5032 @cindex i386 syntax compatibility
5033 @cindex syntax compatibility, i386
5034 In order to maintain compatibility with the output of @code{_GCC__},
5035 @code{_AS__} supports AT&T System V/386 assembler syntax. This is quite
5036 different from Intel syntax. We mention these differences because
5037 almost all 80386 documents used only Intel syntax. Notable differences
5038 between the two syntaxes are:
5042 @cindex immediate operands, i386
5043 @cindex i386 immediate operands
5044 @cindex register operands, i386
5045 @cindex i386 register operands
5046 @cindex jump/call operands, i386
5047 @cindex i386 jump/call operands
5048 @cindex operand delimiters, i386
5049 AT&T immediate operands are preceded by @samp{$}; Intel immediate
5050 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
5051 AT&T register operands are preceded by @samp{%}; Intel register operands
5052 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
5053 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
5056 @cindex i386 source, destination operands
5057 @cindex source, destination operands; i386
5058 AT&T and Intel syntax use the opposite order for source and destination
5059 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
5060 @samp{source, dest} convention is maintained for compatibility with
5061 previous Unix assemblers.
5064 @cindex opcode suffixes, i386
5065 @cindex sizes operands, i386
5066 @cindex i386 size suffixes
5067 In AT&T syntax the size of memory operands is determined from the last
5068 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
5069 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
5070 memory references. Intel syntax accomplishes this by prefixes memory
5071 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
5072 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
5073 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
5076 @cindex return instructions, i386
5077 @cindex i386 jump, call, return
5078 Immediate form long jumps and calls are
5079 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
5081 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
5083 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
5084 @samp{ret far @var{stack-adjust}}.
5087 @cindex sections, i386
5088 @cindex i386 sections
5089 The AT&T assembler does not provide support for multiple section
5090 programs. Unix style systems expect all programs to be single sections.
5093 @node i386-Opcodes, i386-Regs, i386-Syntax, i386-Dependent
5094 _CHAPSEC__(1+_GENERIC__) Opcode Naming
5096 @cindex i386 opcode naming
5097 @cindex opcode naming, i386
5098 Opcode names are suffixed with one character modifiers which specify the
5099 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
5100 byte, word, and long operands. If no suffix is specified by an
5101 instruction and it contains no memory operands then @code{_AS__} tries to
5102 fill in the missing suffix based on the destination register operand
5103 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
5104 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
5105 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
5106 assembler which assumes that a missing opcode suffix implies long
5107 operand size. (This incompatibility does not affect compiler output
5108 since compilers always explicitly specify the opcode suffix.)
5110 Almost all opcodes have the same names in AT&T and Intel format. There
5111 are a few exceptions. The sign extend and zero extend instructions need
5112 two sizes to specify them. They need a size to sign/zero extend
5113 @emph{from} and a size to zero extend @emph{to}. This is accomplished
5114 by using two opcode suffixes in AT&T syntax. Base names for sign extend
5115 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
5116 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
5117 suffixes are tacked on to this base name, the @emph{from} suffix before
5118 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
5119 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
5120 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
5121 and @samp{wl} (from word to long).
5123 @cindex conversion instructions, i386
5124 @cindex i386 conversion instructions
5125 The Intel-syntax conversion instructions
5129 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
5132 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
5135 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
5138 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
5142 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
5143 AT&T naming. @code{_AS__} accepts either naming for these instructions.
5145 @cindex jump instructions, i386
5146 @cindex call instructions, i386
5147 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
5148 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
5151 @node i386-Regs, i386-prefixes, i386-Opcodes, i386-Dependent
5152 _CHAPSEC__(1+_GENERIC__) Register Naming
5154 @cindex i386 registers
5155 @cindex registers, i386
5156 Register operands are always prefixes with @samp{%}. The 80386 registers
5161 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
5162 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
5163 frame pointer), and @samp{%esp} (the stack pointer).
5166 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
5167 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
5170 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
5171 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
5172 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
5173 @samp{%cx}, and @samp{%dx})
5176 the 6 section registers @samp{%cs} (code section), @samp{%ds}
5177 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
5181 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
5185 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
5186 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
5189 the 2 test registers @samp{%tr6} and @samp{%tr7}.
5192 the 8 floating point register stack @samp{%st} or equivalently
5193 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
5194 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
5197 @node i386-prefixes, i386-Memory, i386-Regs, i386-Dependent
5198 _CHAPSEC__(1+_GENERIC__) Opcode Prefixes
5200 @cindex i386 opcode prefixes
5201 @cindex opcode prefixes, i386
5202 @cindex prefixes, i386
5203 Opcode prefixes are used to modify the following opcode. They are used
5204 to repeat string instructions, to provide section overrides, to perform
5205 bus lock operations, and to give operand and address size (16-bit
5206 operands are specified in an instruction by prefixing what would
5207 normally be 32-bit operands with a ``operand size'' opcode prefix).
5208 Opcode prefixes are usually given as single-line instructions with no
5209 operands, and must directly precede the instruction they act upon. For
5210 example, the @samp{scas} (scan string) instruction is repeated with:
5216 Here is a list of opcode prefixes:
5220 @cindex section override prefixes, i386
5221 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
5222 @samp{fs}, @samp{gs}. These are automatically added by specifying
5223 using the @var{section}:@var{memory-operand} form for memory references.
5226 @cindex size prefixes, i386
5227 Operand/Address size prefixes @samp{data16} and @samp{addr16}
5228 change 32-bit operands/addresses into 16-bit operands/addresses. Note
5229 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
5230 are not supported (yet).
5233 @cindex bus lock prefixes, i386
5234 @cindex inhibiting interrupts, i386
5235 The bus lock prefix @samp{lock} inhibits interrupts during
5236 execution of the instruction it precedes. (This is only valid with
5237 certain instructions; see a 80386 manual for details).
5240 @cindex coprocessor wait, i386
5241 The wait for coprocessor prefix @samp{wait} waits for the
5242 coprocessor to complete the current instruction. This should never be
5243 needed for the 80386/80387 combination.
5246 @cindex repeat prefixes, i386
5247 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
5248 to string instructions to make them repeat @samp{%ecx} times.
5251 @node i386-Memory, i386-jumps, i386-prefixes, i386-Dependent
5252 _CHAPSEC__(1+_GENERIC__) Memory References
5254 @cindex i386 memory references
5255 @cindex memory references, i386
5256 An Intel syntax indirect memory reference of the form
5259 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
5263 is translated into the AT&T syntax
5266 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
5270 where @var{base} and @var{index} are the optional 32-bit base and
5271 index registers, @var{disp} is the optional displacement, and
5272 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
5273 to calculate the address of the operand. If no @var{scale} is
5274 specified, @var{scale} is taken to be 1. @var{section} specifies the
5275 optional section register for the memory operand, and may override the
5276 default section register (see a 80386 manual for section register
5277 defaults). Note that section overrides in AT&T syntax @emph{must} have
5278 be preceded by a @samp{%}. If you specify a section override which
5279 coincides with the default section register, @code{_AS__} will @emph{not}
5280 output any section register override prefixes to assemble the given
5281 instruction. Thus, section overrides can be specified to emphasize which
5282 section register is used for a given memory operand.
5284 Here are some examples of Intel and AT&T style memory references:
5287 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
5288 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
5289 missing, and the default section is used (@samp{%ss} for addressing with
5290 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
5292 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
5293 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
5294 @samp{foo}. All other fields are missing. The section register here
5295 defaults to @samp{%ds}.
5297 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
5298 This uses the value pointed to by @samp{foo} as a memory operand.
5299 Note that @var{base} and @var{index} are both missing, but there is only
5300 @emph{one} @samp{,}. This is a syntactic exception.
5302 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
5303 This selects the contents of the variable @samp{foo} with section
5304 register @var{section} being @samp{%gs}.
5307 Absolute (as opposed to PC relative) call and jump operands must be
5308 prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will
5309 always choose PC relative addressing for jump/call labels.
5311 Any instruction that has a memory operand @emph{must} specify its size (byte,
5312 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
5315 @node i386-jumps, i386-Float, i386-Memory, i386-Dependent
5316 _CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions
5318 @cindex jump optimization, i386
5319 @cindex i386 jump optimization
5320 Jump instructions are always optimized to use the smallest possible
5321 displacements. This is accomplished by using byte (8-bit) displacement
5322 jumps whenever the target is sufficiently close. If a byte displacement
5323 is insufficient a long (32-bit) displacement is used. We do not support
5324 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
5325 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
5326 @samp{%eip} to 16 bits after the word displacement is added.
5328 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
5329 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
5330 byte displacements, so that it is possible that use of these
5331 instructions (@code{_GCC__} does not use them) will cause the assembler to
5332 print an error message (and generate incorrect code). The AT&T 80386
5333 assembler tries to get around this problem by expanding @samp{jcxz foo} to
5341 @node i386-Float, i386-Notes, i386-jumps, i386-Dependent
5342 _CHAPSEC__(1+_GENERIC__) Floating Point
5344 @cindex i386 floating point
5345 @cindex floating point, i386
5346 All 80387 floating point types except packed BCD are supported.
5347 (BCD support may be added without much difficulty). These data
5348 types are 16-, 32-, and 64- bit integers, and single (32-bit),
5349 double (64-bit), and extended (80-bit) precision floating point.
5350 Each supported type has an opcode suffix and a constructor
5351 associated with it. Opcode suffixes specify operand's data
5352 types. Constructors build these data types into memory.
5356 @cindex @code{float} directive, i386
5357 @cindex @code{single} directive, i386
5358 @cindex @code{double} directive, i386
5359 @cindex @code{tfloat} directive, i386
5360 Floating point constructors are @samp{.float} or @samp{.single},
5361 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
5362 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
5363 @samp{t} stands for temporary real, and that the 80387 only supports
5364 this format via the @samp{fldt} (load temporary real to stack top) and
5365 @samp{fstpt} (store temporary real and pop stack) instructions.
5368 @cindex @code{word} directive, i386
5369 @cindex @code{long} directive, i386
5370 @cindex @code{int} directive, i386
5371 @cindex @code{quad} directive, i386
5372 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
5373 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
5374 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
5375 (quad). As with the temporary real format the 64-bit @samp{q} format is
5376 only present in the @samp{fildq} (load quad integer to stack top) and
5377 @samp{fistpq} (store quad integer and pop stack) instructions.
5380 Register to register operations do not require opcode suffixes,
5381 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
5383 @cindex i386 @code{fwait} instruction
5384 @cindex @code{fwait instruction}, i386
5385 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
5386 instructions are almost never needed (this is not the case for the
5387 80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses
5388 the @samp{fwait} instruction whenever it is implicitly selected by one
5389 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
5390 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
5391 instructions are made equivalent to @samp{f@dots{}} instructions. If
5392 @samp{fwait} is desired it must be explicitly coded.
5394 @node i386-Notes, , i386-Float, i386-Dependent
5395 _CHAPSEC__(1+_GENERIC__) Notes
5397 @cindex i386 @code{mul}, @code{imul} instructions
5398 @cindex @code{mul} instruction, i386
5399 @cindex @code{imul} instruction, i386
5400 There is some trickery concerning the @samp{mul} and @samp{imul}
5401 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
5402 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
5403 for @samp{imul}) can be output only in the one operand form. Thus,
5404 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
5405 the expanding multiply would clobber the @samp{%edx} register, and this
5406 would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the
5407 64-bit product in @samp{%edx:%eax}.
5409 We have added a two operand form of @samp{imul} when the first operand
5410 is an immediate mode expression and the second operand is a register.
5411 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
5412 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
5417 @c pesch@cygnus.com: we ignore the following chapters, since internals are
5418 @c changing rapidly. These may need to be moved to another
5419 @c book anyhow, if we adopt the model of user/modifier
5421 @node Maintenance, Retargeting, _MACH_DEP__, Top
5422 @chapter Maintaining the Assembler
5423 [[this chapter is still being built]]
5426 We had these goals, in descending priority:
5429 For every program composed by a compiler, @code{_AS__} should emit
5430 ``correct'' code. This leaves some latitude in choosing addressing
5431 modes, order of @code{relocation_info} structures in the object
5434 @item Speed, for usual case.
5435 By far the most common use of @code{_AS__} will be assembling compiler
5438 @item Upward compatibility for existing assembler code.
5439 Well @dots{} we don't support Vax bit fields but everything else
5440 seems to be upward compatible.
5443 The code should be maintainable with few surprises. (JF: ha!)
5447 We assumed that disk I/O was slow and expensive while memory was
5448 fast and access to memory was cheap. We expect the in-memory data
5449 structures to be less than 10 times the size of the emitted object
5450 file. (Contrast this with the C compiler where in-memory structures
5451 might be 100 times object file size!)
5455 Try to read the source file from disk only one time. For other
5456 reasons, we keep large chunks of the source file in memory during
5457 assembly so this is not a problem. Also the assembly algorithm
5458 should only scan the source text once if the compiler composed the
5459 text according to a few simple rules.
5461 Emit the object code bytes only once. Don't store values and then
5464 Build the object file in memory and do direct writes to disk of
5468 RMS suggested a one-pass algorithm which seems to work well. By not
5469 parsing text during a second pass considerable time is saved on
5470 large programs (@emph{e.g.} the sort of C program @code{yacc} would
5473 It happened that the data structures needed to emit relocation
5474 information to the object file were neatly subsumed into the data
5475 structures that do backpatching of addresses after pass 1.
5477 Many of the functions began life as re-usable modules, loosely
5478 connected. RMS changed this to gain speed. For example, input
5479 parsing routines which used to work on pre-sanitized strings now
5480 must parse raw data. Hence they have to import knowledge of the
5481 assemblers' comment conventions @emph{etc}.
5483 @section Deprecated Feature(?)s
5484 We have stopped supporting some features:
5487 @code{.org} statements must have @b{defined} expressions.
5489 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
5492 It might be a good idea to not support these features in a future release:
5495 @kbd{#} should begin a comment, even in column 1.
5497 Why support the logical line & file concept any more?
5499 Subsections are a good candidate for flushing.
5500 Depends on which compilers need them I guess.
5503 @section Bugs, Ideas, Further Work
5504 Clearly the major improvement is DON'T USE A TEXT-READING
5505 ASSEMBLER for the back end of a compiler. It is much faster to
5506 interpret binary gobbledygook from a compiler's tables than to
5507 ask the compiler to write out human-readable code just so the
5508 assembler can parse it back to binary.
5510 Assuming you use @code{_AS__} for human written programs: here are
5514 Document (here) @code{APP}.
5516 Take advantage of knowing no spaces except after opcode
5517 to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces:
5518 only keep space/tabs at begin of line or between 2
5521 Put pointers in this documentation to @file{a.out} documentation.
5523 Split the assembler into parts so it can gobble direct binary
5524 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
5525 just so @code{_AS__} can parse it back to binary.
5527 Rewrite hash functions: I want a more modular, faster library.
5529 Clean up LOTS of code.
5531 Include all the non-@file{.c} files in the maintenance chapter.
5535 Implement flonum short literals.
5537 Change all talk of expression operands to expression quantities,
5538 or perhaps to expression arguments.
5542 Whenever a @code{.text} or @code{.data} statement is seen, we close
5543 of the current frag with an imaginary @code{.fill 0}. This is
5544 because we only have one obstack for frags, and we can't grow new
5545 frags for a new subsection, then go back to the old subsection and
5546 append bytes to the old frag. All this nonsense goes away if we
5547 give each subsection its own obstack. It makes code simpler in
5548 about 10 places, but nobody has bothered to do it because C compiler
5549 output rarely changes subsections (compared to ending frags with
5550 relaxable addresses, which is common).
5554 @c The following files in the @file{_AS__} directory
5555 @c are symbolic links to other files, of
5556 @c the same name, in a different directory.
5559 @c @file{atof_generic.c}
5561 @c @file{atof_vax.c}
5563 @c @file{flonum_const.c}
5565 @c @file{flonum_copy.c}
5567 @c @file{flonum_get.c}
5569 @c @file{flonum_multip.c}
5571 @c @file{flonum_normal.c}
5573 @c @file{flonum_print.c}
5576 Here is a list of the source files in the @file{_AS__} directory.
5580 This contains the pre-processing phase, which deletes comments,
5581 handles whitespace, etc. This was recently re-written, since app
5582 used to be a separate program, but RMS wanted it to be inline.
5585 This is a subroutine to append a string to another string returning a
5586 pointer just after the last @code{char} appended. (JF: All these
5587 little routines should probably all be put in one file.)
5590 Here you will find the main program of the assembler @code{_AS__}.
5593 This is a branch office of @file{read.c}. This understands
5594 expressions, arguments. Inside @code{_AS__}, arguments are called
5595 (expression) @emph{operands}. This is confusing, because we also talk
5596 (elsewhere) about instruction @emph{operands}. Also, expression
5597 operands are called @emph{quantities} explicitly to avoid confusion
5598 with instruction operands. What a mess.
5601 This implements the @b{frag} concept. Without frags, finding the
5602 right size for branch instructions would be a lot harder.
5605 This contains the symbol table, opcode table @emph{etc.} hashing
5609 This is a table of values of digits, for use in atoi() type
5610 functions. Could probably be flushed by using calls to strtol(), or
5614 This contains Operating system dependent source file reading
5615 routines. Since error messages often say where we are in reading
5616 the source file, they live here too. Since @code{_AS__} is intended to
5617 run under GNU and Unix only, this might be worth flushing. Anyway,
5618 almost all C compilers support stdio.
5621 This deals with calling the pre-processor (if needed) and feeding the
5622 chunks back to the rest of the assembler the right way.
5625 This contains operating system independent parts of fatal and
5626 warning message reporting. See @file{append.c} above.
5629 This contains operating system dependent functions that write an
5630 object file for @code{_AS__}. See @file{input-file.c} above.
5633 This implements all the directives of @code{_AS__}. This also deals
5634 with passing input lines to the machine dependent part of the
5638 This is a C library function that isn't in most C libraries yet.
5639 See @file{append.c} above.
5642 This implements subsections.
5645 This implements symbols.
5648 This contains the code to perform relaxation, and to write out
5649 the object file. It is mostly operating system independent, but
5650 different OSes have different object file formats in any case.
5653 This implements @code{malloc()} or bust. See @file{append.c} above.
5656 This implements @code{realloc()} or bust. See @file{append.c} above.
5658 @item atof-generic.c
5659 The following files were taken from a machine-independent subroutine
5660 library for manipulating floating point numbers and very large
5663 @file{atof-generic.c} turns a string into a flonum internal format
5664 floating-point number.
5666 @item flonum-const.c
5667 This contains some potentially useful floating point numbers in
5671 This copies a flonum.
5673 @item flonum-multip.c
5674 This multiplies two flonums together.
5677 This copies a bignum.
5681 Here is a table of all the machine-specific files (this includes
5682 both source and header files). Typically, there is a
5683 @var{machine}.c file, a @var{machine}-opcode.h file, and an
5684 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
5685 be identical to the one used by GDB (which uses it for disassembly.)
5690 This contains code to turn a flonum into a ieee literal constant.
5691 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}.
5694 This is the opcode-table for the i386 version of the assembler.
5697 This contains all the code for the i386 version of the assembler.
5700 This defines constants and macros used by the i386 version of the assembler.
5703 generic 68020 header file. To be linked to m68k.h on a
5704 non-sun3, non-hpux system.
5707 68010 header file for Sun2 workstations. Not well tested. To be linked
5708 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
5712 68020 header file for Sun3 workstations. To be linked to m68k.h before
5713 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
5717 68020 header file for a HPUX (system 5?) box. Which box, which
5718 version of HPUX, etc? I don't know.
5721 A hard- or symbolic- link to one of @file{m-generic.h},
5722 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
5723 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
5727 Opcode table for 68020. This is now a link to the opcode table
5728 in the @code{GDB} source directory.
5731 All the mc680x0 code, in one huge, slow-to-compile file.
5734 This contains the code for the ns32032/ns32532 version of the
5737 @item ns32k-opcode.h
5738 This contains the opcode table for the ns32032/ns32532 version
5742 Vax specific file for describing Vax operands and other Vax-ish things.
5748 Vax specific parts of @code{_AS__}. Also includes the former files
5749 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
5752 Turns a flonum into a Vax constant.
5755 This file contains the special code needed to put out a VMS
5756 style object file for the Vax.
5760 Here is a list of the header files in the source directory.
5761 (Warning: This section may not be very accurate. I didn't
5762 write the header files; I just report them.) Also note that I
5763 think many of these header files could be cleaned up or
5769 This describes the structures used to create the binary header data
5770 inside the object file. Perhaps we should use the one in
5771 @file{/usr/include}?
5774 This defines all the globally useful things, and pulls in _0__<stdio.h>_1__
5775 and _0__<assert.h>_1__.
5778 This defines macros useful for dealing with bignums.
5781 Structure and macros for dealing with expression()
5784 This defines the structure for dealing with floating point
5785 numbers. It #includes @file{bignum.h}.
5788 This contains macro for appending a byte to the current frag.
5791 Structures and function definitions for the hashing functions.
5794 Function headers for the input-file.c functions.
5797 structures and function headers for things defined in the
5798 machine dependent part of the assembler.
5801 This is the GNU systemwide include file for manipulating obstacks.
5802 Since nobody is running under real GNU yet, we include this file.
5805 Macros and function headers for reading in source files.
5807 @item struct-symbol.h
5808 Structure definition and macros for dealing with the _AS__
5809 internal form of a symbol.
5812 structure definition for dealing with the numbered subsections
5813 of the text and data sections.
5816 Macros and function headers for dealing with symbols.
5819 Structure for doing section fixups.
5822 @comment ~subsection Test Directory
5823 @comment (Note: The test directory seems to have disappeared somewhere
5824 @comment along the line. If you want it, you'll probably have to find a
5825 @comment REALLY OLD dump tape~dots{})
5827 @comment The ~file{test/} directory is used for regression testing.
5828 @comment After you modify ~@code{_AS__}, you can get a quick go/nogo
5829 @comment confidence test by running the new ~@code{_AS__} over the source
5830 @comment files in this directory. You use a shell script ~file{test/do}.
5832 @comment The tests in this suite are evolving. They are not comprehensive.
5833 @comment They have, however, caught hundreds of bugs early in the debugging
5834 @comment cycle of ~@code{_AS__}. Most test statements in this suite were naturally
5835 @comment selected: they were used to demonstrate actual ~@code{_AS__} bugs rather
5836 @comment than being written ~i{a prioi}.
5838 @comment Another testing suggestion: over 30 bugs have been found simply by
5839 @comment running examples from this manual through ~@code{_AS__}.
5840 @comment Some examples in this manual are selected
5841 @comment to distinguish boundary conditions; they are good for testing ~@code{_AS__}.
5843 @comment ~subsubsection Regression Testing
5844 @comment Each regression test involves assembling a file and comparing the
5845 @comment actual output of ~@code{_AS__} to ``known good'' output files. Both
5846 @comment the object file and the error/warning message file (stderr) are
5847 @comment inspected. Optionally the ~@code{_AS__} exit status may be checked.
5848 @comment Discrepencies are reported. Each discrepency means either that
5849 @comment you broke some part of ~@code{_AS__} or that the ``known good'' files
5850 @comment are now out of date and should be changed to reflect the new
5851 @comment definition of ``good''.
5853 @comment Each regression test lives in its own directory, in a tree
5854 @comment rooted in the directory ~file{test/}. Each such directory
5855 @comment has a name ending in ~file{.ret}, where `ret' stands for
5856 @comment REgression Test. The ~file{.ret} ending allows ~code{find
5857 @comment (1)} to find all regression tests in the tree, without
5858 @comment needing to list them explicitly.
5860 @comment Any ~file{.ret} directory must contain a file called
5861 @comment ~file{input} which is the source file to assemble. During
5862 @comment testing an object file ~file{output} is created, as well as
5863 @comment a file ~file{stdouterr} which contains the output to both
5864 @comment stderr and stderr. If there is a file ~file{output.good} in
5865 @comment the directory, and if ~file{output} contains exactly the
5866 @comment same data as ~file{output.good}, the file ~file{output} is
5867 @comment deleted. Likewise ~file{stdouterr} is removed if it exactly
5868 @comment matches a file ~file{stdouterr.good}. If file
5869 @comment ~file{status.good} is present, containing a decimal number
5870 @comment before a newline, the exit status of ~@code{_AS__} is compared
5871 @comment to this number. If the status numbers are not equal, a file
5872 @comment ~file{status} is written to the directory, containing the
5873 @comment actual status as a decimal number followed by newline.
5875 @comment Should any of the ~file{*.good} files fail to match their corresponding
5876 @comment actual files, this is noted by a 1-line message on the screen during
5877 @comment the regression test, and you can use ~@code{find (1)} to find any
5878 @comment files named ~file{status}, ~file {output} or ~file{stdouterr}.
5880 @node Retargeting, Copying, Maintenance, Top
5881 @chapter Teaching the Assembler about a New Machine
5883 This chapter describes the steps required in order to make the
5884 assembler work with another machine's assembly language. This
5885 chapter is not complete, and only describes the steps in the
5886 broadest terms. You should look at the source for the
5887 currently supported machine in order to discover some of the
5888 details that aren't mentioned here.
5890 You should create a new file called @file{@var{machine}.c}, and
5891 add the appropriate lines to the file @file{Makefile} so that
5892 you can compile your new version of the assembler. This should
5893 be straighforward; simply add lines similar to the ones there
5894 for the four current versions of the assembler.
5896 If you want to be compatible with GDB, (and the current
5897 machine-dependent versions of the assembler), you should create
5898 a file called @file{@var{machine}-opcode.h} which should
5899 contain all the information about the names of the machine
5900 instructions, their opcodes, and what addressing modes they
5901 support. If you do this right, the assembler and GDB can share
5902 this file, and you'll only have to write it once. Note that
5903 while you're writing @code{_AS__}, you may want to use an
5904 independent program (if you have access to one), to make sure
5905 that @code{_AS__} is emitting the correct bytes. Since @code{_AS__}
5906 and @code{GDB} share the opcode table, an incorrect opcode
5907 table entry may make invalid bytes look OK when you disassemble
5908 them with @code{GDB}.
5910 @section Functions You will Have to Write
5912 Your file @file{@var{machine}.c} should contain definitions for
5913 the following functions and variables. It will need to include
5914 some header files in order to use some of the structures
5915 defined in the machine-independent part of the assembler. The
5916 needed header files are mentioned in the descriptions of the
5917 functions that will need them.
5922 This long integer holds the value to place at the beginning of
5923 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
5924 machines that store additional information in the magic-number.
5926 @item char comment_chars[];
5927 This character array holds the values of the characters that
5928 start a comment anywhere in a line. Comments are stripped off
5929 automatically by the machine independent part of the
5930 assembler. Note that the @samp{/*} will always start a
5931 comment, and that only @samp{*/} will end a comment started by
5934 @item char line_comment_chars[];
5935 This character array holds the values of the chars that start a
5936 comment only if they are the first (non-whitespace) character
5937 on a line. If the character @samp{#} does not appear in this
5938 list, you may get unexpected results. (Various
5939 machine-independent parts of the assembler treat the comments
5940 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
5941 that start with @samp{#} are comments.)
5943 @item char EXP_CHARS[];
5944 This character array holds the letters that can separate the
5945 mantissa and the exponent of a floating point number. Typical
5946 values are @samp{e} and @samp{E}.
5948 @item char FLT_CHARS[];
5949 This character array holds the letters that--when they appear
5950 immediately after a leading zero--indicate that a number is a
5951 floating-point number. (Sort of how 0x indicates that a
5952 hexadecimal number follows.)
5954 @item pseudo_typeS md_pseudo_table[];
5955 (@var{pseudo_typeS} is defined in @file{md.h})
5956 This array contains a list of the machine_dependent directives
5957 the assembler must support. It contains the name of each
5958 pseudo op (Without the leading @samp{.}), a pointer to a
5959 function to be called when that directive is encountered, and
5960 an integer argument to be passed to that function.
5962 @item void md_begin(void)
5963 This function is called as part of the assembler's
5964 initialization. It should do any initialization required by
5965 any of your other routines.
5967 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
5968 This routine is called once for each option on the command line
5969 that the machine-independent part of @code{_AS__} does not
5970 understand. This function should return non-zero if the option
5971 pointed to by @var{optionPTR} is a valid option. If it is not
5972 a valid option, this routine should return zero. The variables
5973 @var{argcPTR} and @var{argvPTR} are provided in case the option
5974 requires a filename or something similar as an argument. If
5975 the option is multi-character, @var{optionPTR} should be
5976 advanced past the end of the option, otherwise every letter in
5977 the option will be treated as a separate single-character
5980 @item void md_assemble(char *string)
5981 This routine is called for every machine-dependent
5982 non-directive line in the source file. It does all the real
5983 work involved in reading the opcode, parsing the operands,
5984 etc. @var{string} is a pointer to a null-terminated string,
5985 that comprises the input line, with all excess whitespace and
5988 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
5989 This routine is called to turn a C long int, short int, or char
5990 into the series of bytes that represents that number on the
5991 target machine. @var{outputPTR} points to an array where the
5992 result should be stored; @var{value} is the value to store; and
5993 @var{nbytes} is the number of bytes in 'value' that should be
5996 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
5997 This routine is called to turn a C long int, short int, or char
5998 into the series of bytes that represent an immediate value on
5999 the target machine. It is identical to the function @code{md_number_to_chars},
6000 except on NS32K machines.@refill
6002 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
6003 This routine is called to turn a C long int, short int, or char
6004 into the series of bytes that represent an displacement value on
6005 the target machine. It is identical to the function @code{md_number_to_chars},
6006 except on NS32K machines.@refill
6008 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
6009 This routine is identical to @code{md_number_to_chars},
6010 except on NS32K machines.
6012 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
6013 (@code{struct relocation_info} is defined in @file{a.out.h})
6014 This routine emits the relocation info in @var{ri}
6015 in the appropriate bit-pattern for the target machine.
6016 The result should be stored in the location pointed
6017 to by @var{riPTR}. This routine may be a no-op unless you are
6018 attempting to do cross-assembly.
6020 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
6021 This routine turns a series of digits into the appropriate
6022 internal representation for a floating-point number.
6023 @var{type} is a character from @var{FLT_CHARS[]} that describes
6024 what kind of floating point number is wanted; @var{outputPTR}
6025 is a pointer to an array that the result should be stored in;
6026 and @var{sizePTR} is a pointer to an integer where the size (in
6027 bytes) of the result should be stored. This routine should
6028 return an error message, or an empty string (not (char *)0) for
6031 @item int md_short_jump_size;
6032 This variable holds the (maximum) size in bytes of a short (16
6033 bit or so) jump created by @code{md_create_short_jump()}. This
6034 variable is used as part of the broken-word feature, and isn't
6035 needed if the assembler is compiled with
6036 @samp{-DWORKING_DOT_WORD}.
6038 @item int md_long_jump_size;
6039 This variable holds the (maximum) size in bytes of a long (32
6040 bit or so) jump created by @code{md_create_long_jump()}. This
6041 variable is used as part of the broken-word feature, and isn't
6042 needed if the assembler is compiled with
6043 @samp{-DWORKING_DOT_WORD}.
6045 @item void md_create_short_jump(char *resultPTR,long from_addr,
6046 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6047 This function emits a jump from @var{from_addr} to @var{to_addr} in
6048 the array of bytes pointed to by @var{resultPTR}. If this creates a
6049 type of jump that must be relocated, this function should call
6050 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
6051 emitted by this function may be smaller than @var{md_short_jump_size},
6052 but it must never create a larger one.
6053 (If it creates a smaller jump, the extra bytes of memory will not be
6054 used.) This function is used as part of the broken-word feature,
6055 and isn't needed if the assembler is compiled with
6056 @samp{-DWORKING_DOT_WORD}.@refill
6058 @item void md_create_long_jump(char *ptr,long from_addr,
6059 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6060 This function is similar to the previous function,
6061 @code{md_create_short_jump()}, except that it creates a long
6062 jump instead of a short one. This function is used as part of
6063 the broken-word feature, and isn't needed if the assembler is
6064 compiled with @samp{-DWORKING_DOT_WORD}.
6066 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
6067 This function does the initial setting up for relaxation. This
6068 includes forcing references to still-undefined symbols to the
6069 appropriate addressing modes.
6071 @item relax_typeS md_relax_table[];
6072 (relax_typeS is defined in md.h)
6073 This array describes the various machine dependent states a
6074 frag may be in before relaxation. You will need one group of
6075 entries for each type of addressing mode you intend to relax.
6077 @item void md_convert_frag(fragS *fragPTR)
6078 (@var{fragS} is defined in @file{as.h})
6079 This routine does the required cleanup after relaxation.
6080 Relaxation has changed the type of the frag to a type that can
6081 reach its destination. This function should adjust the opcode
6082 of the frag to use the appropriate addressing mode.
6083 @var{fragPTR} points to the frag to clean up.
6085 @item void md_end(void)
6086 This function is called just before the assembler exits. It
6087 need not free up memory unless the operating system doesn't do
6088 it automatically on exit. (In which case you'll also have to
6089 track down all the other places where the assembler allocates
6090 space but never frees it.)
6094 @section External Variables You will Need to Use
6096 You will need to refer to or change the following external variables
6097 from within the machine-dependent part of the assembler.
6100 @item extern char flagseen[];
6101 This array holds non-zero values in locations corresponding to
6102 the options that were on the command line. Thus, if the
6103 assembler was called with @samp{-W}, @var{flagseen['W']} would
6106 @item extern fragS *frag_now;
6107 This pointer points to the current frag--the frag that bytes
6108 are currently being added to. If nothing else, you will need
6109 to pass it as an argument to various machine-independent
6110 functions. It is maintained automatically by the
6111 frag-manipulating functions; you should never have to change it
6114 @item extern LITTLENUM_TYPE generic_bignum[];
6115 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
6116 This is where @dfn{bignums}--numbers larger than 32 bits--are
6117 returned when they are encountered in an expression. You will
6118 need to use this if you need to implement directives (or
6119 anything else) that must deal with these large numbers.
6120 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
6121 @file{as.h}, and have a positive @code{X_add_number}. The
6122 @code{X_add_number} of a @code{bignum} is the number of
6123 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
6126 @item extern FLONUM_TYPE generic_floating_point_number;
6127 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
6128 The is where @dfn{flonums}--floating-point numbers within
6129 expressions--are returned. @code{Flonums} are of @code{segT}
6130 @code{SEG_BIG}, and have a negative @code{X_add_number}.
6131 @code{Flonums} are returned in a generic format. You will have
6132 to write a routine to turn this generic format into the
6133 appropriate floating-point format for your machine.
6135 @item extern int need_pass_2;
6136 If this variable is non-zero, the assembler has encountered an
6137 expression that cannot be assembled in a single pass. Since
6138 the second pass isn't implemented, this flag means that the
6139 assembler is punting, and is only looking for additional syntax
6140 errors. (Or something like that.)
6142 @item extern segT now_seg;
6143 This variable holds the value of the section the assembler is
6144 currently assembling into.
6148 @section External functions will you need
6150 You will find the following external functions useful (or
6151 indispensable) when you're writing the machine-dependent part
6156 @item char *frag_more(int bytes)
6157 This function allocates @var{bytes} more bytes in the current
6158 frag (or starts a new frag, if it can't expand the current frag
6159 any more.) for you to store some object-file bytes in. It
6160 returns a pointer to the bytes, ready for you to store data in.
6162 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
6163 This function stores a relocation fixup to be acted on later.
6164 @var{frag} points to the frag the relocation belongs in;
6165 @var{where} is the location within the frag where the relocation begins;
6166 @var{size} is the size of the relocation, and is usually 1 (a single byte),
6167 2 (sixteen bits), or 4 (a longword).
6168 The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
6169 at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the
6170 location is subtracted from the result. A relocation entry is also added
6171 to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
6172 @var{offset} may be NULL.@refill
6174 @item char *frag_var(relax_stateT type, int max_chars, int var,
6175 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
6176 This function creates a machine-dependent frag of type @var{type}
6177 (usually @code{rs_machine_dependent}).
6178 @var{max_chars} is the maximum size in bytes that the frag may grow by;
6179 @var{var} is the current size of the variable end of the frag;
6180 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
6181 @var{md_relax_table[]} during @code{relaxation}.
6182 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
6183 @var{opcode} points into a byte whose value may have to be modified if the
6184 addressing mode used by this frag changes. It typically points into the
6185 @var{fr_literal[]} of the previous frag, and is used to point to a location
6186 that @code{md_convert_frag()}, may have to change.@refill
6188 @item void frag_wane(fragS *fragPTR)
6189 This function is useful from within @code{md_convert_frag}. It
6190 changes a frag to type rs_fill, and sets the variable-sized
6191 piece of the frag to zero. The frag will never change in size
6194 @item segT expression(expressionS *retval)
6195 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
6196 This function parses the string pointed to by the external char
6197 pointer @var{input_line_pointer}, and returns the section-type
6198 of the expression. It also stores the results in the
6199 @var{expressionS} pointed to by @var{retval}.
6200 @var{input_line_pointer} is advanced to point past the end of
6201 the expression. (@var{input_line_pointer} is used by other
6202 parts of the assembler. If you modify it, be sure to restore
6203 it to its original value.)
6205 @item as_warn(char *message,@dots{})
6206 If warning messages are disabled, this function does nothing.
6207 Otherwise, it prints out the current file name, and the current
6208 line number, then uses @code{fprintf} to print the
6209 @var{message} and any arguments it was passed.
6211 @item as_bad(char *message,@dots{})
6212 This function should be called when @code{_AS__} encounters
6213 conditions that are bad enough that @code{_AS__} should not
6214 produce an object file, but should continue reading input and
6215 printing warning and bad error messages.
6217 @item as_fatal(char *message,@dots{})
6218 This function prints out the current file name and line number,
6219 prints the word @samp{FATAL:}, then uses @code{fprintf} to
6220 print the @var{message} and any arguments it was passed. Then
6221 the assembler exits. This function should only be used for
6222 serious, unrecoverable errors.
6224 @item void float_const(int float_type)
6225 This function reads floating-point constants from the current
6226 input line, and calls @code{md_atof} to assemble them. It is
6227 useful as the function to call for the directives
6228 @samp{.single}, @samp{.double}, @samp{.float}, etc.
6229 @var{float_type} must be a character from @var{FLT_CHARS}.
6231 @item void demand_empty_rest_of_line(void);
6232 This function can be used by machine-dependent directives to
6233 make sure the rest of the input line is empty. It prints a
6234 warning message if there are additional characters on the line.
6236 @item long int get_absolute_expression(void)
6237 This function can be used by machine-dependent directives to
6238 read an absolute number from the current input line. It
6239 returns the result. If it isn't given an absolute expression,
6240 it prints a warning message and returns zero.
6245 @section The concept of Frags
6247 This assembler works to optimize the size of certain addressing
6248 modes. (e.g. branch instructions) This means the size of many
6249 pieces of object code cannot be determined until after assembly
6250 is finished. (This means that the addresses of symbols cannot be
6251 determined until assembly is finished.) In order to do this,
6252 @code{_AS__} stores the output bytes as @dfn{frags}.
6254 Here is the definition of a frag (from @file{as.h})
6260 relax_stateT fr_type;
6261 relax_substateT fr_substate;
6262 unsigned long fr_address;
6264 struct symbol *fr_symbol;
6266 struct frag *fr_next;
6273 is the size of the fixed-size piece of the frag.
6276 is the maximum (?) size of the variable-sized piece of the frag.
6279 is the type of the frag.
6284 rs_machine_dependent
6287 This stores the type of machine-dependent frag this is. (what
6288 kind of addressing mode is being used, and what size is being
6292 @var{fr_address} is only valid after relaxation is finished.
6293 Before relaxation, the only way to store an address is (pointer
6294 to frag containing the address) plus (offset into the frag).
6297 This contains a number, whose meaning depends on the type of
6299 for machine_dependent frags, this contains the offset from
6300 fr_symbol that the frag wants to go to. Thus, for branch
6301 instructions it is usually zero. (unless the instruction was
6302 @samp{jba foo+12} or something like that.)
6305 for machine_dependent frags, this points to the symbol the frag
6309 This points to the location in the frag (or in a previous frag)
6310 of the opcode for the instruction that caused this to be a frag.
6311 @var{fr_opcode} is needed if the actual opcode must be changed
6312 in order to use a different form of the addressing mode.
6313 (For example, if a conditional branch only comes in size tiny,
6314 a large-size branch could be implemented by reversing the sense
6315 of the test, and turning it into a tiny branch over a large jump.
6316 This would require changing the opcode.)
6318 @var{fr_literal} is a variable-size array that contains the
6319 actual object bytes. A frag consists of a fixed size piece of
6320 object data, (which may be zero bytes long), followed by a
6321 piece of object data whose size may not have been determined
6322 yet. Other information includes the type of the frag (which
6323 controls how it is relaxed),
6326 This is the next frag in the singly-linked list. This is
6327 usually only needed by the machine-independent part of
6333 @node Copying, Index, _MACH_DEP__, Top
6334 @unnumbered GNU GENERAL PUBLIC LICENSE
6338 @cindex copying @code{_AS__}
6339 @center Version 2, June 1991
6342 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
6343 675 Mass Ave, Cambridge, MA 02139, USA
6345 Everyone is permitted to copy and distribute verbatim copies
6346 of this license document, but changing it is not allowed.
6349 @unnumberedsec Preamble
6351 The licenses for most software are designed to take away your
6352 freedom to share and change it. By contrast, the GNU General Public
6353 License is intended to guarantee your freedom to share and change free
6354 software---to make sure the software is free for all its users. This
6355 General Public License applies to most of the Free Software
6356 Foundation's software and to any other program whose authors commit to
6357 using it. (Some other Free Software Foundation software is covered by
6358 the GNU Library General Public License instead.) You can apply it to
6361 When we speak of free software, we are referring to freedom, not
6362 price. Our General Public Licenses are designed to make sure that you
6363 have the freedom to distribute copies of free software (and charge for
6364 this service if you wish), that you receive source code or can get it
6365 if you want it, that you can change the software or use pieces of it
6366 in new free programs; and that you know you can do these things.
6368 To protect your rights, we need to make restrictions that forbid
6369 anyone to deny you these rights or to ask you to surrender the rights.
6370 These restrictions translate to certain responsibilities for you if you
6371 distribute copies of the software, or if you modify it.
6373 For example, if you distribute copies of such a program, whether
6374 gratis or for a fee, you must give the recipients all the rights that
6375 you have. You must make sure that they, too, receive or can get the
6376 source code. And you must show them these terms so they know their
6379 We protect your rights with two steps: (1) copyright the software, and
6380 (2) offer you this license which gives you legal permission to copy,
6381 distribute and/or modify the software.
6383 Also, for each author's protection and ours, we want to make certain
6384 that everyone understands that there is no warranty for this free
6385 software. If the software is modified by someone else and passed on, we
6386 want its recipients to know that what they have is not the original, so
6387 that any problems introduced by others will not reflect on the original
6388 authors' reputations.
6390 Finally, any free program is threatened constantly by software
6391 patents. We wish to avoid the danger that redistributors of a free
6392 program will individually obtain patent licenses, in effect making the
6393 program proprietary. To prevent this, we have made it clear that any
6394 patent must be licensed for everyone's free use or not licensed at all.
6396 The precise terms and conditions for copying, distribution and
6397 modification follow.
6400 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6403 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6408 This License applies to any program or other work which contains
6409 a notice placed by the copyright holder saying it may be distributed
6410 under the terms of this General Public License. The ``Program'', below,
6411 refers to any such program or work, and a ``work based on the Program''
6412 means either the Program or any derivative work under copyright law:
6413 that is to say, a work containing the Program or a portion of it,
6414 either verbatim or with modifications and/or translated into another
6415 language. (Hereinafter, translation is included without limitation in
6416 the term ``modification''.) Each licensee is addressed as ``you''.
6418 Activities other than copying, distribution and modification are not
6419 covered by this License; they are outside its scope. The act of
6420 running the Program is not restricted, and the output from the Program
6421 is covered only if its contents constitute a work based on the
6422 Program (independent of having been made by running the Program).
6423 Whether that is true depends on what the Program does.
6426 You may copy and distribute verbatim copies of the Program's
6427 source code as you receive it, in any medium, provided that you
6428 conspicuously and appropriately publish on each copy an appropriate
6429 copyright notice and disclaimer of warranty; keep intact all the
6430 notices that refer to this License and to the absence of any warranty;
6431 and give any other recipients of the Program a copy of this License
6432 along with the Program.
6434 You may charge a fee for the physical act of transferring a copy, and
6435 you may at your option offer warranty protection in exchange for a fee.
6438 You may modify your copy or copies of the Program or any portion
6439 of it, thus forming a work based on the Program, and copy and
6440 distribute such modifications or work under the terms of Section 1
6441 above, provided that you also meet all of these conditions:
6445 You must cause the modified files to carry prominent notices
6446 stating that you changed the files and the date of any change.
6449 You must cause any work that you distribute or publish, that in
6450 whole or in part contains or is derived from the Program or any
6451 part thereof, to be licensed as a whole at no charge to all third
6452 parties under the terms of this License.
6455 If the modified program normally reads commands interactively
6456 when run, you must cause it, when started running for such
6457 interactive use in the most ordinary way, to print or display an
6458 announcement including an appropriate copyright notice and a
6459 notice that there is no warranty (or else, saying that you provide
6460 a warranty) and that users may redistribute the program under
6461 these conditions, and telling the user how to view a copy of this
6462 License. (Exception: if the Program itself is interactive but
6463 does not normally print such an announcement, your work based on
6464 the Program is not required to print an announcement.)
6467 These requirements apply to the modified work as a whole. If
6468 identifiable sections of that work are not derived from the Program,
6469 and can be reasonably considered independent and separate works in
6470 themselves, then this License, and its terms, do not apply to those
6471 sections when you distribute them as separate works. But when you
6472 distribute the same sections as part of a whole which is a work based
6473 on the Program, the distribution of the whole must be on the terms of
6474 this License, whose permissions for other licensees extend to the
6475 entire whole, and thus to each and every part regardless of who wrote it.
6477 Thus, it is not the intent of this section to claim rights or contest
6478 your rights to work written entirely by you; rather, the intent is to
6479 exercise the right to control the distribution of derivative or
6480 collective works based on the Program.
6482 In addition, mere aggregation of another work not based on the Program
6483 with the Program (or with a work based on the Program) on a volume of
6484 a storage or distribution medium does not bring the other work under
6485 the scope of this License.
6488 You may copy and distribute the Program (or a work based on it,
6489 under Section 2) in object code or executable form under the terms of
6490 Sections 1 and 2 above provided that you also do one of the following:
6494 Accompany it with the complete corresponding machine-readable
6495 source code, which must be distributed under the terms of Sections
6496 1 and 2 above on a medium customarily used for software interchange; or,
6499 Accompany it with a written offer, valid for at least three
6500 years, to give any third party, for a charge no more than your
6501 cost of physically performing source distribution, a complete
6502 machine-readable copy of the corresponding source code, to be
6503 distributed under the terms of Sections 1 and 2 above on a medium
6504 customarily used for software interchange; or,
6507 Accompany it with the information you received as to the offer
6508 to distribute corresponding source code. (This alternative is
6509 allowed only for noncommercial distribution and only if you
6510 received the program in object code or executable form with such
6511 an offer, in accord with Subsection b above.)
6514 The source code for a work means the preferred form of the work for
6515 making modifications to it. For an executable work, complete source
6516 code means all the source code for all modules it contains, plus any
6517 associated interface definition files, plus the scripts used to
6518 control compilation and installation of the executable. However, as a
6519 special exception, the source code distributed need not include
6520 anything that is normally distributed (in either source or binary
6521 form) with the major components (compiler, kernel, and so on) of the
6522 operating system on which the executable runs, unless that component
6523 itself accompanies the executable.
6525 If distribution of executable or object code is made by offering
6526 access to copy from a designated place, then offering equivalent
6527 access to copy the source code from the same place counts as
6528 distribution of the source code, even though third parties are not
6529 compelled to copy the source along with the object code.
6532 You may not copy, modify, sublicense, or distribute the Program
6533 except as expressly provided under this License. Any attempt
6534 otherwise to copy, modify, sublicense or distribute the Program is
6535 void, and will automatically terminate your rights under this License.
6536 However, parties who have received copies, or rights, from you under
6537 this License will not have their licenses terminated so long as such
6538 parties remain in full compliance.
6541 You are not required to accept this License, since you have not
6542 signed it. However, nothing else grants you permission to modify or
6543 distribute the Program or its derivative works. These actions are
6544 prohibited by law if you do not accept this License. Therefore, by
6545 modifying or distributing the Program (or any work based on the
6546 Program), you indicate your acceptance of this License to do so, and
6547 all its terms and conditions for copying, distributing or modifying
6548 the Program or works based on it.
6551 Each time you redistribute the Program (or any work based on the
6552 Program), the recipient automatically receives a license from the
6553 original licensor to copy, distribute or modify the Program subject to
6554 these terms and conditions. You may not impose any further
6555 restrictions on the recipients' exercise of the rights granted herein.
6556 You are not responsible for enforcing compliance by third parties to
6560 If, as a consequence of a court judgment or allegation of patent
6561 infringement or for any other reason (not limited to patent issues),
6562 conditions are imposed on you (whether by court order, agreement or
6563 otherwise) that contradict the conditions of this License, they do not
6564 excuse you from the conditions of this License. If you cannot
6565 distribute so as to satisfy simultaneously your obligations under this
6566 License and any other pertinent obligations, then as a consequence you
6567 may not distribute the Program at all. For example, if a patent
6568 license would not permit royalty-free redistribution of the Program by
6569 all those who receive copies directly or indirectly through you, then
6570 the only way you could satisfy both it and this License would be to
6571 refrain entirely from distribution of the Program.
6573 If any portion of this section is held invalid or unenforceable under
6574 any particular circumstance, the balance of the section is intended to
6575 apply and the section as a whole is intended to apply in other
6578 It is not the purpose of this section to induce you to infringe any
6579 patents or other property right claims or to contest validity of any
6580 such claims; this section has the sole purpose of protecting the
6581 integrity of the free software distribution system, which is
6582 implemented by public license practices. Many people have made
6583 generous contributions to the wide range of software distributed
6584 through that system in reliance on consistent application of that
6585 system; it is up to the author/donor to decide if he or she is willing
6586 to distribute software through any other system and a licensee cannot
6589 This section is intended to make thoroughly clear what is believed to
6590 be a consequence of the rest of this License.
6593 If the distribution and/or use of the Program is restricted in
6594 certain countries either by patents or by copyrighted interfaces, the
6595 original copyright holder who places the Program under this License
6596 may add an explicit geographical distribution limitation excluding
6597 those countries, so that distribution is permitted only in or among
6598 countries not thus excluded. In such case, this License incorporates
6599 the limitation as if written in the body of this License.
6602 The Free Software Foundation may publish revised and/or new versions
6603 of the General Public License from time to time. Such new versions will
6604 be similar in spirit to the present version, but may differ in detail to
6605 address new problems or concerns.
6607 Each version is given a distinguishing version number. If the Program
6608 specifies a version number of this License which applies to it and ``any
6609 later version'', you have the option of following the terms and conditions
6610 either of that version or of any later version published by the Free
6611 Software Foundation. If the Program does not specify a version number of
6612 this License, you may choose any version ever published by the Free Software
6616 If you wish to incorporate parts of the Program into other free
6617 programs whose distribution conditions are different, write to the author
6618 to ask for permission. For software which is copyrighted by the Free
6619 Software Foundation, write to the Free Software Foundation; we sometimes
6620 make exceptions for this. Our decision will be guided by the two goals
6621 of preserving the free status of all derivatives of our free software and
6622 of promoting the sharing and reuse of software generally.
6625 @heading NO WARRANTY
6632 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
6633 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
6634 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
6635 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
6636 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6637 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
6638 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
6639 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
6640 REPAIR OR CORRECTION.
6643 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
6644 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
6645 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
6646 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
6647 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
6648 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
6649 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
6650 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
6651 POSSIBILITY OF SUCH DAMAGES.
6655 @heading END OF TERMS AND CONDITIONS
6658 @center END OF TERMS AND CONDITIONS
6662 @unnumberedsec Applying These Terms to Your New Programs
6664 If you develop a new program, and you want it to be of the greatest
6665 possible use to the public, the best way to achieve this is to make it
6666 free software which everyone can redistribute and change under these terms.
6668 To do so, attach the following notices to the program. It is safest
6669 to attach them to the start of each source file to most effectively
6670 convey the exclusion of warranty; and each file should have at least
6671 the ``copyright'' line and a pointer to where the full notice is found.
6674 @var{one line to give the program's name and an idea of what it does.}
6675 Copyright (C) 19@var{yy} @var{name of author}
6677 This program is free software; you can redistribute it and/or
6678 modify it under the terms of the GNU General Public License
6679 as published by the Free Software Foundation; either version 2
6680 of the License, or (at your option) any later version.
6682 This program is distributed in the hope that it will be useful,
6683 but WITHOUT ANY WARRANTY; without even the implied warranty of
6684 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6685 GNU General Public License for more details.
6687 You should have received a copy of the GNU General Public License
6688 along with this program; if not, write to the
6689 Free Software Foundation, Inc., 675 Mass Ave,
6690 Cambridge, MA 02139, USA.
6693 Also add information on how to contact you by electronic and paper mail.
6695 If the program is interactive, make it output a short notice like this
6696 when it starts in an interactive mode:
6699 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
6700 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
6701 type `show w'. This is free software, and you are welcome
6702 to redistribute it under certain conditions; type `show c'
6706 The hypothetical commands @samp{show w} and @samp{show c} should show
6707 the appropriate parts of the General Public License. Of course, the
6708 commands you use may be called something other than @samp{show w} and
6709 @samp{show c}; they could even be mouse-clicks or menu items---whatever
6712 You should also get your employer (if you work as a programmer) or your
6713 school, if any, to sign a ``copyright disclaimer'' for the program, if
6714 necessary. Here is a sample; alter the names:
6717 Yoyodyne, Inc., hereby disclaims all copyright interest in
6718 the program `Gnomovision' (which makes passes at compilers)
6719 written by James Hacker.
6721 @var{signature of Ty Coon}, 1 April 1989
6722 Ty Coon, President of Vice
6725 This General Public License does not permit incorporating your program into
6726 proprietary programs. If your program is a subroutine library, you may
6727 consider it more useful to permit linking proprietary applications with the
6728 library. If this is what you want to do, use the GNU Library General
6729 Public License instead of this License.
6731 @node Index, , Copying, Top
projects / binutils-gdb.git / blob