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
23 * As: (as). The GNU assembler.
33 NOTE: this manual is marked up for preprocessing with a collection
34 of m4 macros called "pretex.m4".
36 THIS IS THE FULL SOURCE. The full source needs to be run through m4
37 before either tex- or info- formatting: for example,
38 m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
39 will produce (assuming your path finds either GNU or SysV m4; Berkeley
40 won't do) a file, configured for the M680x0 version of GAS, suitable for
41 formatting. See the text in "pretex.m4" for a fuller explanation (and
42 the macro definitions).
47 This file documents the GNU Assembler "_AS__".
49 Copyright (C) 1991 Free Software Foundation, Inc.
51 Permission is granted to make and distribute verbatim copies of
52 this manual provided the copyright notice and this permission notice
53 are preserved on all copies.
56 Permission is granted to process this file through Tex and print the
57 results, provided the printed document carries copying permission
58 notice identical to this one except for the removal of this paragraph
59 (this paragraph not being relevant to the printed manual).
62 Permission is granted to copy and distribute modified versions of this
63 manual under the conditions for verbatim copying, provided also that the
64 section entitled ``GNU General Public License'' is included exactly as
65 in the original, and provided that the entire resulting derived work is
66 distributed under the terms of a permission notice identical to this
69 Permission is granted to copy and distribute translations of this manual
70 into another language, under the above conditions for modified versions,
71 except that the section entitled ``GNU General Public License'' may be
72 included in a translation approved by the Free Software Foundation
73 instead of in the original English.
78 @subtitle The GNU Assembler
80 @subtitle for the _HOST__ family
83 @subtitle January 1992
86 The Free Software Foundation Inc. thanks The Nice Computer
87 Company of Australia for loaning Dean Elsner to write the
88 first (Vax) version of @code{as} for Project GNU.
89 The proprietors, management and staff of TNCCA thank FSF for
90 distracting the boss while they got some work
93 @author Dean Elsner, Jay Fenlason & friends
94 @c edited by: pesch@cygnus.com
97 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
98 \xdef\manvers{\$Revision$} % For use in headers, footers too
100 \hfill {\it Using {\tt _AS__}} \manvers\par
101 \hfill \TeX{}info \texinfoversion\par
102 \hfill Edited by Roland Pesch for Cygnus Support\par
104 %"boxit" macro for figures:
105 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
106 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
107 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
108 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
109 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
112 @vskip 0pt plus 1filll
113 Copyright @copyright{} 1991 Free Software Foundation, Inc.
115 Permission is granted to make and distribute verbatim copies of
116 this manual provided the copyright notice and this permission notice
117 are preserved on all copies.
119 Permission is granted to copy and distribute modified versions of this
120 manual under the conditions for verbatim copying, provided also that the
121 section entitled ``GNU General Public License'' is included exactly as
122 in the original, and provided that the entire resulting derived work is
123 distributed under the terms of a permission notice identical to this
126 Permission is granted to copy and distribute translations of this manual
127 into another language, under the above conditions for modified versions,
128 except that the section entitled ``GNU General Public License'' may be
129 included in a translation approved by the Free Software Foundation
130 instead of in the original English.
133 @node Top, Overview, (dir), (dir)
135 This file is a user guide to the GNU assembler @code{_AS__}.
137 This version of the file describes @code{_AS__} configured to generate
138 code for _HOST__ architectures.
142 * Overview:: Overview
143 * Invoking:: Command-Line Options
145 * Sections:: Sections and Relocation
147 * Expressions:: Expressions
148 * Pseudo Ops:: Assembler Directives
149 * _MACH_DEP__:: Machine Dependent Features
150 * Copying:: GNU GENERAL PUBLIC LICENSE
154 @node Overview, Invoking, Top, Top
157 This manual is a user guide to the GNU assembler @code{_AS__}.
159 This version of the manual describes @code{_AS__} configured to generate
160 code for _HOST__ architectures.
164 @cindex invocation summary
165 @cindex option summary
166 @cindex summary of options
167 Here is a brief summary of how to invoke @code{_AS__}. For details,
168 @pxref{Invoking,,Comand-Line Options}.
170 @c We don't use deffn and friends for the following because they seem
171 @c to be limited to one line for the header.
173 _AS__ [ -a | -al | -as ] [ -D ] [ -f ]
174 [ -I @var{path} ] [ -K ] [ -L ]
175 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
177 @c am29k has no machine-dependent assembler options
180 @c h8/300 has no machine-dependent assembler options
183 @c see md_parse_option in i960.c
184 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
188 [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
190 [ -- | @var{files} @dots{} ]
195 Turn on assembly listings; @samp{-al}, listing only, @samp{-as}, symbols
196 only, @samp{-a}, everything.
199 This option is accepted only for script compatibility with calls to
200 other assemblers; it has no effect on @code{_AS__}.
203 ``fast''---skip preprocessing (assume source is compiler output)
206 Add @var{path} to the search list for @code{.include} directives
209 _if__((!_GENERIC__) && !_DIFFTABKLUG__)
210 This option is accepted but has no effect on the _HOST__ family.
211 _fi__((!_GENERIC__) && !_DIFFTABKLUG__)
212 _if__(_GENERIC__ || _DIFFTABKLUG__)
213 Issue warnings when difference tables altered for long displacements.
214 _fi__(_GENERIC__ || _DIFFTABKLUG__)
217 Keep (in symbol table) local symbols, starting with @samp{L}
219 @item -o @var{objfile}
220 Name the object-file output from @code{_AS__}
223 Fold data section into text section
226 Announce @code{as} version
229 Suppress warning messages
232 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
234 (When configured for Intel 960).
236 Specify which variant of the 960 architecture is the target.
240 (When configured for Intel 960).
242 Add code to collect statistics about branches taken.
246 (When configured for Intel 960).
248 Do not alter compare-and-branch instructions for long displacements;
255 (When configured for Motorola 68000).
257 Shorten references to undefined symbols, to one word instead of two
259 @item -mc68000 | -mc68010 | -mc68020
261 (When configured for Motorola 68000).
263 Specify what processor in the 68000 family is the target (default 68020)
266 @item -- | @var{files} @dots{}
267 Standard input, or source files to assemble
271 * Manual:: Structure of this Manual
272 * GNU Assembler:: _AS__, the GNU Assembler
273 * Object Formats:: Object File Formats
274 * Command Line:: Command Line
275 * Input Files:: Input Files
276 * Object:: Output (Object) File
277 * Errors:: Error and Warning Messages
280 @node Manual, GNU Assembler, Overview, Overview
281 @section Structure of this Manual
283 @cindex manual, structure and purpose
284 This manual is intended to describe what you need to know to use
285 @sc{gnu} @code{_AS__}. We cover the syntax expected in source files, including
286 notation for symbols, constants, and expressions; the directives that
287 @code{_AS__} understands; and of course how to invoke @code{_AS__}.
290 We also cover special features in the _HOST__
291 configuration of @code{_AS__}, including assembler directives.
294 This manual also describes some of the machine-dependent features of
295 various flavors of the assembler.
298 This manual also describes how the assembler works internally, and
299 provides some information that may be useful to people attempting to
300 port the assembler to another machine.
304 @cindex machine instructions (not covered)
305 On the other hand, this manual is @emph{not} intended as an introduction
306 to programming in assembly language---let alone programming in general!
307 In a similar vein, we make no attempt to introduce the machine
308 architecture; we do @emph{not} describe the instruction set, standard
309 mnemonics, registers or addressing modes that are standard to a
310 particular architecture.
312 You may want to consult the manufacturer's
313 machine architecture manual for this information.
315 _if__(_H8__&&!_GENERIC__)
316 For information on the H8/300 machine instruction set, see @cite{H8/300
317 Series Programming Manual} (Hitachi ADE--602--025).
318 _fi__(_H8__&&!_GENERIC__)
321 @c I think this is premature---pesch@cygnus.com, 17jan1991
323 Throughout this manual, we assume that you are running @dfn{GNU},
324 the portable operating system from the @dfn{Free Software
325 Foundation, Inc.}. This restricts our attention to certain kinds of
326 computer (in particular, the kinds of computers that GNU can run on);
327 once this assumption is granted examples and definitions need less
330 @code{_AS__} is part of a team of programs that turn a high-level
331 human-readable series of instructions into a low-level
332 computer-readable series of instructions. Different versions of
333 @code{_AS__} are used for different kinds of computer.
336 @c There used to be a section "Terminology" here, which defined
337 @c "contents", "byte", "word", and "long". Defining "word" to any
338 @c particular size is confusing when the .word directive may generate 16
339 @c bits on one machine and 32 bits on another; in general, for the user
340 @c version of this manual, none of these terms seem essential to define.
341 @c They were used very little even in the former draft of the manual;
342 @c this draft makes an effort to avoid them (except in names of
345 @node GNU Assembler, Object Formats, Manual, Overview
346 @section _AS__, the GNU Assembler
348 GNU @code{as} is really a family of assemblers.
350 This manual describes @code{_AS__}, a member of that family which is
351 configured for the _HOST__ architectures.
353 If you use (or have used) the GNU assembler on one architecture, you
354 should find a fairly similar environment when you use it on another
355 architecture. Each version has much in common with the others,
356 including object file formats, most assembler directives (often called
357 @dfn{pseudo-ops)} and assembler syntax.@refill
359 _if__(_GENERIC__||!_H8__)
360 @cindex purpose of @sc{gnu} @code{_AS__}
361 @code{_AS__} is primarily intended to assemble the output of the GNU C
362 compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless,
363 we've tried to make @code{_AS__} assemble correctly everything that the native
365 _fi__(_GENERIC__||!_H8__)
367 Any exceptions are documented explicitly (@pxref{_MACH_DEP__}).
369 _if__(_GENERIC__||_M680X0__)
370 This doesn't mean @code{_AS__} always uses the same syntax as another
371 assembler for the same architecture; for example, we know of several
372 incompatible versions of 680x0 assembly language syntax.
373 _fi__(_GENERIC__||_M680X0__)
375 Unlike older assemblers, @code{_AS__} is designed to assemble a source
376 program in one pass of the source file. This has a subtle impact on the
377 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
379 @node Object Formats, Command Line, GNU Assembler, Overview
380 @section Object File Formats
382 @cindex object file format
383 The GNU assembler can be configured to produce several alternative
384 object file formats. For the most part, this does not affect how you
385 write assembly language programs; but directives for debugging symbols
386 are typically different in different file formats. @xref{Symbol
387 Attributes,,Symbol Attributes}.
389 _if__(!(_I960__||_A29K__))
390 _if__(_AOUT__ && (!_COFF__) && (!_ELF__))
391 On the _HOST__, @code{_AS__} is configured to produce @code{a.out} format object
393 _fi__(_AOUT__ && (!_COFF__) && (!_ELF__))
394 _if__((!_AOUT__) && _COFF__ && (!_ELF__))
395 On the _HOST__, @code{_AS__} is configured to produce COFF format object
397 _fi__((!_AOUT__) && _COFF__ && (!_ELF__))
398 _fi__(!(_I960__||_A29K__))
400 On the _HOST__, @code{_AS__} can be configured to produce either
401 @code{a.out} or COFF format object files.
404 On the _HOST__, @code{_AS__} can be configured to produce either @code{b.out} or COFF
409 @node Command Line, Input Files, Object Formats, Overview
410 @section Command Line
412 @cindex command line conventions
413 After the program name @code{_AS__}, the command line may contain
414 options and file names. Options may appear in any order, and may be
415 before, after, or between file names. The order of file names is
418 @cindex standard input, as input file
420 @file{--} (two hyphens) by itself names the standard input file
421 explicitly, as one of the files for @code{_AS__} to assemble.
423 @cindex options, command line
424 Except for @samp{--} any command line argument that begins with a
425 hyphen (@samp{-}) is an option. Each option changes the behavior of
426 @code{_AS__}. No option changes the way another option works. An
427 option is a @samp{-} followed by one or more letters; the case of
428 the letter is important. All options are optional.
430 Some options expect exactly one file name to follow them. The file
431 name may either immediately follow the option's letter (compatible
432 with older assemblers) or it may be the next command argument (GNU
433 standard). These two command lines are equivalent:
436 _AS__ -o my-object-file.o mumble.s
437 _AS__ -omy-object-file.o mumble.s
440 @node Input Files, Object, Command Line, Overview
444 @cindex source program
446 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
447 describe the program input to one run of @code{_AS__}. The program may
448 be in one or more files; how the source is partitioned into files
449 doesn't change the meaning of the source.
451 @c I added "con" prefix to "catenation" just to prove I can overcome my
452 @c APL training... pesch@cygnus.com
453 The source program is a concatenation of the text in all the files, in the
456 Each time you run @code{_AS__} it assembles exactly one source
457 program. The source program is made up of one or more files.
458 (The standard input is also a file.)
460 You give @code{_AS__} a command line that has zero or more input file
461 names. The input files are read (from left file name to right). A
462 command line argument (in any position) that has no special meaning
463 is taken to be an input file name.
465 If you give @code{_AS__} no file names it attempts to read one input file
466 from the @code{_AS__} standard input, which is normally your terminal. You
467 may have to type @key{ctl-D} to tell @code{_AS__} there is no more program
470 Use @samp{--} if you need to explicitly name the standard input file
471 in your command line.
473 If the source is empty, @code{_AS__} will produce a small, empty object
476 @subheading Filenames and Line-numbers
478 @cindex input file linenumbers
479 @cindex line numbers, in input files
480 There are two ways of locating a line in the input file (or files) and
481 either may be used in reporting error messages. One way refers to a line
482 number in a physical file; the other refers to a line number in a
483 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
485 @dfn{Physical files} are those files named in the command line given
488 @dfn{Logical files} are simply names declared explicitly by assembler
489 directives; they bear no relation to physical files. Logical file names
490 help error messages reflect the original source file, when @code{_AS__}
491 source is itself synthesized from other files.
492 @xref{App-File,,@code{.app-file}}.
494 @node Object, Errors, Input Files, Overview
495 @section Output (Object) File
501 Every time you run @code{_AS__} it produces an output file, which is
502 your assembly language program translated into numbers. This file
503 is the object file, named @code{a.out} unless you tell @code{_AS__} to
504 give it another name by using the @code{-o} option. Conventionally,
505 object file names end with @file{.o}. The default name of
506 @file{a.out} is used for historical reasons: older assemblers were
507 capable of assembling self-contained programs directly into a
509 @c This may still work, but hasn't been tested.
513 The object file is meant for input to the linker @code{_LD__}. It contains
514 assembled program code, information to help @code{_LD__} integrate
515 the assembled program into a runnable file, and (optionally) symbolic
516 information for the debugger.
518 @c link above to some info file(s) like the description of a.out.
519 @c don't forget to describe GNU info as well as Unix lossage.
521 @node Errors, , Object, Overview
522 @section Error and Warning Messages
524 @cindex error messsages
525 @cindex warning messages
526 @cindex messages from @code{_AS__}
527 @code{_AS__} may write warnings and error messages to the standard error
528 file (usually your terminal). This should not happen when a compiler
529 runs @code{_AS__} automatically. Warnings report an assumption made so
530 that @code{_AS__} could keep assembling a flawed program; errors report a
531 grave problem that stops the assembly.
533 @cindex format of warning messages
534 Warning messages have the format
537 file_name:@b{NNN}:Warning Message Text
541 @cindex line numbers, in warnings/errors
542 (where @b{NNN} is a line number). If a logical file name has
543 been given (@pxref{App-File,,@code{.app-file}}) it is used for the filename, otherwise the
544 name of the current input file is used. If a logical line number was
547 (@pxref{Line,,@code{.line}})
550 (@pxref{Ln,,@code{.ln}})
552 then it is used to calculate the number printed,
553 otherwise the actual line in the current source file is printed. The
554 message text is intended to be self explanatory (in the grand Unix
557 @cindex format of error messages
558 Error messages have the format
560 file_name:@b{NNN}:FATAL:Error Message Text
562 The file name and line number are derived as for warning
563 messages. The actual message text may be rather less explanatory
564 because many of them aren't supposed to happen.
566 @node Invoking, Syntax, Overview, Top
567 @chapter Command-Line Options
569 @cindex options, all versions of @code{_AS__}
570 This chapter describes command-line options available in @emph{all}
571 versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific
576 to particular machine architectures.
579 @section Enable Listings: @code{-a}, @code{-al}, @code{-as}
584 @cindex listings, enabling
585 @cindex assembly listings, enabling
586 These options enable listing output from the assembler. @samp{-a} by
587 itself requests all listing output; @samp{-al} requests only the
588 output-program listing, and @samp{-as} requests only a symbol table
591 Once you have specified one of these options, you can further control
592 listing output and its appearance using the directives @code{.list},
593 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
596 If you do not request listing output with one of the @samp{-a} options, the
597 listing-control directives have no effect.
602 This option has no effect whatsoever, but it is accepted to make it more
603 likely that scripts written for other assemblers will also work with
606 @section Work Faster: @code{-f}
609 @cindex trusted compiler
610 @cindex faster processing (@code{-f})
611 @samp{-f} should only be used when assembling programs written by a
612 (trusted) compiler. @samp{-f} stops the assembler from pre-processing
613 the input file(s) before assembling them. @xref{Pre-processing,
617 @emph{Warning:} if the files actually need to be pre-processed (if they
618 contain comments, for example), @code{_AS__} will not work correctly if
622 @section @code{.include} search path: @code{-I} @var{path}
624 @kindex -I @var{path}
625 @cindex paths for @code{.include}
626 @cindex search path for @code{.include}
627 @cindex @code{include} directive search path
628 Use this option to add a @var{path} to the list of directories
629 @code{_AS__} will search for files specified in @code{.include}
630 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
631 many times as necessary to include a variety of paths. The current
632 working directory is always searched first; after that, @code{_AS__}
633 searches any @samp{-I} directories in the same order as they were
634 specified (left to right) on the command line.
636 @section Difference Tables: @code{-K}
639 _if__((!_GENERIC__) && (!_DIFFTABKLUG__))
640 On the _HOST__ family, this option is allowed, but has no effect. It is
641 permitted for compatibility with the GNU assembler on other platforms,
642 where it can be used to warn when the assembler alters the machine code
643 generated for @samp{.word} directives in difference tables. The _HOST__
644 family does not have the addressing limitations that sometimes lead to this
645 alteration on other platforms.
646 _fi__((!_GENERIC__) && (!_DIFFTABKLUG__))
648 _if__(_GENERIC__ || _DIFFTABKLUG__ )
649 @cindex difference tables, warning
650 @cindex warning for altered difference tables
651 @code{_AS__} sometimes alters the code emitted for directives of the form
652 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
653 You can use the @samp{-K} option if you want a warning issued when this
655 _fi__(_GENERIC__ || _DIFFTABKLUG__ )
657 @section Include Local Labels: @code{-L}
660 @cindex local labels, retaining in output
661 Labels beginning with @samp{L} (upper case only) are called @dfn{local
662 labels}. @xref{Symbol Names}. Normally you don't see such labels when
663 debugging, because they are intended for the use of programs (like
664 compilers) that compose assembler programs, not for your notice.
665 Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't
666 normally debug with them.
668 This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols
669 in the object file. Usually if you do this you also tell the linker
670 @code{_LD__} to preserve symbols whose names begin with @samp{L}.
672 @section Name the Object File: @code{-o}
675 @cindex naming object file
676 @cindex object file name
677 There is always one object file output when you run @code{_AS__}. By
678 default it has the name @file{a.out}. You use this option (which
679 takes exactly one filename) to give the object file a different name.
681 Whatever the object file is called, @code{_AS__} will overwrite any
682 existing file of the same name.
684 @section Join Data and Text Sections: @code{-R}
687 @cindex data and text sections, joining
688 @cindex text and data sections, joining
689 @cindex joining text and data sections
690 @cindex merging text and data sections
691 @code{-R} tells @code{_AS__} to write the object file as if all
692 data-section data lives in the text section. This is only done at
693 the very last moment: your binary data are the same, but data
694 section parts are relocated differently. The data section part of
695 your object file is zero bytes long because all it bytes are
696 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
698 When you specify @code{-R} it would be possible to generate shorter
699 address displacements (because we don't have to cross between text and
700 data section). We refrain from doing this simply for compatibility with
701 older versions of @code{_AS__}. In future, @code{-R} may work this way.
704 When @code{_AS__} is configured for COFF output,
705 this option is only useful if you use sections named @samp{.text} and
709 @section Announce Version: @code{-v}
713 @cindex @code{_AS__} version
714 @cindex version of @code{_AS__}
715 You can find out what version of as is running by including the
716 option @samp{-v} (which you can also spell as @samp{-version}) on the
719 @section Suppress Warnings: @code{-W}
722 @cindex suppressing warnings
723 @cindex warnings, suppressing
724 @code{_AS__} should never give a warning or error message when
725 assembling compiler output. But programs written by people often
726 cause @code{_AS__} to give a warning that a particular assumption was
727 made. All such warnings are directed to the standard error file.
728 If you use this option, no warnings are issued. This option only
729 affects the warning messages: it does not change any particular of how
730 @code{_AS__} assembles your file. Errors, which stop the assembly, are
733 @node Syntax, Sections, Invoking, Top
736 @cindex machine-independent syntax
737 @cindex syntax, machine-independent
738 This chapter describes the machine-independent syntax allowed in a
739 source file. @code{_AS__} syntax is similar to what many other assemblers
740 use; it is inspired in BSD 4.2
745 assembler, except that @code{_AS__} does not assemble Vax bit-fields.
749 * Pre-processing:: Pre-processing
750 * Whitespace:: Whitespace
751 * Comments:: Comments
752 * Symbol Intro:: Symbols
753 * Statements:: Statements
754 * Constants:: Constants
757 @node Pre-processing, Whitespace, Syntax, Syntax
758 @section Pre-Processing
760 @cindex preprocessing
763 @cindex whitespace, removed by preprocessor
765 adjusts and removes extra whitespace. It leaves one space or tab before
766 the keywords on a line, and turns any other whitespace on the line into
769 @cindex comments, removed by preprocessor
771 removes all comments, replacing them with a single space, or an
772 appropriate number of newlines.
774 @cindex constants, converted by preprocessor
776 converts character constants into the appropriate numeric values.
779 Excess whitespace, comments, and character constants
780 cannot be used in the portions of the input text that are not
783 @cindex turning preprocessing on and off
784 @cindex preprocessing, turning on and off
787 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
788 option is given, the input file will not be pre-processed. Within such
789 an input file, parts of the file can be pre-processed by putting a line
790 that says @code{#APP} before the text that should be pre-processed, and
791 putting a line that says @code{#NO_APP} after them. This feature is
792 mainly intend to support @code{asm} statements in compilers whose output
793 normally does not need to be pre-processed.
795 @node Whitespace, Comments, Pre-processing, Syntax
799 @dfn{Whitespace} is one or more blanks or tabs, in any order.
800 Whitespace is used to separate symbols, and to make programs neater for
801 people to read. Unless within character constants
802 (@pxref{Characters,,Character Constants}), any whitespace means the same
803 as exactly one space.
805 @node Comments, Symbol Intro, Whitespace, Syntax
809 There are two ways of rendering comments to @code{_AS__}. In both
810 cases the comment is equivalent to one space.
812 Anything from @samp{/*} through the next @samp{*/} is a comment.
813 This means you may not nest these comments.
817 The only way to include a newline ('\n') in a comment
818 is to use this sort of comment.
821 /* This sort of comment does not nest. */
824 @cindex line comment character
825 Anything from the @dfn{line comment} character to the next newline
826 is considered a comment and is ignored. The line comment character is
831 @samp{#} on the i960;
834 @samp{|} on the 680x0;
837 @samp{;} for the AMD 29K family;
840 @samp{;} for the _HOST__ family;
842 @pxref{_MACH_DEP__}. @refill
843 @c FIXME: fill in SPARC line comment char
846 On some machines there are two different line comment characters. One
847 will only begin a comment if it is the first non-whitespace character on
848 a line, while the other will always begin a comment.
852 @cindex lines starting with @code{#}
853 @cindex logical line numbers
854 To be compatible with past assemblers, a special interpretation is
855 given to lines that begin with @samp{#}. Following the @samp{#} an
856 absolute expression (@pxref{Expressions}) is expected: this will be
857 the logical line number of the @b{next} line. Then a string
858 (@xref{Strings}.) is allowed: if present it is a new logical file
859 name. The rest of the line, if any, should be whitespace.
861 If the first non-whitespace characters on the line are not numeric,
862 the line is ignored. (Just like a comment.)
864 # This is an ordinary comment.
865 # 42-6 "new_file_name" # New logical file name
866 # This is logical line # 36.
868 This feature is deprecated, and may disappear from future versions
871 @node Symbol Intro, Statements, Comments, Syntax
874 @cindex characters used in symbols
875 A @dfn{symbol} is one or more characters chosen from the set of all
876 letters (both upper and lower case), digits and
878 the three characters @samp{_.$}
881 the two characters @samp{_.}
883 On most machines, you can also use @code{$} in symbol names; exceptions
884 are noted in @ref{_MACH_DEP__}.
887 No symbol may begin with a digit. Case is significant.
888 There is no length limit: all characters are significant. Symbols are
889 delimited by characters not in that set, or by the beginning of a file
890 (since the source program must end with a newline, the end of a file is
891 not a possible symbol delimiter). @xref{Symbols}.
892 @cindex length of symbols
894 @node Statements, Constants, Symbol Intro, Syntax
897 @cindex statements, structure of
898 @cindex line separator character
899 @cindex statement separator character
901 _if__(!(_A29K__||_H8__))
902 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
903 semicolon (@samp{;}). The newline or semicolon is considered part of
904 the preceding statement. Newlines and semicolons within character
905 constants are an exception: they don't end statements.
906 _fi__(!(_A29K__||_H8__))
908 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
909 sign (@samp{@@}). The newline or at sign is considered part of the
910 preceding statement. Newlines and at signs within character constants
911 are an exception: they don't end statements.
914 A @dfn{statement} ends at a newline character (@samp{\n}) or a dollar
915 sign (@samp{$}). The newline or dollar sign is considered part of the
916 preceding statement. Newlines and dollar signs within character constants
917 are an exception: they don't end statements.
921 A @dfn{statement} ends at a newline character (@samp{\n}) or line
922 separator character. (The line separator is usually @samp{;}, unless
923 this conflicts with the comment character; @pxref{_MACH_DEP__}.) The
924 newline or separator character is considered part of the preceding
925 statement. Newlines and separators within character constants are an
926 exception: they don't end statements.
929 @cindex newline, required at file end
930 @cindex EOF, newline must precede
931 It is an error to end any statement with end-of-file: the last
932 character of any input file should be a newline.@refill
934 @cindex continuing statements
935 @cindex multi-line statements
936 @cindex statement on multiple lines
937 You may write a statement on more than one line if you put a
938 backslash (@kbd{\}) immediately in front of any newlines within the
939 statement. When @code{_AS__} reads a backslashed newline both
940 characters are ignored. You can even put backslashed newlines in
941 the middle of symbol names without changing the meaning of your
944 An empty statement is allowed, and may include whitespace. It is ignored.
946 @cindex instructions and directives
947 @cindex directives and instructions
948 @c "key symbol" is not used elsewhere in the document; seems pedantic to
949 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
951 A statement begins with zero or more labels, optionally followed by a
952 key symbol which determines what kind of statement it is. The key
953 symbol determines the syntax of the rest of the statement. If the
954 symbol begins with a dot @samp{.} then the statement is an assembler
955 directive: typically valid for any computer. If the symbol begins with
956 a letter the statement is an assembly language @dfn{instruction}: it
957 will assemble into a machine language instruction.
959 Different versions of @code{_AS__} for different computers will
960 recognize different instructions. In fact, the same symbol may
961 represent a different instruction in a different computer's assembly
965 @cindex @code{:} (label)
966 @cindex label (@code{:})
967 A label is a symbol immediately followed by a colon (@code{:}).
968 Whitespace before a label or after a colon is permitted, but you may not
969 have whitespace between a label's symbol and its colon. @xref{Labels}.
972 label: .directive followed by something
973 another_label: # This is an empty statement.
974 instruction operand_1, operand_2, @dots{}
977 @node Constants, , Statements, Syntax
981 A constant is a number, written so that its value is known by
982 inspection, without knowing any context. Like this:
984 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
985 .ascii "Ring the bell\7" # A string constant.
986 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
987 .float 0f-314159265358979323846264338327\
988 95028841971.693993751E-40 # - pi, a flonum.
992 * Characters:: Character Constants
993 * Numbers:: Number Constants
996 @node Characters, Numbers, Constants, Constants
997 @subsection Character Constants
999 @cindex character constants
1000 @cindex constants, character
1001 There are two kinds of character constants. A @dfn{character} stands
1002 for one character in one byte and its value may be used in
1003 numeric expressions. String constants (properly called string
1004 @emph{literals}) are potentially many bytes and their values may not be
1005 used in arithmetic expressions.
1009 * Chars:: Characters
1012 @node Strings, Chars, Characters, Characters
1013 @subsubsection Strings
1015 @cindex string constants
1016 @cindex constants, string
1017 A @dfn{string} is written between double-quotes. It may contain
1018 double-quotes or null characters. The way to get special characters
1019 into a string is to @dfn{escape} these characters: precede them with
1020 a backslash @samp{\} character. For example @samp{\\} represents
1021 one backslash: the first @code{\} is an escape which tells
1022 @code{_AS__} to interpret the second character literally as a backslash
1023 (which prevents @code{_AS__} from recognizing the second @code{\} as an
1024 escape character). The complete list of escapes follows.
1026 @cindex escape codes, character
1027 @cindex character escape codes
1030 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1033 @cindex @code{\b} (backspace character)
1034 @cindex backspace (@code{\b})
1035 Mnemonic for backspace; for ASCII this is octal code 010.
1038 @c Mnemonic for EOText; for ASCII this is octal code 004.
1041 @cindex @code{\f} (formfeed character)
1042 @cindex formfeed (@code{\f})
1043 Mnemonic for FormFeed; for ASCII this is octal code 014.
1046 @cindex @code{\n} (newline character)
1047 @cindex newline (@code{\n})
1048 Mnemonic for newline; for ASCII this is octal code 012.
1051 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1054 @cindex @code{\r} (carriage return character)
1055 @cindex carriage return (@code{\r})
1056 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1059 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1060 @c other assemblers.
1063 @cindex @code{\t} (tab)
1064 @cindex tab (@code{\t})
1065 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1068 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1069 @c @item \x @var{digit} @var{digit} @var{digit}
1070 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1072 @item \ @var{digit} @var{digit} @var{digit}
1073 @cindex @code{\@var{ddd}} (octal character code)
1074 @cindex octal character code (@code{\@var{ddd}})
1075 An octal character code. The numeric code is 3 octal digits.
1076 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1077 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1080 @cindex @code{\\} (@samp{\} character)
1081 @cindex backslash (@code{\\})
1082 Represents one @samp{\} character.
1085 @c Represents one @samp{'} (accent acute) character.
1086 @c This is needed in single character literals
1087 @c (@xref{Characters,,Character Constants}.) to represent
1091 @cindex @code{\"} (doublequote character)
1092 @cindex doublequote (@code{\"})
1093 Represents one @samp{"} character. Needed in strings to represent
1094 this character, because an unescaped @samp{"} would end the string.
1096 @item \ @var{anything-else}
1097 Any other character when escaped by @kbd{\} will give a warning, but
1098 assemble as if the @samp{\} was not present. The idea is that if
1099 you used an escape sequence you clearly didn't want the literal
1100 interpretation of the following character. However @code{_AS__} has no
1101 other interpretation, so @code{_AS__} knows it is giving you the wrong
1102 code and warns you of the fact.
1105 Which characters are escapable, and what those escapes represent,
1106 varies widely among assemblers. The current set is what we think
1107 the BSD 4.2 assembler recognizes, and is a subset of what most C
1108 compilers recognize. If you are in doubt, don't use an escape
1111 @node Chars, , Strings, Characters
1112 @subsubsection Characters
1114 @cindex single character constant
1115 @cindex character, single
1116 @cindex constant, single character
1117 A single character may be written as a single quote immediately
1118 followed by that character. The same escapes apply to characters as
1119 to strings. So if you want to write the character backslash, you
1120 must write @kbd{'\\} where the first @code{\} escapes the second
1121 @code{\}. As you can see, the quote is an acute accent, not a
1122 grave accent. A newline
1124 _if__(!(_A29K__||_H8__))
1125 (or semicolon @samp{;})
1126 _fi__(!(_A29K__||_H8__))
1128 (or at sign @samp{@@})
1131 (or dollar sign @samp{$})
1134 immediately following an acute accent is taken as a literal character
1135 and does not count as the end of a statement. The value of a character
1136 constant in a numeric expression is the machine's byte-wide code for
1137 that character. @code{_AS__} assumes your character code is ASCII:
1138 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1140 @node Numbers, , Characters, Constants
1141 @subsection Number Constants
1143 @cindex constants, number
1144 @cindex number constants
1145 @code{_AS__} distinguishes three kinds of numbers according to how they
1146 are stored in the target machine. @emph{Integers} are numbers that
1147 would fit into an @code{int} in the C language. @emph{Bignums} are
1148 integers, but they are stored in more than 32 bits. @emph{Flonums}
1149 are floating point numbers, described below.
1152 * Integers:: Integers
1155 _if__(_I960__&&!_GENERIC__)
1156 * Bit Fields:: Bit Fields
1157 _fi__(_I960__&&!_GENERIC__)
1160 @node Integers, Bignums, Numbers, Numbers
1161 @subsubsection Integers
1163 @cindex constants, integer
1165 @cindex binary integers
1166 @cindex integers, binary
1167 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1168 the binary digits @samp{01}.
1170 @cindex octal integers
1171 @cindex integers, octal
1172 An octal integer is @samp{0} followed by zero or more of the octal
1173 digits (@samp{01234567}).
1175 @cindex decimal integers
1176 @cindex integers, decimal
1177 A decimal integer starts with a non-zero digit followed by zero or
1178 more digits (@samp{0123456789}).
1180 @cindex hexadecimal integers
1181 @cindex integers, hexadecimal
1182 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1183 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1185 Integers have the usual values. To denote a negative integer, use
1186 the prefix operator @samp{-} discussed under expressions
1187 (@pxref{Prefix Ops,,Prefix Operators}).
1189 @node Bignums, Flonums, Integers, Numbers
1190 @subsubsection Bignums
1193 @cindex constants, bignum
1194 A @dfn{bignum} has the same syntax and semantics as an integer
1195 except that the number (or its negative) takes more than 32 bits to
1196 represent in binary. The distinction is made because in some places
1197 integers are permitted while bignums are not.
1199 _if__(_I960__&&!_GENERIC__)
1200 @node Flonums, Bit Fields, Bignums, Numbers
1201 _fi__(_I960__&&!_GENERIC__)
1202 _if__(_GENERIC__||!_I960__)
1203 @node Flonums, , Bignums, Numbers
1204 _fi__(_GENERIC__||!_I960__)
1205 @subsubsection Flonums
1207 @cindex floating point numbers
1208 @cindex constants, floating point
1210 @cindex precision, floating point
1211 A @dfn{flonum} represents a floating point number. The translation is
1212 indirect: a decimal floating point number from the text is converted by
1213 @code{_AS__} to a generic binary floating point number of more than
1214 sufficient precision. This generic floating point number is converted
1215 to a particular computer's floating point format (or formats) by a
1216 portion of @code{_AS__} specialized to that computer.
1218 A flonum is written by writing (in order)
1223 A letter, to tell @code{_AS__} the rest of the number is a flonum.
1225 @kbd{e} is recommended. Case is not important.
1227 @c FIXME: verify if flonum syntax really this vague for most cases
1228 (Any otherwise illegal letter
1229 will work here, but that might be changed. Vax BSD 4.2 assembler seems
1230 to allow any of @samp{defghDEFGH}.)
1233 _if__(_A29K__||_H8__)
1235 On the AMD 29K and H8/300 architectures, the letter must be:
1237 One of the letters @samp{DFPRSX} (in upper or lower case).
1238 _fi__(_A29K__||_H8__)
1241 On the Intel 960 architecture, the letter must be:
1243 One of the letters @samp{DFT} (in upper or lower case).
1246 An optional sign: either @samp{+} or @samp{-}.
1248 An optional @dfn{integer part}: zero or more decimal digits.
1250 An optional @dfn{fractional part}: @samp{.} followed by zero
1251 or more decimal digits.
1253 An optional exponent, consisting of:
1256 An @samp{E} or @samp{e}.
1257 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1258 @c principle this can perfectly well be different on different targets.
1260 Optional sign: either @samp{+} or @samp{-}.
1262 One or more decimal digits.
1266 At least one of the integer part or the fractional part must be
1267 present. The floating point number has the usual base-10 value.
1269 @code{_AS__} does all processing using integers. Flonums are computed
1270 independently of any floating point hardware in the computer running
1273 _if__(_I960__&&!_GENERIC__)
1274 @c Bit fields are written as a general facility but are also controlled
1275 @c by a conditional-compilation flag---which is as of now (21mar91)
1276 @c turned on only by the i960 config of GAS.
1277 @node Bit Fields, , Flonums, Numbers
1278 @subsubsection Bit Fields
1281 @cindex constants, bit field
1282 You can also define numeric constants as @dfn{bit fields}.
1283 specify two numbers separated by a colon---
1285 @var{mask}:@var{value}
1288 the first will act as a mask; @code{_AS__} will bitwise-and it with the
1291 The resulting number is then packed
1293 @c this conditional paren in case bit fields turned on elsewhere than 960
1294 (in host-dependent byte order)
1296 into a field whose width depends on which assembler directive has the
1297 bit-field as its argument. Overflow (a result from the bitwise and
1298 requiring more binary digits to represent) is not an error; instead,
1299 more constants are generated, of the specified width, beginning with the
1300 least significant digits.@refill
1302 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1303 @code{.short}, and @code{.word} accept bit-field arguments.
1304 _fi__(_I960__&&!_GENERIC__)
1306 @node Sections, Symbols, Syntax, Top
1307 @chapter Sections and Relocation
1312 * Secs Background:: Background
1313 * _LD__ Sections:: _LD__ Sections
1314 * _AS__ Sections:: _AS__ Internal Sections
1315 * Sub-Sections:: Sub-Sections
1319 @node Secs Background, _LD__ Sections, Sections, Sections
1322 Roughly, a section is a range of addresses, with no gaps; all data
1323 ``in'' those addresses is treated the same for some particular purpose.
1324 For example there may be a ``read only'' section.
1326 @cindex linker, and assembler
1327 @cindex assembler, and linker
1328 The linker @code{_LD__} reads many object files (partial programs) and
1329 combines their contents to form a runnable program. When @code{_AS__}
1330 emits an object file, the partial program is assumed to start at address
1331 0. @code{_LD__} will assign the final addresses the partial program
1332 occupies, so that different partial programs don't overlap. This is
1333 actually an over-simplification, but it will suffice to explain how
1334 @code{_AS__} uses sections.
1336 @code{_LD__} moves blocks of bytes of your program to their run-time
1337 addresses. These blocks slide to their run-time addresses as rigid
1338 units; their length does not change and neither does the order of bytes
1339 within them. Such a rigid unit is called a @emph{section}. Assigning
1340 run-time addresses to sections is called @dfn{relocation}. It includes
1341 the task of adjusting mentions of object-file addresses so they refer to
1342 the proper run-time addresses.
1344 For the H8/300, @code{_AS__} pads sections if needed to ensure they end
1345 on a word (sixteen bit) boundary.
1348 @cindex standard @code{_AS__} sections
1349 An object file written by @code{_AS__} has at least three sections, any
1350 of which may be empty. These are named @dfn{text}, @dfn{data} and
1355 When it generates COFF output,
1357 @code{_AS__} can also generate whatever other named sections you specify
1358 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1359 If you don't use any directives that place output in the @samp{.text}
1360 or @samp{.data} sections, these sections will still exist, but will be empty.
1363 Within the object file, the text section starts at address @code{0}, the
1364 data section follows, and the bss section follows the data section.
1366 To let @code{_LD__} know which data will change when the sections are
1367 relocated, and how to change that data, @code{_AS__} also writes to the
1368 object file details of the relocation needed. To perform relocation
1369 @code{_LD__} must know, each time an address in the object
1373 Where in the object file is the beginning of this reference to
1376 How long (in bytes) is this reference?
1378 Which section does the address refer to? What is the numeric value of
1380 (@var{address}) @minus{} (@var{start-address of section})?
1383 Is the reference to an address ``Program-Counter relative''?
1386 @cindex addresses, format of
1387 @cindex section-relative addressing
1388 In fact, every address @code{_AS__} ever uses is expressed as
1390 (@var{section}) + (@var{offset into section})
1393 Further, every expression @code{_AS__} computes is of this section-relative
1394 nature. @dfn{Absolute expression} means an expression with section
1395 ``absolute'' (@pxref{_LD__ Sections}). A @dfn{pass1 expression} means
1396 an expression with section ``pass1'' (@pxref{_AS__ Sections,,_AS__
1397 Internal Sections}). In this manual we use the notation @{@var{secname}
1398 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1400 Apart from text, data and bss sections you need to know about the
1401 @dfn{absolute} section. When @code{_LD__} mixes partial programs,
1402 addresses in the absolute section remain unchanged. For example, address
1403 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}.
1404 Although two partial programs' data sections will not overlap addresses
1405 after linking, @emph{by definition} their absolute sections will overlap.
1406 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1407 address when the program is running as address @code{@{absolute@ 239@}} in any
1408 other partial program.
1410 The idea of sections is extended to the @dfn{undefined} section. Any
1411 address whose section is unknown at assembly time is by definition
1412 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1413 Since numbers are always defined, the only way to generate an undefined
1414 address is to mention an undefined symbol. A reference to a named
1415 common block would be such a symbol: its value is unknown at assembly
1416 time so it has section @emph{undefined}.
1418 By analogy the word @emph{section} is used to describe groups of sections in
1419 the linked program. @code{_LD__} puts all partial programs' text
1420 sections in contiguous addresses in the linked program. It is
1421 customary to refer to the @emph{text section} of a program, meaning all
1422 the addresses of all partial program's text sections. Likewise for
1423 data and bss sections.
1425 Some sections are manipulated by @code{_LD__}; others are invented for
1426 use of @code{_AS__} and have no meaning except during assembly.
1428 @node _LD__ Sections, _AS__ Sections, Secs Background, Sections
1429 @section _LD__ Sections
1430 @code{_LD__} deals with just four kinds of sections, summarized below.
1434 _if__(_GENERIC__||_COFF__)
1435 @cindex named sections
1436 @cindex sections, named
1437 @item named sections
1438 _fi__(_GENERIC__||_COFF__)
1439 _if__(_AOUT__||_BOUT__)
1440 @cindex text section
1441 @cindex data section
1444 _fi__(_AOUT__||_BOUT__)
1445 These sections hold your program. @code{_AS__} and @code{_LD__} treat them as
1446 separate but equal sections. Anything you can say of one section is
1448 _if__(_AOUT__||_BOUT__)
1449 When the program is running, however, it is
1450 customary for the text section to be unalterable. The
1451 text section is often shared among processes: it will contain
1452 instructions, constants and the like. The data section of a running
1453 program is usually alterable: for example, C variables would be stored
1454 in the data section.
1455 _fi__(_AOUT__||_BOUT__)
1459 This section contains zeroed bytes when your program begins running. It
1460 is used to hold unitialized variables or common storage. The length of
1461 each partial program's bss section is important, but because it starts
1462 out containing zeroed bytes there is no need to store explicit zero
1463 bytes in the object file. The bss section was invented to eliminate
1464 those explicit zeros from object files.
1466 @cindex absolute section
1467 @item absolute section
1468 Address 0 of this section is always ``relocated'' to runtime address 0.
1469 This is useful if you want to refer to an address that @code{_LD__} must
1470 not change when relocating. In this sense we speak of absolute
1471 addresses being ``unrelocatable'': they don't change during relocation.
1473 @cindex undefined section
1474 @item undefined section
1475 This ``section'' is a catch-all for address references to objects not in
1476 the preceding sections.
1477 @c FIXME: ref to some other doc on obj-file formats could go here.
1480 @cindex relocation example
1481 An idealized example of three relocatable sections follows.
1483 The example uses the traditional section names @samp{.text} and @samp{.data}.
1485 Memory addresses are on the horizontal axis.
1489 @c END TEXI2ROFF-KILL
1492 partial program # 1: |ttttt|dddd|00|
1499 partial program # 2: |TTT|DDD|000|
1502 +--+---+-----+--+----+---+-----+~~
1503 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1504 +--+---+-----+--+----+---+-----+~~
1506 addresses: 0 @dots{}
1510 @c FIXME make sure no page breaks inside figure!!
1513 \line{\it Partial program \#1: \hfil}
1514 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1515 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1517 \line{\it Partial program \#2: \hfil}
1518 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1519 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1521 \line{\it linked program: \hfil}
1522 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1523 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1524 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1525 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1527 \line{\it addresses: \hfil}
1531 @c END TEXI2ROFF-KILL
1533 @node _AS__ Sections, Sub-Sections, _LD__ Sections, Sections
1534 @section _AS__ Internal Sections
1536 @cindex internal @code{_AS__} sections
1537 @cindex sections in messages, internal
1538 These sections are meant only for the internal use of @code{_AS__}. They
1539 have no meaning at run-time. You don't really need to know about these
1540 sections for most purposes; but they can be mentioned in @code{_AS__}
1541 warning messages, so it might be helpful to have an idea of their
1542 meanings to @code{_AS__}. These sections are used to permit the
1543 value of every expression in your assembly language program to be a
1544 section-relative address.
1548 @cindex absent (internal section)
1549 An expression was expected and none was found.
1551 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1552 @cindex assembler internal logic error
1553 An internal assembler logic error has been found. This means there is a
1554 bug in the assembler.
1557 @cindex bignum/flonum (internal section)
1558 If a number can't be written as a C @code{int} constant (a bignum or a
1559 flonum, but not an integer), it is recorded as belonging to this
1560 ``section''. @code{_AS__} has to remember that a flonum or a bignum
1561 does not fit into 32 bits, and cannot be an argument (@pxref{Arguments})
1562 in an expression: this is done by making a flonum or bignum be in a
1563 separate internal section. This is purely for internal @code{_AS__}
1564 convenience; bignum/flonum section behaves similarly to absolute
1568 @cindex pass1 (internal section)
1569 The expression was impossible to evaluate in the first pass. The
1570 assembler will attempt a second pass (second reading of the source) to
1571 evaluate the expression. Your expression mentioned an undefined symbol
1572 in a way that defies the one-pass (section + offset in section) assembly
1573 process. No compiler need emit such an expression.
1576 @emph{Warning:} the second pass is currently not implemented. @code{_AS__}
1577 will abort with an error message if one is required.
1580 @item difference section
1581 @cindex difference (internal section)
1582 As an assist to the C compiler, expressions of the forms
1584 (@var{undefined symbol}) @minus{} (@var{expression})
1585 @var{something} @minus{} (@var{undefined symbol})
1586 (@var{undefined symbol}) @minus{} (@var{undefined symbol})
1589 are permitted, and belong to the difference section. @code{_AS__}
1590 re-evaluates such expressions after the source file has been read and
1591 the symbol table built. If by that time there are no undefined symbols
1592 in the expression then the expression assumes a new section. The
1593 intention is to permit statements like
1594 @samp{.word label - base_of_table}
1595 to be assembled in one pass where both @code{label} and
1596 @code{base_of_table} are undefined. This is useful for compiling C and
1597 Algol switch statements, Pascal case statements, FORTRAN computed goto
1598 statements and the like.
1600 @c FIXME item transfer[t] vector preload
1601 @c FIXME item transfer[t] vector postload
1602 @c FIXME item register
1605 @node Sub-Sections, bss, _AS__ Sections, Sections
1606 @section Sub-Sections
1608 @cindex numbered subsections
1609 @cindex grouping data
1610 _if__(_AOUT__||_BOUT__)
1615 fall into two sections: text and data.
1616 _fi__(_AOUT__||_BOUT__)
1617 You may have separate groups of
1618 _if__(_COFF__||_GENERIC__)
1619 data in named sections
1620 _fi__(_COFF__||_GENERIC__)
1621 _if__((_AOUT__||_BOUT__)&&!_GENERIC__)
1623 _fi__((_AOUT__||_BOUT__)&&!_GENERIC__)
1624 that you want to end up near to each other in the object
1625 file, even though they are not contiguous in the assembler source.
1626 @code{_AS__} allows you to use @dfn{subsections} for this purpose.
1627 Within each section, there can be numbered subsections with
1628 values from 0 to 8192. Objects assembled into the same subsection will
1629 be grouped with other objects in the same subsection when they are all
1630 put into the object file. For example, a compiler might want to store
1631 constants in the text section, but might not want to have them
1632 interspersed with the program being assembled. In this case, the
1633 compiler could issue a @samp{.text 0} before each section of code being
1634 output, and a @samp{.text 1} before each group of constants being output.
1636 Subsections are optional. If you don't use subsections, everything
1637 will be stored in subsection number zero.
1640 Each subsection is zero-padded up to a multiple of four bytes.
1641 (Subsections may be padded a different amount on different flavors
1646 On the H8/300 platform, each subsection is zero-padded to a word
1647 boundary (two bytes).
1650 @c FIXME section padding (alignment)?
1651 @c Rich Pixley says padding here depends on target obj code format; that
1652 @c doesn't seem particularly useful to say without further elaboration,
1653 @c so for now I say nothing about it. If this is a generic BFD issue,
1654 @c these paragraphs might need to vanish from this manual, and be
1655 @c discussed in BFD chapter of binutils (or some such).
1658 On the AMD 29K family, no particular padding is added to section or
1659 subsection sizes; _AS__ forces no alignment on this platform.
1663 Subsections appear in your object file in numeric order, lowest numbered
1664 to highest. (All this to be compatible with other people's assemblers.)
1665 The object file contains no representation of subsections; @code{_LD__} and
1666 other programs that manipulate object files will see no trace of them.
1667 They just see all your text subsections as a text section, and all your
1668 data subsections as a data section.
1670 To specify which subsection you want subsequent statements assembled
1671 into, use a numeric argument to specify it, in a @samp{.text
1672 @var{expression}} or a @samp{.data @var{expression}} statement.
1675 When generating COFF output, you
1680 can also use an extra subsection
1681 argument with arbitrary named sections: @samp{.section @var{name},
1684 @var{Expression} should be an absolute expression.
1685 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
1686 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
1687 begins in @code{text 0}. For instance:
1689 .text 0 # The default subsection is text 0 anyway.
1690 .ascii "This lives in the first text subsection. *"
1692 .ascii "But this lives in the second text subsection."
1694 .ascii "This lives in the data section,"
1695 .ascii "in the first data subsection."
1697 .ascii "This lives in the first text section,"
1698 .ascii "immediately following the asterisk (*)."
1701 Each section has a @dfn{location counter} incremented by one for every
1702 byte assembled into that section. Because subsections are merely a
1703 convenience restricted to @code{_AS__} there is no concept of a subsection
1704 location counter. There is no way to directly manipulate a location
1705 counter---but the @code{.align} directive will change it, and any label
1706 definition will capture its current value. The location counter of the
1707 section that statements are being assembled into is said to be the
1708 @dfn{active} location counter.
1710 @node bss, , Sub-Sections, Sections
1711 @section bss Section
1714 @cindex common variable storage
1715 The bss section is used for local common variable storage.
1716 You may allocate address space in the bss section, but you may
1717 not dictate data to load into it before your program executes. When
1718 your program starts running, all the contents of the bss
1719 section are zeroed bytes.
1721 Addresses in the bss section are allocated with special directives; you
1722 may not assemble anything directly into the bss section. Hence there
1723 are no bss subsections. @xref{Comm,,@code{.comm}},
1724 @pxref{Lcomm,,@code{.lcomm}}.
1726 @node Symbols, Expressions, Sections, Top
1730 Symbols are a central concept: the programmer uses symbols to name
1731 things, the linker uses symbols to link, and the debugger uses symbols
1735 @cindex debuggers, and symbol order
1736 @emph{Warning:} @code{_AS__} does not place symbols in the object file in
1737 the same order they were declared. This may break some debuggers.
1742 * Setting Symbols:: Giving Symbols Other Values
1743 * Symbol Names:: Symbol Names
1744 * Dot:: The Special Dot Symbol
1745 * Symbol Attributes:: Symbol Attributes
1748 @node Labels, Setting Symbols, Symbols, Symbols
1752 A @dfn{label} is written as a symbol immediately followed by a colon
1753 @samp{:}. The symbol then represents the current value of the
1754 active location counter, and is, for example, a suitable instruction
1755 operand. You are warned if you use the same symbol to represent two
1756 different locations: the first definition overrides any other
1759 @node Setting Symbols, Symbol Names, Labels, Symbols
1760 @section Giving Symbols Other Values
1762 @cindex assigning values to symbols
1763 @cindex symbol values, assigning
1764 A symbol can be given an arbitrary value by writing a symbol, followed
1765 by an equals sign @samp{=}, followed by an expression
1766 (@pxref{Expressions}). This is equivalent to using the @code{.set}
1767 directive. @xref{Set,,@code{.set}}.
1769 @node Symbol Names, Dot, Setting Symbols, Symbols
1770 @section Symbol Names
1772 @cindex symbol names
1773 @cindex names, symbol
1774 Symbol names begin with a letter or with one of
1781 (On most machines, you can also use @code{$} in symbol names; exceptions
1782 are noted in @ref{_MACH_DEP__}.)
1785 That character may be followed by any string of digits, letters,
1787 underscores and dollar signs.
1791 dollar signs (unless otherwise noted in @ref{_MACH_DEP__}),
1795 Case of letters is significant:
1796 @code{foo} is a different symbol name than @code{Foo}.
1799 For the AMD 29K family, @samp{?} is also allowed in the
1800 body of a symbol name, though not at its beginning.
1803 Each symbol has exactly one name. Each name in an assembly language
1804 program refers to exactly one symbol. You may use that symbol name any
1805 number of times in a program.
1807 @subheading Local Symbol Names
1809 @cindex local symbol names
1810 @cindex symbol names, local
1811 @cindex temporary symbol names
1812 @cindex symbol names, temporary
1813 Local symbols help compilers and programmers use names temporarily.
1814 There are ten local symbol names, which are re-used throughout the
1815 program. You may refer to them using the names @samp{0} @samp{1}
1816 @dots{} @samp{9}. To define a local symbol, write a label of the form
1817 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
1818 recent previous definition of that symbol write @samp{@b{N}b}, using the
1819 same digit as when you defined the label. To refer to the next
1820 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
1821 a choice of 10 forward references. The @samp{b} stands for
1822 ``backwards'' and the @samp{f} stands for ``forwards''.
1824 Local symbols are not emitted by the current GNU C compiler.
1826 There is no restriction on how you can use these labels, but
1827 remember that at any point in the assembly you can refer to at most
1828 10 prior local labels and to at most 10 forward local labels.
1830 Local symbol names are only a notation device. They are immediately
1831 transformed into more conventional symbol names before the assembler
1832 uses them. The symbol names stored in the symbol table, appearing in
1833 error messages and optionally emitted to the object file have these
1838 All local labels begin with @samp{L}. Normally both @code{_AS__} and
1839 @code{_LD__} forget symbols that start with @samp{L}. These labels are
1840 used for symbols you are never intended to see. If you give the
1841 @samp{-L} option then @code{_AS__} will retain these symbols in the
1842 object file. If you also instruct @code{_LD__} to retain these symbols,
1843 you may use them in debugging.
1846 If the label is written @samp{0:} then the digit is @samp{0}.
1847 If the label is written @samp{1:} then the digit is @samp{1}.
1848 And so on up through @samp{9:}.
1851 This unusual character is included so you don't accidentally invent
1852 a symbol of the same name. The character has ASCII value
1855 @item @emph{ordinal number}
1856 This is a serial number to keep the labels distinct. The first
1857 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
1858 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
1862 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
1863 @code{3:} is named @code{L3@ctrl{A}44}.
1865 @node Dot, Symbol Attributes, Symbol Names, Symbols
1866 @section The Special Dot Symbol
1868 @cindex dot (symbol)
1869 @cindex @code{.} (symbol)
1870 @cindex current address
1871 @cindex location counter
1872 The special symbol @samp{.} refers to the current address that
1873 @code{_AS__} is assembling into. Thus, the expression @samp{melvin:
1874 .long .} will cause @code{melvin} to contain its own address.
1875 Assigning a value to @code{.} is treated the same as a @code{.org}
1876 directive. Thus, the expression @samp{.=.+4} is the same as saying
1884 @node Symbol Attributes, , Dot, Symbols
1885 @section Symbol Attributes
1887 @cindex symbol attributes
1888 @cindex attributes, symbol
1889 Every symbol has, as well as its name, the attributes ``Value'' and
1890 ``Type''. Depending on output format, symbols can also have auxiliary
1893 The detailed definitions are in _0__<a.out.h>_1__.
1896 If you use a symbol without defining it, @code{_AS__} assumes zero for
1897 all these attributes, and probably won't warn you. This makes the
1898 symbol an externally defined symbol, which is generally what you
1902 * Symbol Value:: Value
1903 * Symbol Type:: Type
1904 _if__(_AOUT__||_BOUT__)
1905 _if__(_GENERIC__||!_BOUT__)
1906 * a.out Symbols:: Symbol Attributes: @code{a.out}
1907 _fi__(_GENERIC__||!_BOUT__)
1908 _if__(_BOUT__&&!_GENERIC__)
1909 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
1910 _fi__(_BOUT__&&!_GENERIC__)
1911 _fi__(_AOUT__||_BOUT__)
1913 * COFF Symbols:: Symbol Attributes for COFF
1917 @node Symbol Value, Symbol Type, Symbol Attributes, Symbol Attributes
1920 @cindex value of a symbol
1921 @cindex symbol value
1922 The value of a symbol is (usually) 32 bits. For a symbol which labels a
1923 location in the text, data, bss or absolute sections the value is the
1924 number of addresses from the start of that section to the label.
1925 Naturally for text, data and bss sections the value of a symbol changes
1926 as @code{_LD__} changes section base addresses during linking. Absolute
1927 symbols' values do not change during linking: that is why they are
1930 The value of an undefined symbol is treated in a special way. If it is
1931 0 then the symbol is not defined in this assembler source program, and
1932 @code{_LD__} will try to determine its value from other programs it is
1933 linked with. You make this kind of symbol simply by mentioning a symbol
1934 name without defining it. A non-zero value represents a @code{.comm}
1935 common declaration. The value is how much common storage to reserve, in
1936 bytes (addresses). The symbol refers to the first address of the
1939 _if__(!(_AOUT__||_BOUT__))
1940 @node Symbol Type, COFF Symbols, Symbol Value, Symbol Attributes
1941 _fi__(!(_AOUT__||_BOUT__))
1942 _if__((_AOUT__||_BOUT__))
1943 @node Symbol Type, a.out Symbols, Symbol Value, Symbol Attributes
1944 _fi__((_AOUT__||_BOUT__))
1947 @cindex type of a symbol
1949 The type attribute of a symbol contains relocation (section)
1950 information, any flag settings indicating that a symbol is external, and
1951 (optionally), other information for linkers and debuggers. The exact
1952 format depends on the object-code output format in use.
1954 _if__(_AOUT__||_BOUT__)
1956 @node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes
1959 @node a.out Symbols, , Symbol Type, Symbol Attributes
1961 _if__(_BOUT__&&!_GENERIC__)
1962 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
1964 @cindex @code{b.out} symbol attributes
1965 @cindex symbol attributes, @code{b.out}
1966 These symbol attributes appear only when @code{_AS__} is configured for
1967 one of the Berkeley-descended object output formats.
1968 _fi__(_BOUT__&&!_GENERIC__)
1969 _if__(_GENERIC__||!_BOUT__)
1970 @subsection Symbol Attributes: @code{a.out}
1971 _fi__(_GENERIC__||!_BOUT__)
1973 @cindex @code{a.out} symbol attributes
1974 @cindex symbol attributes, @code{a.out}
1977 * Symbol Desc:: Descriptor
1978 * Symbol Other:: Other
1981 @node Symbol Desc, Symbol Other, a.out Symbols, a.out Symbols
1982 @subsubsection Descriptor
1984 @cindex descriptor, of @code{a.out} symbol
1985 This is an arbitrary 16-bit value. You may establish a symbol's
1986 descriptor value by using a @code{.desc} statement
1987 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
1990 @node Symbol Other, , Symbol Desc, a.out Symbols
1991 @subsubsection Other
1993 @cindex other attribute, of @code{a.out} symbol
1994 This is an arbitrary 8-bit value. It means nothing to @code{_AS__}.
1995 _fi__(_AOUT__||_BOUT__)
1998 _if__(!(_AOUT__||_BOUT__))
1999 @node COFF Symbols, , Symbol Type, Symbol Attributes
2000 _fi__(!(_AOUT__||_BOUT__))
2001 _if__(_AOUT__||_BOUT__)
2002 @node COFF Symbols, , a.out Symbols, Symbol Attributes
2003 _fi__(_AOUT__||_BOUT__)
2004 @subsection Symbol Attributes for COFF
2006 @cindex COFF symbol attributes
2007 @cindex symbol attributes, COFF
2009 The COFF format supports a multitude of auxiliary symbol attributes;
2010 like the primary symbol attributes, they are set between @code{.def} and
2011 @code{.endef} directives.
2013 @subsubsection Primary Attributes
2015 @cindex primary attributes, COFF symbols
2016 The symbol name is set with @code{.def}; the value and type,
2017 respectively, with @code{.val} and @code{.type}.
2019 @subsubsection Auxiliary Attributes
2021 @cindex auxiliary attributes, COFF symbols
2022 The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl},
2023 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2024 information for COFF.
2027 @node Expressions, Pseudo Ops, Symbols, Top
2028 @chapter Expressions
2032 @cindex numeric values
2033 An @dfn{expression} specifies an address or numeric value.
2034 Whitespace may precede and/or follow an expression.
2037 * Empty Exprs:: Empty Expressions
2038 * Integer Exprs:: Integer Expressions
2041 @node Empty Exprs, Integer Exprs, Expressions, Expressions
2042 @section Empty Expressions
2044 @cindex empty expressions
2045 @cindex expressions, empty
2046 An empty expression has no value: it is just whitespace or null.
2047 Wherever an absolute expression is required, you may omit the
2048 expression and @code{_AS__} will assume a value of (absolute) 0. This
2049 is compatible with other assemblers.
2051 @node Integer Exprs, , Empty Exprs, Expressions
2052 @section Integer Expressions
2054 @cindex integer expressions
2055 @cindex expressions, integer
2056 An @dfn{integer expression} is one or more @emph{arguments} delimited
2057 by @emph{operators}.
2060 * Arguments:: Arguments
2061 * Operators:: Operators
2062 * Prefix Ops:: Prefix Operators
2063 * Infix Ops:: Infix Operators
2066 @node Arguments, Operators, Integer Exprs, Integer Exprs
2067 @subsection Arguments
2069 @cindex expression arguments
2070 @cindex arguments in expressions
2071 @cindex operands in expressions
2072 @cindex arithmetic operands
2073 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2074 contexts arguments are sometimes called ``arithmetic operands''. In
2075 this manual, to avoid confusing them with the ``instruction operands'' of
2076 the machine language, we use the term ``argument'' to refer to parts of
2077 expressions only, reserving the word ``operand'' to refer only to machine
2078 instruction operands.
2080 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2081 @var{section} is one of text, data, bss, absolute,
2082 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2085 Numbers are usually integers.
2087 A number can be a flonum or bignum. In this case, you are warned
2088 that only the low order 32 bits are used, and @code{_AS__} pretends
2089 these 32 bits are an integer. You may write integer-manipulating
2090 instructions that act on exotic constants, compatible with other
2093 @cindex subexpressions
2094 Subexpressions are a left parenthesis @samp{(} followed by an integer
2095 expression, followed by a right parenthesis @samp{)}; or a prefix
2096 operator followed by an argument.
2098 @node Operators, Prefix Ops, Arguments, Integer Exprs
2099 @subsection Operators
2101 @cindex operators, in expressions
2102 @cindex arithmetic functions
2103 @cindex functions, in expressions
2104 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2105 operators are followed by an argument. Infix operators appear
2106 between their arguments. Operators may be preceded and/or followed by
2109 @node Prefix Ops, Infix Ops, Operators, Integer Exprs
2110 @subsection Prefix Operator
2112 @cindex prefix operators
2113 @code{_AS__} has the following @dfn{prefix operators}. They each take
2114 one argument, which must be absolute.
2116 @c the tex/end tex stuff surrounding this small table is meant to make
2117 @c it align, on the printed page, with the similar table in the next
2118 @c section (which is inside an enumerate).
2120 \global\advance\leftskip by \itemindent
2125 @dfn{Negation}. Two's complement negation.
2127 @dfn{Complementation}. Bitwise not.
2131 \global\advance\leftskip by -\itemindent
2134 @node Infix Ops, , Prefix Ops, Integer Exprs
2135 @subsection Infix Operators
2137 @cindex infix operators
2138 @cindex operators, permitted arguments
2139 @dfn{Infix operators} take two arguments, one on either side. Operators
2140 have precedence, but operations with equal precedence are performed left
2141 to right. Apart from @code{+} or @code{-}, both arguments must be
2142 absolute, and the result is absolute.
2145 @cindex operator precedence
2146 @cindex precedence of operators
2153 @dfn{Multiplication}.
2156 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2163 @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__}
2167 @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__}
2171 Intermediate precedence
2176 @dfn{Bitwise Inclusive Or}.
2182 @dfn{Bitwise Exclusive Or}.
2185 @dfn{Bitwise Or Not}.
2193 @cindex addition, permitted arguments
2194 @cindex plus, permitted arguments
2195 @cindex arguments for addition
2196 @dfn{Addition}. If either argument is absolute, the result
2197 has the section of the other argument.
2198 If either argument is pass1 or undefined, the result is pass1.
2199 Otherwise @code{+} is illegal.
2202 @cindex subtraction, permitted arguments
2203 @cindex minus, permitted arguments
2204 @cindex arguments for subtraction
2205 @dfn{Subtraction}. If the right argument is absolute, the
2206 result has the section of the left argument.
2207 If either argument is pass1 the result is pass1.
2208 If either argument is undefined the result is difference section.
2209 If both arguments are in the same section, the result is absolute---provided
2210 that section is one of text, data or bss.
2211 Otherwise subtraction is illegal.
2215 The sense of the rule for addition is that it's only meaningful to add
2216 the @emph{offsets} in an address; you can only have a defined section in
2217 one of the two arguments.
2219 Similarly, you can't subtract quantities from two different sections.
2221 @node Pseudo Ops, _MACH_DEP__, Expressions, Top
2222 @chapter Assembler Directives
2224 @cindex directives, machine independent
2225 @cindex pseudo-ops, machine independent
2226 @cindex machine independent directives
2227 All assembler directives have names that begin with a period (@samp{.}).
2228 The rest of the name is letters, usually in lower case.
2230 This chapter discusses directives present regardless of the target
2231 machine configuration for the GNU assembler.
2233 @xref{_MACH_DEP__} for additional directives.
2237 * Abort:: @code{.abort}
2239 * coff-ABORT:: @code{.ABORT}
2241 _if__(_BOUT__&&!_COFF__)
2242 * bout-ABORT:: @code{.ABORT}
2243 _fi__(_BOUT__&&!_COFF__)
2244 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2245 * App-File:: @code{.app-file @var{string}}
2246 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2247 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2248 * Byte:: @code{.byte @var{expressions}}
2249 * Comm:: @code{.comm @var{symbol} , @var{length} }
2250 * Data:: @code{.data @var{subsection}}
2251 _if__(_COFF__||_BOUT__)
2252 * Def:: @code{.def @var{name}}
2253 _fi__(_COFF__||_BOUT__)
2254 _if__(_AOUT__||_BOUT__)
2255 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2256 _fi__(_AOUT__||_BOUT__)
2257 _if__(_COFF__||_BOUT__)
2259 _fi__(_COFF__||_BOUT__)
2260 * Double:: @code{.double @var{flonums}}
2261 * Eject:: @code{.eject}
2262 * Else:: @code{.else}
2263 _if__(_COFF__||_BOUT__)
2264 * Endef:: @code{.endef}
2265 _fi__(_COFF__||_BOUT__)
2266 * Endif:: @code{.endif}
2267 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2268 * Extern:: @code{.extern}
2269 _if__(_GENERIC__||!_A29K__)
2270 * File:: @code{.file @var{string}}
2271 _fi__(_GENERIC__||!_A29K__)
2272 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2273 * Float:: @code{.float @var{flonums}}
2274 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2275 * hword:: @code{.hword @var{expressions}}
2276 * Ident:: @code{.ident}
2277 * If:: @code{.if @var{absolute expression}}
2278 * Include:: @code{.include "@var{file}"}
2279 * Int:: @code{.int @var{expressions}}
2280 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2281 * Lflags:: @code{.lflags}
2282 _if__(_GENERIC__||!_A29K__)
2283 * Line:: @code{.line @var{line-number}}
2284 _fi__(_GENERIC__||!_A29K__)
2285 * Ln:: @code{.ln @var{line-number}}
2286 * List:: @code{.list}
2287 * Long:: @code{.long @var{expressions}}
2288 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2289 * Nolist:: @code{.nolist}
2290 * Octa:: @code{.octa @var{bignums}}
2291 * Org:: @code{.org @var{new-lc} , @var{fill}}
2292 * Psize:: @code{.psize @var{lines}, @var{columns}}
2293 * Quad:: @code{.quad @var{bignums}}
2294 * Sbttl:: @code{.sbttl "@var{subheading}"}
2295 _if__(_COFF__||_BOUT__)
2296 * Scl:: @code{.scl @var{class}}
2297 _fi__(_COFF__||_BOUT__)
2299 * Section:: @code{.section @var{name}, @var{subsection}}
2301 * Set:: @code{.set @var{symbol}, @var{expression}}
2302 * Short:: @code{.short @var{expressions}}
2303 * Single:: @code{.single @var{flonums}}
2304 _if__(_COFF__||_BOUT__)
2305 * Size:: @code{.size}
2306 _fi__(_COFF__||_BOUT__)
2307 * Space:: @code{.space @var{size} , @var{fill}}
2308 _if__(_GENERIC__||!_H8__)
2309 * Stab:: @code{.stabd, .stabn, .stabs}
2310 _fi__(_GENERIC__||!_H8__)
2311 _if__(_COFF__||_BOUT__)
2312 * Tag:: @code{.tag @var{structname}}
2313 _fi__(_COFF__||_BOUT__)
2314 * Text:: @code{.text @var{subsection}}
2315 * Title:: @code{.title "@var{heading}"}
2316 _if__(_COFF__||_BOUT__)
2317 * Type:: @code{.type @var{int}}
2318 * Val:: @code{.val @var{addr}}
2319 _fi__(_COFF__||_BOUT__)
2320 * Word:: @code{.word @var{expressions}}
2321 * Deprecated:: Deprecated Directives
2325 @node Abort, coff-ABORT, Pseudo Ops, Pseudo Ops
2327 _if__((!_COFF__) && _BOUT__)
2328 @node Abort, bout-ABORT, Pseudo Ops, Pseudo Ops
2329 _fi__((!_COFF__) && _BOUT__)
2330 _if__(! (_BOUT__ || _COFF__) )
2331 @node Abort, Align, Pseudo Ops, Pseudo Ops
2332 _fi__(! (_BOUT__ || _COFF__) )
2333 @section @code{.abort}
2335 @cindex @code{abort} directive
2336 @cindex stopping the assembly
2337 This directive stops the assembly immediately. It is for
2338 compatibility with other assemblers. The original idea was that the
2339 assembly language source would be piped into the assembler. If the sender
2340 of the source quit, it could use this directive tells @code{_AS__} to
2341 quit also. One day @code{.abort} will not be supported.
2344 @node coff-ABORT, Align, Abort, Pseudo Ops
2345 @section @code{.ABORT}
2347 @cindex @code{ABORT} directive
2348 When producing COFF output, @code{_AS__} accepts this directive as a
2349 synonym for @samp{.abort}.
2354 @node bout-ABORT, Align, Abort, Pseudo Ops
2355 @section @code{.ABORT}
2357 @cindex @code{ABORT} directive
2360 When producing @code{b.out} output, @code{_AS__} accepts this directive,
2364 _if__( ! (_COFF__ || _BOUT__) )
2365 @node Align, App-File, Abort, Pseudo Ops
2366 _fi__( ! (_COFF__ || _BOUT__) )
2368 @node Align, App-File, coff-ABORT, Pseudo Ops
2370 _if__( _BOUT__ && (! _COFF__))
2371 @node Align, App-File, bout-ABORT, Pseudo Ops
2372 _fi__( _BOUT__ && (! _COFF__))
2373 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2375 @cindex padding the location counter
2376 @cindex @code{align} directive
2377 Pad the location counter (in the current subsection) to a particular
2378 storage boundary. The first expression (which must be absolute) is the
2379 number of low-order zero bits the location counter will have after
2380 advancement. For example @samp{.align 3} will advance the location
2381 counter until it a multiple of 8. If the location counter is already a
2382 multiple of 8, no change is needed.
2384 The second expression (also absolute) gives the value to be stored in
2385 the padding bytes. It (and the comma) may be omitted. If it is
2386 omitted, the padding bytes are zero.
2388 @node App-File, Ascii, Align, Pseudo Ops
2389 @section @code{.app-file @var{string}}
2391 @cindex logical file name
2392 @cindex file name, logical
2393 @cindex @code{app-file} directive
2396 (which may also be spelled @samp{.file})
2398 tells @code{_AS__} that we are about to start a new
2399 logical file. @var{string} is the new file name. In general, the
2400 filename is recognized whether or not it is surrounded by quotes @samp{"};
2401 but if you wish to specify an empty file name is permitted,
2402 you must give the quotes--@code{""}. This statement may go away in
2403 future: it is only recognized to be compatible with old @code{_AS__}
2406 @node Ascii, Asciz, App-File, Pseudo Ops
2407 @section @code{.ascii "@var{string}"}@dots{}
2409 @cindex @code{ascii} directive
2410 @cindex string literals
2411 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2412 separated by commas. It assembles each string (with no automatic
2413 trailing zero byte) into consecutive addresses.
2415 @node Asciz, Byte, Ascii, Pseudo Ops
2416 @section @code{.asciz "@var{string}"}@dots{}
2418 @cindex @code{asciz} directive
2419 @cindex zero-terminated strings
2420 @cindex null-terminated strings
2421 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2422 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2424 @node Byte, Comm, Asciz, Pseudo Ops
2425 @section @code{.byte @var{expressions}}
2427 @cindex @code{byte} directive
2428 @cindex integers, one byte
2429 @code{.byte} expects zero or more expressions, separated by commas.
2430 Each expression is assembled into the next byte.
2432 @node Comm, Data, Byte, Pseudo Ops
2433 @section @code{.comm @var{symbol} , @var{length} }
2435 @cindex @code{comm} directive
2436 @cindex symbol, common
2437 @code{.comm} declares a named common area in the bss section. Normally
2438 @code{_LD__} reserves memory addresses for it during linking, so no partial
2439 program defines the location of the symbol. Use @code{.comm} to tell
2440 @code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__}
2441 will allocate space for each @code{.comm} symbol that is at least as
2442 long as the longest @code{.comm} request in any of the partial programs
2443 linked. @var{length} is an absolute expression.
2445 _if__(_COFF__ || _BOUT__)
2446 @node Data, Def, Comm, Pseudo Ops
2447 _fi__(_COFF__ || _BOUT__)
2448 _if__(!(_COFF__ || _BOUT__) && _AOUT__)
2449 @node Data, Desc, Comm, Pseudo Ops
2450 _fi__(!(_COFF__ || _BOUT__) && _AOUT__)
2451 _if__(! (_COFF__ || _BOUT__ || _AOUT__) )
2452 @c Well, this *might* happen...
2453 @node Data, Double, Comm, Pseudo Ops
2454 _fi__(! (_COFF__ || _BOUT__ || _AOUT__) )
2455 @section @code{.data @var{subsection}}
2457 @cindex @code{data} directive
2458 @code{.data} tells @code{_AS__} to assemble the following statements onto the
2459 end of the data subsection numbered @var{subsection} (which is an
2460 absolute expression). If @var{subsection} is omitted, it defaults
2463 _if__(_COFF__ || _BOUT__)
2464 _if__(_AOUT__ || _BOUT__)
2465 @node Def, Desc, Data, Pseudo Ops
2466 _fi__(_AOUT__ || _BOUT__)
2467 _if__(!(_AOUT__ || _BOUT__))
2468 @node Def, Dim, Data, Pseudo Ops
2469 _fi__(!(_AOUT__ || _BOUT__))
2470 @section @code{.def @var{name}}
2472 @cindex @code{def} directive
2473 @cindex COFF symbols, debugging
2474 @cindex debugging COFF symbols
2475 Begin defining debugging information for a symbol @var{name}; the
2476 definition extends until the @code{.endef} directive is encountered.
2479 This directive is only observed when @code{_AS__} is configured for COFF
2480 format output; when producing @code{b.out}, @samp{.def} is recognized,
2483 _fi__(_COFF__ || _BOUT__)
2485 _if__(_AOUT__||_BOUT__)
2486 _if__(_COFF__||_BOUT__)
2487 @node Desc, Dim, Def, Pseudo Ops
2488 _fi__(_COFF__||_BOUT__)
2489 _if__(!(_COFF__||_BOUT__))
2490 @node Desc, Double, Data, Pseudo Ops
2491 _fi__(!(_COFF__||_BOUT__))
2492 @section @code{.desc @var{symbol}, @var{abs-expression}}
2494 @cindex @code{desc} directive
2495 @cindex COFF symbol descriptor
2496 @cindex symbol descriptor, COFF
2497 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2498 to the low 16 bits of an absolute expression.
2501 The @samp{.desc} directive is not available when @code{_AS__} is
2502 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2503 object format. For the sake of compatibility, @code{_AS__} will accept
2504 it, but produce no output, when configured for COFF.
2506 _fi__(_AOUT__||_BOUT__)
2508 _if__(_COFF__ || _BOUT__)
2509 _if__(_AOUT__ || _BOUT__)
2510 @node Dim, Double, Desc, Pseudo Ops
2511 _fi__(_AOUT__ || _BOUT__)
2512 _if__(!(_AOUT__ || _BOUT__))
2513 @node Dim, Double, Def, Pseudo Ops
2514 _fi__(!(_AOUT__ || _BOUT__))
2515 @section @code{.dim}
2517 @cindex @code{dim} directive
2518 @cindex COFF auxiliary symbol information
2519 @cindex auxiliary symbol information, COFF
2520 This directive is generated by compilers to include auxiliary debugging
2521 information in the symbol table. It is only permitted inside
2522 @code{.def}/@code{.endef} pairs.
2525 @samp{.dim} is only meaningful when generating COFF format output; when
2526 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2529 _fi__(_COFF__ || _BOUT__)
2531 _if__(_COFF__||_BOUT__)
2532 @node Double, Eject, Dim, Pseudo Ops
2533 _fi__(_COFF__||_BOUT__)
2534 _if__(!(_COFF__||_BOUT__))
2535 @node Double, Eject, Desc, Pseudo Ops
2536 _fi__(!(_COFF__||_BOUT__))
2537 @section @code{.double @var{flonums}}
2539 @cindex @code{double} directive
2540 @cindex floating point numbers (double)
2541 @code{.double} expects zero or more flonums, separated by commas. It
2542 assembles floating point numbers.
2544 The exact kind of floating point numbers emitted depends on how
2545 @code{_AS__} is configured. @xref{_MACH_DEP__}.
2547 _if__((!_GENERIC__) && _IEEEFLOAT__)
2548 On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers
2549 in @sc{ieee} format.
2550 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2552 @node Eject, Else, Double, Pseudo Ops
2553 @section @code{.eject}
2555 @cindex @code{eject} directive
2556 @cindex new page, in listings
2557 @cindex page, in listings
2558 @cindex listing control: new page
2559 Force a page break at this point, when generating assembly listings.
2561 _if__(_COFF__||_BOUT__)
2562 @node Else, Endef, Eject, Pseudo Ops
2563 _fi__(_COFF__||_BOUT__)
2564 _if__(!(_COFF__||_BOUT__))
2565 @node Else, Endif, Eject, Pseudo Ops
2566 _fi__(!(_COFF__||_BOUT__))
2567 @section @code{.else}
2569 @cindex @code{else} directive
2570 @code{.else} is part of the @code{_AS__} support for conditional
2571 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2572 of code to be assembled if the condition for the preceding @code{.if}
2576 @node End, Endef, Else, Pseudo Ops
2577 @section @code{.end}
2579 @cindex @code{end} directive
2580 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2581 meant to do something eventually (which is why it isn't documented here
2582 as "for compatibility with blah").
2585 _if__(_COFF__||_BOUT__)
2586 @node Endef, Endif, Else, Pseudo Ops
2587 @section @code{.endef}
2589 @cindex @code{endef} directive
2590 This directive flags the end of a symbol definition begun with
2594 @samp{.endef} is only meaningful when generating COFF format output; if
2595 @code{_AS__} is configured to generate @code{b.out}, it accepts this
2596 directive but ignores it.
2598 _fi__(_COFF__||_BOUT__)
2600 _if__(_COFF__||_BOUT__)
2601 @node Endif, Equ, Endef, Pseudo Ops
2602 _fi__(_COFF__||_BOUT__)
2603 _if__(!(_COFF__||_BOUT__))
2604 @node Endif, Equ, Else, Pseudo Ops
2605 _fi__(!(_COFF__||_BOUT__))
2606 @section @code{.endif}
2608 @cindex @code{endif} directive
2609 @code{.endif} is part of the @code{_AS__} support for conditional assembly;
2610 it marks the end of a block of code that is only assembled
2611 conditionally. @xref{If,,@code{.if}}.
2613 @node Equ, Extern, Endif, Pseudo Ops
2614 @section @code{.equ @var{symbol}, @var{expression}}
2616 @cindex @code{equ} directive
2617 @cindex assigning values to symbols
2618 @cindex symbols, assigning values to
2619 This directive sets the value of @var{symbol} to @var{expression}.
2620 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2622 _if__(_GENERIC__||!_A29K__)
2623 @node Extern, File, Equ, Pseudo Ops
2624 _fi__(_GENERIC__||!_A29K__)
2625 _if__(_A29K__&&!_GENERIC__)
2626 @node Extern, Fill, Equ, Pseudo Ops
2627 _fi__(_A29K__&&!_GENERIC__)
2628 @section @code{.extern}
2630 @cindex @code{extern} directive
2631 @code{.extern} is accepted in the source program---for compatibility
2632 with other assemblers---but it is ignored. @code{_AS__} treats
2633 all undefined symbols as external.
2635 _if__(_GENERIC__||!_A29K__)
2636 @node File, Fill, Extern, Pseudo Ops
2637 @section @code{.file @var{string}}
2639 @cindex @code{file} directive
2640 @cindex logical file name
2641 @cindex file name, logical
2642 @code{.file} (which may also be spelled @samp{.app-file}) tells
2643 @code{_AS__} that we are about to start a new logical file.
2644 @var{string} is the new file name. In general, the filename is
2645 recognized whether or not it is surrounded by quotes @samp{"}; but if
2646 you wish to specify an empty file name, you must give the
2647 quotes--@code{""}. This statement may go away in future: it is only
2648 recognized to be compatible with old @code{_AS__} programs.
2650 In some configurations of @code{_AS__}, @code{.file} has already been
2651 removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}.
2653 _fi__(_GENERIC__||!_A29K__)
2655 _if__(_GENERIC__||!_A29K__)
2656 @node Fill, Float, File, Pseudo Ops
2657 _fi__(_GENERIC__||!_A29K__)
2658 _if__(_A29K__&&!_GENERIC__)
2659 @node Fill, Float, Extern, Pseudo Ops
2660 _fi__(_A29K__&&!_GENERIC__)
2661 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2663 @cindex @code{fill} directive
2664 @cindex writing patterns in memory
2665 @cindex patterns, writing in memory
2666 @var{result}, @var{size} and @var{value} are absolute expressions.
2667 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2668 may be zero or more. @var{Size} may be zero or more, but if it is
2669 more than 8, then it is deemed to have the value 8, compatible with
2670 other people's assemblers. The contents of each @var{repeat} bytes
2671 is taken from an 8-byte number. The highest order 4 bytes are
2672 zero. The lowest order 4 bytes are @var{value} rendered in the
2673 byte-order of an integer on the computer @code{_AS__} is assembling for.
2674 Each @var{size} bytes in a repetition is taken from the lowest order
2675 @var{size} bytes of this number. Again, this bizarre behavior is
2676 compatible with other people's assemblers.
2678 @var{size} and @var{value} are optional.
2679 If the second comma and @var{value} are absent, @var{value} is
2680 assumed zero. If the first comma and following tokens are absent,
2681 @var{size} is assumed to be 1.
2683 @node Float, Global, Fill, Pseudo Ops
2684 @section @code{.float @var{flonums}}
2686 @cindex floating point numbers (single)
2687 @cindex @code{float} directive
2688 This directive assembles zero or more flonums, separated by commas. It
2689 has the same effect as @code{.single}.
2691 The exact kind of floating point numbers emitted depends on how
2692 @code{_AS__} is configured.
2695 _if__((!_GENERIC__) && _IEEEFLOAT__)
2696 On the _HOST__ family, @code{.float} emits 32-bit floating point numbers
2697 in @sc{ieee} format.
2698 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2700 @node Global, hword, Float, Pseudo Ops
2701 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2703 @cindex @code{global} directive
2704 @cindex symbol, making visible to linker
2705 @code{.global} makes the symbol visible to @code{_LD__}. If you define
2706 @var{symbol} in your partial program, its value is made available to
2707 other partial programs that are linked with it. Otherwise,
2708 @var{symbol} will take its attributes from a symbol of the same name
2709 from another partial program it is linked with.
2711 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2712 compatibility with other assemblers.
2714 _if__(_AOUT__||_BOUT__||_COFF__)
2715 @node hword, Ident, Global, Pseudo Ops
2716 _fi__(_AOUT__||_BOUT__||_COFF__)
2717 _if__(!(_AOUT__||_BOUT__||_COFF__))
2718 @node hword, If, Global, Pseudo Ops
2719 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2720 @section @code{.hword @var{expressions}}
2722 @cindex @code{hword} directive
2723 @cindex integers, 16-bit
2724 @cindex numbers, 16-bit
2725 @cindex sixteen bit integers
2726 This expects zero or more @var{expressions}, and emits
2727 a 16 bit number for each.
2730 This directive is a synonym for @samp{.short}; depending on the target
2731 architecture, it may also be a synonym for @samp{.word}.
2733 _if__( _W32__ && !_GENERIC__ )
2734 This directive is a synonym for @samp{.short}.
2735 _fi__( _W32__ && !_GENERIC__ )
2736 _if__(_W16__ && !_GENERIC__ )
2737 This directive is a synonym for both @samp{.short} and @samp{.word}.
2738 _fi__(_W16__ && !_GENERIC__ )
2740 _if__(_AOUT__||_BOUT__||_COFF__)
2741 @node Ident, If, hword, Pseudo Ops
2742 @section @code{.ident}
2744 @cindex @code{ident} directive
2745 This directive is used by some assemblers to place tags in object files.
2746 @code{_AS__} simply accepts the directive for source-file
2747 compatibility with such assemblers, but does not actually emit anything
2749 _fi__(_AOUT__||_BOUT__||_COFF__)
2751 _if__(_AOUT__||_BOUT__||_COFF__)
2752 @node If, Include, Ident, Pseudo Ops
2753 _fi__(_AOUT__||_BOUT__||_COFF__)
2754 _if__(!(_AOUT__||_BOUT__||_COFF__))
2755 @node If, Include, hword, Pseudo Ops
2756 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2757 @section @code{.if @var{absolute expression}}
2759 @cindex conditional assembly
2760 @cindex @code{if} directive
2761 @code{.if} marks the beginning of a section of code which is only
2762 considered part of the source program being assembled if the argument
2763 (which must be an @var{absolute expression}) is non-zero. The end of
2764 the conditional section of code must be marked by @code{.endif}
2765 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
2766 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
2768 The following variants of @code{.if} are also supported:
2770 @item .ifdef @var{symbol}
2771 @cindex @code{ifdef} directive
2772 Assembles the following section of code if the specified @var{symbol}
2777 @cindex @code{ifeqs} directive
2778 Not yet implemented.
2781 @item .ifndef @var{symbol}
2782 @itemx ifnotdef @var{symbol}
2783 @cindex @code{ifndef} directive
2784 @cindex @code{ifnotdef} directive
2785 Assembles the following section of code if the specified @var{symbol}
2786 has not been defined. Both spelling variants are equivalent.
2790 Not yet implemented.
2794 @node Include, Int, If, Pseudo Ops
2795 @section @code{.include "@var{file}"}
2797 @cindex @code{include} directive
2798 @cindex supporting files, including
2799 @cindex files, including
2800 This directive provides a way to include supporting files at specified
2801 points in your source program. The code from @var{file} is assembled as
2802 if it followed the point of the @code{.include}; when the end of the
2803 included file is reached, assembly of the original file continues. You
2804 can control the search paths used with the @samp{-I} command-line option
2805 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
2808 @node Int, Lcomm, Include, Pseudo Ops
2809 @section @code{.int @var{expressions}}
2811 @cindex @code{int} directive
2812 _if__(_GENERIC__||!_H8__)
2813 @cindex integers, 32-bit
2814 _fi__(_GENERIC__||!_H8__)
2815 Expect zero or more @var{expressions}, of any section, separated by
2816 commas. For each expression, emit a
2817 _if__(_GENERIC__||!_H8__)
2819 _fi__(_GENERIC__||!_H8__)
2820 _if__(_H8__&&!_GENERIC__)
2822 _fi__(_H8__&&!_GENERIC__)
2823 number that will, at run
2824 time, be the value of that expression. The byte order of the
2825 expression depends on what kind of computer will run the program.
2827 @node Lcomm, Lflags, Int, Pseudo Ops
2828 @section @code{.lcomm @var{symbol} , @var{length}}
2830 @cindex @code{lcomm} directive
2831 @cindex local common symbols
2832 @cindex symbols, local common
2833 Reserve @var{length} (an absolute expression) bytes for a local common
2834 denoted by @var{symbol}. The section and value of @var{symbol} are
2835 those of the new local common. The addresses are allocated in the bss
2836 section, so at run-time the bytes will start off zeroed. @var{Symbol}
2837 is not declared global (@pxref{Global,,@code{.global}}), so is normally
2838 not visible to @code{_LD__}.
2840 _if__(_GENERIC__||(!_A29K__))
2841 @node Lflags, Line, Lcomm, Pseudo Ops
2842 _fi__(_GENERIC__||(!_A29K__))
2843 _if__((!_GENERIC__)&& _A29K__)
2844 @node Lflags, Ln, Lcomm, Pseudo Ops
2845 _fi__((!_GENERIC__)&& _A29K__)
2846 @section @code{.lflags}
2848 @cindex @code{lflags} directive (ignored)
2849 @code{_AS__} accepts this directive, for compatibility with other
2850 assemblers, but ignores it.
2852 _if__(_GENERIC__ || !_A29K__)
2853 @node Line, Ln, Lflags, Pseudo Ops
2854 @section @code{.line @var{line-number}}
2856 @cindex @code{line} directive
2857 _fi__(_GENERIC__ || (!_A29K__))
2858 _if__(_A29K__ && (!_GENERIC__))
2859 @node Ln, List, Lflags, Pseudo Ops
2860 @section @code{.ln @var{line-number}}
2862 @cindex @code{ln} directive
2863 _fi__(_A29K__ && (!_GENERIC__))
2864 @cindex logical line number
2865 _if__(_AOUT__||_BOUT__)
2866 Tell @code{_AS__} to change the logical line number. @var{line-number} must be
2867 an absolute expression. The next line will have that logical line
2868 number. So any other statements on the current line (after a statement
2874 _if__(! (_A29K__||_H8__) )
2876 _fi__(! (_A29K__||_H8__) )
2878 character @samp{@@})
2884 will be reported as on logical line number
2885 @var{line-number} @minus{} 1.
2886 One day this directive will be unsupported: it is used only
2887 for compatibility with existing assembler programs. @refill
2889 _if__(_GENERIC__ && _A29K__)
2890 @emph{Warning:} In the AMD29K configuration of _AS__, this command is
2891 only available with the name @code{.ln}, rather than as either
2892 @code{.line} or @code{.ln}.
2893 _fi__(_GENERIC__ && _A29K__)
2894 _fi__(_AOUT__||_BOUT__)
2897 Even though this is a directive associated with the @code{a.out} or
2898 @code{b.out} object-code formats, @code{_AS__} will still recognize it
2899 when producing COFF output, and will treat @samp{.line} as though it
2900 were the COFF @samp{.ln} @emph{if} it is found outside a
2901 @code{.def}/@code{.endef} pair.
2903 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
2904 used by compilers to generate auxiliary symbol information for
2908 _if__(_AOUT__&&(_GENERIC__||!_A29K__))
2909 @node Ln, List, Line, Pseudo Ops
2910 @section @code{.ln @var{line-number}}
2912 @cindex @code{ln} directive
2913 @samp{.ln} is a synonym for @samp{.line}.
2914 _fi__(_AOUT__&&(_GENERIC__||!_A29K__))
2915 _if__(_COFF__&&!_AOUT__)
2916 @node Ln, List, Line, Pseudo Ops
2917 @section @code{.ln @var{line-number}}
2919 @cindex @code{ln} directive
2920 Tell @code{_AS__} to change the logical line number. @var{line-number}
2921 must be an absolute expression. The next line will have that logical
2922 line number, so any other statements on the current line (after a
2923 statement separator character @code{;}) will be reported as on logical
2924 line number @var{line-number} @minus{} 1.
2927 This directive is accepted, but ignored, when @code{_AS__} is configured for
2928 @code{b.out}; its effect is only associated with COFF output format.
2930 _fi__(_COFF__&&!_AOUT__)
2932 @node List, Long, Ln, Pseudo Ops
2933 @section @code{.list}
2935 @cindex @code{list} directive
2936 @cindex listing control, turning on
2937 Control (in conjunction with the @code{.nolist} directive) whether or
2938 not assembly listings are generated. These two directives maintain an
2939 internal counter (which is zero initially). @code{.list} increments the
2940 counter, and @code{.nolist} decrements it. Assembly listings are
2941 generated whenever the counter is greater than zero.
2943 By default, listings are disabled. When you enable them (with the
2944 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
2945 the initial value of the listing counter is one.
2947 @node Long, Lsym, List, Pseudo Ops
2948 @section @code{.long @var{expressions}}
2950 @cindex @code{long} directive
2951 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
2953 @node Lsym, Nolist, Long, Pseudo Ops
2954 @section @code{.lsym @var{symbol}, @var{expression}}
2956 @cindex @code{lsym} directive
2957 @cindex symbol, not referenced in assembly
2958 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
2959 the hash table, ensuring it cannot be referenced by name during the
2960 rest of the assembly. This sets the attributes of the symbol to be
2961 the same as the expression value:
2963 @var{other} = @var{descriptor} = 0
2964 @var{type} = @r{(section of @var{expression})}
2965 @var{value} = @var{expression}
2968 The new symbol is not flagged as external.
2970 @node Nolist, Octa, Lsym, Pseudo Ops
2971 @section @code{.nolist}
2973 @cindex @code{nolist} directive
2974 @cindex listing control, turning off
2975 Control (in conjunction with the @code{.list} directive) whether or
2976 not assembly listings are generated. These two directives maintain an
2977 internal counter (which is zero initially). @code{.list} increments the
2978 counter, and @code{.nolist} decrements it. Assembly listings are
2979 generated whenever the counter is greater than zero.
2981 @node Octa, Org, Nolist, Pseudo Ops
2982 @section @code{.octa @var{bignums}}
2984 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
2985 @cindex @code{octa} directive
2986 @cindex integer, 16-byte
2987 @cindex sixteen byte integer
2988 This directive expects zero or more bignums, separated by commas. For each
2989 bignum, it emits a 16-byte integer.
2991 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
2992 hence @emph{octa}-word for 16 bytes.
2994 @node Org, Psize, Octa, Pseudo Ops
2995 @section @code{.org @var{new-lc} , @var{fill}}
2997 @cindex @code{org} directive
2998 @cindex location counter, advancing
2999 @cindex advancing location counter
3000 @cindex current address, advancing
3001 @code{.org} will advance the location counter of the current section to
3002 @var{new-lc}. @var{new-lc} is either an absolute expression or an
3003 expression with the same section as the current subsection. That is,
3004 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3005 wrong section, the @code{.org} directive is ignored. To be compatible
3006 with former assemblers, if the section of @var{new-lc} is absolute,
3007 @code{_AS__} will issue a warning, then pretend the section of @var{new-lc}
3008 is the same as the current subsection.
3010 @code{.org} may only increase the location counter, or leave it
3011 unchanged; you cannot use @code{.org} to move the location counter
3014 @c double negative used below "not undefined" because this is a specific
3015 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3016 @c section. pesch@cygnus.com 18feb91
3017 Because @code{_AS__} tries to assemble programs in one pass @var{new-lc}
3018 may not be undefined. If you really detest this restriction we eagerly await
3019 a chance to share your improved assembler.
3021 Beware that the origin is relative to the start of the section, not
3022 to the start of the subsection. This is compatible with other
3023 people's assemblers.
3025 When the location counter (of the current subsection) is advanced, the
3026 intervening bytes are filled with @var{fill} which should be an
3027 absolute expression. If the comma and @var{fill} are omitted,
3028 @var{fill} defaults to zero.
3030 @node Psize, Quad, Org, Pseudo Ops
3031 @section @code{.psize @var{lines} , @var{columns}}
3033 @cindex @code{psize} directive
3034 @cindex listing control: paper size
3035 @cindex paper size, for listings
3036 Use this directive to declare the number of lines---and, optionally, the
3037 number of columns---to use for each page, when generating listings.
3039 If you don't use @code{.psize}, listings will use a default line-count
3040 of 60. You may omit the comma and @var{columns} specification; the
3041 default width is 200 columns.
3043 @code{_AS__} will generate formfeeds whenever the specified number of
3044 lines is exceeded (or whenever you explicitly request one, using
3047 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3048 those explicitly specified with @code{.eject}.
3050 @node Quad, Sbttl, Psize, Pseudo Ops
3051 @section @code{.quad @var{bignums}}
3053 @cindex @code{quad} directive
3054 @code{.quad} expects zero or more bignums, separated by commas. For
3055 each bignum, it emits
3056 _if__(_GENERIC__||(!_I960__))
3057 an 8-byte integer. If the bignum won't fit in 8
3058 bytes, it prints a warning message; and just takes the lowest order 8
3059 bytes of the bignum.@refill
3060 @cindex eight-byte integer
3061 @cindex integer, 8-byte
3063 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3064 hence @emph{quad}-word for 8 bytes.
3065 _fi__(_GENERIC__||(!_I960__))
3066 _if__(_I960__&&(!_GENERIC__))
3067 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3068 warning message; and just takes the lowest order 16 bytes of the
3070 @cindex sixteen-byte integer
3071 @cindex integer, 16-byte
3072 _fi__(_I960__&&(!_GENERIC__))
3074 _if__(_COFF__||_BOUT__)
3075 @node Sbttl, Scl, Quad, Pseudo Ops
3076 _fi__(_COFF__||_BOUT__)
3077 _if__(!(_COFF__||_BOUT__))
3078 @node Sbttl, Set, Quad, Pseudo Ops
3079 _fi__(!(_COFF__||_BOUT__))
3080 @section @code{.sbttl "@var{subheading}"}
3082 @cindex @code{sbttl} directive
3083 @cindex subtitles for listings
3084 @cindex listing control: subtitle
3085 Use @var{subheading} as the title (third line, immediately after the
3086 title line) when generating assembly listings.
3088 This directive affects subsequent pages, as well as the current page if
3089 it appears within ten lines of the top of a page.
3091 _if__(_COFF__||_BOUT__)
3093 @node Scl, Set, Sbttl, Pseudo Ops
3096 @node Scl, Section, Sbttl, Pseudo Ops
3098 @section @code{.scl @var{class}}
3100 @cindex @code{scl} directive
3101 @cindex symbol storage class (COFF)
3102 @cindex COFF symbol storage class
3103 Set the storage-class value for a symbol. This directive may only be
3104 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3105 whether a symbol is static or external, or it may record further
3106 symbolic debugging information.
3109 The @samp{.scl} directive is primarily associated with COFF output; when
3110 configured to generate @code{b.out} output format, @code{_AS__} will
3111 accept this directive but ignore it.
3113 _fi__(_COFF__||_BOUT__)
3116 @node Section, Set, Scl, Pseudo Ops
3117 @section @code{.section @var{name}, @var{subsection}}
3119 @cindex @code{section} directive
3120 @cindex named section (COFF)
3121 @cindex COFF named section
3122 Assemble the following code into end of subsection numbered
3123 @var{subsection} in the COFF named section @var{name}. If you omit
3124 @var{subsection}, @code{_AS__} uses subsection number zero.
3125 @samp{.section .text} is equivalent to the @code{.text} directive;
3126 @samp{.section .data} is equivalent to the @code{.data} directive.
3128 @node Set, Short, Section, Pseudo Ops
3130 _if__(_BOUT__&&!_COFF__)
3131 @node Set, Short, Scl, Pseudo Ops
3132 _fi__(_BOUT__&&!_COFF__)
3133 _if__(!(_COFF__||_BOUT__))
3134 @node Set, Short, Quad, Pseudo Ops
3135 _fi__(!(_COFF__||_BOUT__))
3136 @section @code{.set @var{symbol}, @var{expression}}
3138 @cindex @code{set} directive
3139 @cindex symbol value, setting
3140 This directive sets the value of @var{symbol} to @var{expression}. This
3141 will change @var{symbol}'s value and type to conform to
3142 @var{expression}. If @var{symbol} was flagged as external, it remains
3143 flagged. (@xref{Symbol Attributes}.)
3145 You may @code{.set} a symbol many times in the same assembly.
3146 If the expression's section is unknowable during pass 1, a second
3147 pass over the source program will be forced. The second pass is
3148 currently not implemented. @code{_AS__} will abort with an error
3149 message if one is required.
3151 If you @code{.set} a global symbol, the value stored in the object
3152 file is the last value stored into it.
3154 @node Short, Single, Set, Pseudo Ops
3155 @section @code{.short @var{expressions}}
3157 @cindex @code{short} directive
3158 _if__(_GENERIC__ || _W16__)
3159 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3161 In some configurations, however, @code{.short} and @code{.word} generate
3162 numbers of different lengths; @pxref{_MACH_DEP__}.
3164 _fi__(_GENERIC__|| _W16__)
3165 _if__((!_GENERIC__) && _W32__)
3166 This expects zero or more @var{expressions}, and emits
3167 a 16 bit number for each.
3168 _fi__((!_GENERIC__) && _W32__)
3169 _if__(_COFF__||_BOUT__)
3170 @node Single, Size, Short, Pseudo Ops
3171 _fi__(_COFF__||_BOUT__)
3172 _if__(!(_COFF__||_BOUT__))
3173 @node Single, Space, Short, Pseudo Ops
3174 _fi__(!(_COFF__||_BOUT__))
3175 @section @code{.single @var{flonums}}
3177 @cindex @code{single} directive
3178 @cindex floating point numbers (single)
3179 This directive assembles zero or more flonums, separated by commas. It
3180 has the same effect as @code{.float}.
3182 The exact kind of floating point numbers emitted depends on how
3183 @code{_AS__} is configured. @xref{_MACH_DEP__}.
3185 _if__((!_GENERIC__) && _IEEEFLOAT__)
3186 On the _HOST__ family, @code{.single} emits 32-bit floating point
3187 numbers in @sc{ieee} format.
3188 _fi__((!_GENERIC__) && _IEEEFLOAT__)
3190 _if__(_COFF__||_BOUT__)
3191 @node Size, Space, Single, Pseudo Ops
3192 @section @code{.size}
3194 @cindex @code{size} directive
3195 This directive is generated by compilers to include auxiliary debugging
3196 information in the symbol table. It is only permitted inside
3197 @code{.def}/@code{.endef} pairs.
3200 @samp{.size} is only meaningful when generating COFF format output; when
3201 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3204 _fi__(_COFF__||_BOUT__)
3206 _if__(_H8__&&!_GENERIC__)
3207 @node Space, Tag, Size, Pseudo Ops
3208 _fi__(_H8__&&!_GENERIC__)
3209 _if__(_GENERIC__||!_H8__)
3210 _if__(_COFF__||_BOUT__)
3211 @node Space, Stab, Size, Pseudo Ops
3212 _fi__(_COFF__||_BOUT__)
3213 _if__(!(_COFF__||_BOUT__))
3214 @node Space, Stab, Single, Pseudo Ops
3215 _fi__(!(_COFF__||_BOUT__))
3216 _fi__(_GENERIC__||!_H8__)
3217 _if__(_GENERIC__ || !_A29K__)
3218 @section @code{.space @var{size} , @var{fill}}
3220 @cindex @code{space} directive
3221 @cindex filling memory
3222 This directive emits @var{size} bytes, each of value @var{fill}. Both
3223 @var{size} and @var{fill} are absolute expressions. If the comma
3224 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3225 _fi__(_GENERIC__ || !_A29K__)
3229 @section @code{.space}
3230 @cindex @code{space} directive
3232 On the AMD 29K, this directive is ignored; it is accepted for
3233 compatibility with other AMD 29K assemblers.
3236 @emph{Warning:} In other versions of the GNU assembler, the directive
3237 @code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}.
3241 _if__(_GENERIC__||!_H8__)
3242 _if__(_AOUT__||_BOUT__||_COFF__)
3243 _if__(_COFF__||_BOUT__)
3244 @node Stab, Tag, Space, Pseudo Ops
3245 _fi__(_COFF__||_BOUT__)
3246 _if__(!(_COFF__||_BOUT__))
3247 @node Stab, Text, Space, Pseudo Ops
3248 _fi__(!(_COFF__||_BOUT__))
3249 @section @code{.stabd, .stabn, .stabs}
3251 @cindex symbolic debuggers, information for
3252 @cindex @code{stab@var{x}} directives
3253 There are three directives that begin @samp{.stab}.
3254 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3255 The symbols are not entered in the @code{_AS__} hash table: they
3256 cannot be referenced elsewhere in the source file.
3257 Up to five fields are required:
3260 This is the symbol's name. It may contain any character except @samp{\000},
3261 so is more general than ordinary symbol names. Some debuggers used to
3262 code arbitrarily complex structures into symbol names using this field.
3264 An absolute expression. The symbol's type is set to the low 8
3265 bits of this expression.
3266 Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on
3269 An absolute expression.
3270 The symbol's ``other'' attribute is set to the low 8 bits of this expression.
3272 An absolute expression.
3273 The symbol's descriptor is set to the low 16 bits of this expression.
3275 An absolute expression which becomes the symbol's value.
3278 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3279 or @code{.stabs} statement, the symbol has probably already been created
3280 and you will get a half-formed symbol in your object file. This is
3281 compatible with earlier assemblers!
3284 @cindex @code{stabd} directive
3285 @item .stabd @var{type} , @var{other} , @var{desc}
3287 The ``name'' of the symbol generated is not even an empty string.
3288 It is a null pointer, for compatibility. Older assemblers used a
3289 null pointer so they didn't waste space in object files with empty
3292 The symbol's value is set to the location counter,
3293 relocatably. When your program is linked, the value of this symbol
3294 will be where the location counter was when the @code{.stabd} was
3297 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3298 @cindex @code{stabn} directive
3299 The name of the symbol is set to the empty string @code{""}.
3301 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3302 @cindex @code{stabs} directive
3303 All five fields are specified.
3305 _fi__(_AOUT__||_BOUT__||_COFF__)
3306 _fi__(_GENERIC__||!_H8__)
3308 _if__(_COFF__||_BOUT__)
3309 _if__(_GENERIC__||!_H8__)
3310 @node Tag, Text, Stab, Pseudo Ops
3311 _fi__(_GENERIC__||!_H8__)
3312 _if__(_H8__&&!_GENERIC__)
3313 @node Tag, Text, Space, Pseudo Ops
3314 _fi__(_H8__&&!_GENERIC__)
3315 @section @code{.tag @var{structname}}
3317 @cindex COFF structure debugging
3318 @cindex structure debugging, COFF
3319 @cindex @code{tag} directive
3320 This directive is generated by compilers to include auxiliary debugging
3321 information in the symbol table. It is only permitted inside
3322 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3323 definitions in the symbol table with instances of those structures.
3326 @samp{.tag} is only used when generating COFF format output; when
3327 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3330 _fi__(_COFF__||_BOUT__)
3332 _if__(_COFF__||_BOUT__)
3333 @node Text, Title, Tag, Pseudo Ops
3334 _fi__(_COFF__||_BOUT__)
3335 _if__(!(_COFF__||_BOUT__))
3336 @node Text, Title, Stab, Pseudo Ops
3337 _fi__(!(_COFF__||_BOUT__))
3338 @section @code{.text @var{subsection}}
3340 @cindex @code{text} directive
3341 Tells @code{_AS__} to assemble the following statements onto the end of
3342 the text subsection numbered @var{subsection}, which is an absolute
3343 expression. If @var{subsection} is omitted, subsection number zero
3346 _if__(_COFF__||_BOUT__)
3347 @node Title, Type, Text, Pseudo Ops
3348 _fi__(_COFF__||_BOUT__)
3349 _if__(!(_COFF__||_BOUT__))
3350 @node Title, Word, Text, Pseudo Ops
3351 _fi__(!(_COFF__||_BOUT__))
3352 @section @code{.title "@var{heading}"}
3354 @cindex @code{title} directive
3355 @cindex listing control: title line
3356 Use @var{heading} as the title (second line, immediately after the
3357 source file name and pagenumber) when generating assembly listings.
3359 This directive affects subsequent pages, as well as the current page if
3360 it appears within ten lines of the top of a page.
3362 _if__(_COFF__||_BOUT__)
3363 @node Type, Val, Title, Pseudo Ops
3364 @section @code{.type @var{int}}
3366 @cindex COFF symbol type
3367 @cindex symbol type, COFF
3368 @cindex @code{type} directive
3369 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3370 records the integer @var{int} as the type attribute of a symbol table entry.
3373 @samp{.type} is associated only with COFF format output; when
3374 @code{_AS__} is configured for @code{b.out} output, it accepts this
3375 directive but ignores it.
3377 _fi__(_COFF__||_BOUT__)
3379 _if__(_COFF__||_BOUT__)
3380 @node Val, Word, Type, Pseudo Ops
3381 @section @code{.val @var{addr}}
3383 @cindex @code{val} directive
3384 @cindex COFF value attribute
3385 @cindex value attribute, COFF
3386 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3387 records the address @var{addr} as the value attribute of a symbol table
3391 @samp{.val} is used only for COFF output; when @code{_AS__} is
3392 configured for @code{b.out}, it accepts this directive but ignores it.
3394 _fi__(_COFF__||_BOUT__)
3396 _if__(_COFF__||_BOUT__)
3397 @node Word, Deprecated, Val, Pseudo Ops
3398 _fi__(_COFF__||_BOUT__)
3399 _if__(!(_COFF__||_BOUT__))
3400 @node Word, Deprecated, Text, Pseudo Ops
3401 _fi__(!(_COFF__||_BOUT__))
3402 @section @code{.word @var{expressions}}
3404 @cindex @code{word} directive
3405 This directive expects zero or more @var{expressions}, of any section,
3406 separated by commas.
3407 _if__((!_GENERIC__) && _W32__)
3408 For each expression, @code{_AS__} emits a 32-bit number.
3409 _fi__((!_GENERIC__) && _W32__)
3410 _if__((!_GENERIC__) && _W16__)
3411 For each expression, @code{_AS__} emits a 16-bit number.
3412 _fi__((!_GENERIC__) && _W16__)
3415 The size of the number emitted, and its byte order,
3416 depends on what kind of computer will run the program.
3419 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3420 @c happen---32-bit addressability, period; no long/short jumps.
3421 _if__(_GENERIC__ || _DIFFTABKLUG__)
3422 @cindex difference tables altered
3423 @cindex altered difference tables
3425 @emph{Warning: Special Treatment to support Compilers}
3429 Machines with a 32-bit address space, but that do less than 32-bit
3430 addressing, require the following special treatment. If the machine of
3431 interest to you does 32-bit addressing (or doesn't require it;
3432 @pxref{_MACH_DEP__}), you can ignore this issue.
3435 In order to assemble compiler output into something that will work,
3436 @code{_AS__} will occasionlly do strange things to @samp{.word} directives.
3437 Directives of the form @samp{.word sym1-sym2} are often emitted by
3438 compilers as part of jump tables. Therefore, when @code{_AS__} assembles a
3439 directive of the form @samp{.word sym1-sym2}, and the difference between
3440 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will
3441 create a @dfn{secondary jump table}, immediately before the next label.
3442 This secondary jump table will be preceded by a short-jump to the
3443 first byte after the secondary table. This short-jump prevents the flow
3444 of control from accidentally falling into the new table. Inside the
3445 table will be a long-jump to @code{sym2}. The original @samp{.word}
3446 will contain @code{sym1} minus the address of the long-jump to
3449 If there were several occurrences of @samp{.word sym1-sym2} before the
3450 secondary jump table, all of them will be adjusted. If there was a
3451 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3452 long-jump to @code{sym4} will be included in the secondary jump table,
3453 and the @code{.word} directives will be adjusted to contain @code{sym3}
3454 minus the address of the long-jump to @code{sym4}; and so on, for as many
3455 entries in the original jump table as necessary.
3458 @emph{This feature may be disabled by compiling @code{_AS__} with the
3459 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3460 assembly language programmers.
3462 _fi__(_GENERIC__ || _DIFFTABKLUG__)
3464 @node Deprecated, , Word, Pseudo Ops
3465 @section Deprecated Directives
3467 @cindex deprecated directives
3468 @cindex obsolescent directives
3469 One day these directives won't work.
3470 They are included for compatibility with older assemblers.
3477 @node _MACH_DEP__, Copying, Pseudo Ops, Top
3479 @chapter Machine Dependent Features
3481 @cindex machine dependencies
3482 The machine instruction sets are (almost by definition) different on
3483 each machine where @code{_AS__} runs. Floating point representations
3484 vary as well, and @code{_AS__} often supports a few additional
3485 directives or command-line options for compatibility with other
3486 assemblers on a particular platform. Finally, some versions of
3487 @code{_AS__} support special pseudo-instructions for branch
3490 This chapter discusses most of these differences, though it does not
3491 include details on any machine's instruction set. For details on that
3492 subject, see the hardware manufacturer's manual.
3496 * Vax-Dependent:: VAX Dependent Features
3499 * AMD29K-Dependent:: AMD 29K Dependent Features
3502 * H8/300-Dependent:: AMD 29K Dependent Features
3505 * i960-Dependent:: Intel 80960 Dependent Features
3508 * M68K-Dependent:: M680x0 Dependent Features
3511 * Sparc-Dependent:: SPARC Dependent Features
3514 * i386-Dependent:: 80386 Dependent Features
3521 @node Vax-Dependent, AMD29K-Dependent, Machine Dependent, Machine Dependent
3523 _CHAPSEC__(0+_GENERIC__) VAX Dependent Features
3527 * Vax-Opts:: VAX Command-Line Options
3528 * VAX-float:: VAX Floating Point
3529 * VAX-directives:: Vax Machine Directives
3530 * VAX-opcodes:: VAX Opcodes
3531 * VAX-branch:: VAX Branch Improvement
3532 * VAX-operands:: VAX Operands
3533 * VAX-no:: Not Supported on VAX
3536 @node Vax-Opts, VAX-float, Vax-Dependent, Vax-Dependent
3537 _CHAPSEC__(1+_GENERIC__) VAX Command-Line Options
3539 @cindex command-line options ignored, VAX
3540 @cindex VAX command-line options ignored
3541 The Vax version of @code{_AS__} accepts any of the following options,
3542 gives a warning message that the option was ignored and proceeds.
3543 These options are for compatibility with scripts designed for other
3544 people's assemblers.
3547 @item @kbd{-D} (Debug)
3548 @itemx @kbd{-S} (Symbol Table)
3549 @itemx @kbd{-T} (Token Trace)
3550 @cindex @code{-D}, ignored on VAX
3551 @cindex @code{-S}, ignored on VAX
3552 @cindex @code{-T}, ignored on VAX
3553 These are obsolete options used to debug old assemblers.
3555 @item @kbd{-d} (Displacement size for JUMPs)
3556 @cindex @code{-d}, VAX option
3557 This option expects a number following the @kbd{-d}. Like options
3558 that expect filenames, the number may immediately follow the
3559 @kbd{-d} (old standard) or constitute the whole of the command line
3560 argument that follows @kbd{-d} (GNU standard).
3562 @item @kbd{-V} (Virtualize Interpass Temporary File)
3563 @cindex @code{-V}, redundant on VAX
3564 Some other assemblers use a temporary file. This option
3565 commanded them to keep the information in active memory rather
3566 than in a disk file. @code{_AS__} always does this, so this
3567 option is redundant.
3569 @item @kbd{-J} (JUMPify Longer Branches)
3570 @cindex @code{-J}, ignored on VAX
3571 Many 32-bit computers permit a variety of branch instructions
3572 to do the same job. Some of these instructions are short (and
3573 fast) but have a limited range; others are long (and slow) but
3574 can branch anywhere in virtual memory. Often there are 3
3575 flavors of branch: short, medium and long. Some other
3576 assemblers would emit short and medium branches, unless told by
3577 this option to emit short and long branches.
3579 @item @kbd{-t} (Temporary File Directory)
3580 @cindex @code{-t}, ignored on VAX
3581 Some other assemblers may use a temporary file, and this option
3582 takes a filename being the directory to site the temporary
3583 file. @code{_AS__} does not use a temporary disk file, so this
3584 option makes no difference. @kbd{-t} needs exactly one
3588 @cindex VMS (VAX) options
3589 @cindex options for VAX/VMS
3590 @cindex VAX/VMS options
3591 @cindex @code{-h} option, VAX/VMS
3592 @cindex @code{-+} option, VAX/VMS
3593 @cindex Vax-11 C compatibility
3594 @cindex symbols with lowercase, VAX/VMS
3595 @c FIXME! look into "I think" below, correct if needed, delete.
3596 The Vax version of the assembler accepts two options when
3597 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
3598 @kbd{-h} option prevents @code{_AS__} from modifying the
3599 symbol-table entries for symbols that contain lowercase
3600 characters (I think). The @kbd{-+} option causes @code{_AS__} to
3601 print warning messages if the FILENAME part of the object file,
3602 or any symbol name is larger than 31 characters. The @kbd{-+}
3603 option also insertes some code following the @samp{_main}
3604 symbol so that the object file will be compatible with Vax-11
3607 @node VAX-float, VAX-directives, Vax-Opts, Vax-Dependent
3608 _CHAPSEC__(1+_GENERIC__) VAX Floating Point
3610 @cindex VAX floating point
3611 @cindex floating point, VAX
3612 Conversion of flonums to floating point is correct, and
3613 compatible with previous assemblers. Rounding is
3614 towards zero if the remainder is exactly half the least significant bit.
3616 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3619 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3620 are rendered correctly. Again, rounding is towards zero in the
3623 @cindex @code{float} directive, VAX
3624 @cindex @code{double} directive, VAX
3625 The @code{.float} directive produces @code{f} format numbers.
3626 The @code{.double} directive produces @code{d} format numbers.
3628 @node VAX-directives, VAX-opcodes, VAX-float, Vax-Dependent
3629 _CHAPSEC__(1+_GENERIC__) Vax Machine Directives
3631 @cindex machine directives, VAX
3632 @cindex VAX machine directives
3633 The Vax version of the assembler supports four directives for
3634 generating Vax floating point constants. They are described in the
3637 @cindex wide floating point directives, VAX
3640 @cindex @code{dfloat} directive, VAX
3641 This expects zero or more flonums, separated by commas, and
3642 assembles Vax @code{d} format 64-bit floating point constants.
3645 @cindex @code{ffloat} directive, VAX
3646 This expects zero or more flonums, separated by commas, and
3647 assembles Vax @code{f} format 32-bit floating point constants.
3650 @cindex @code{gfloat} directive, VAX
3651 This expects zero or more flonums, separated by commas, and
3652 assembles Vax @code{g} format 64-bit floating point constants.
3655 @cindex @code{hfloat} directive, VAX
3656 This expects zero or more flonums, separated by commas, and
3657 assembles Vax @code{h} format 128-bit floating point constants.
3661 @node VAX-opcodes, VAX-branch, VAX-directives, Vax-Dependent
3662 _CHAPSEC__(1+_GENERIC__) VAX Opcodes
3664 @cindex VAX opcode mnemonics
3665 @cindex opcode mnemonics, VAX
3666 @cindex mnemonics for opcodes, VAX
3667 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3668 instructions have exactly 3 operands. The dispatch table that
3669 follows the @code{case@dots{}} instruction should be made with
3670 @code{.word} statements. This is compatible with all unix
3671 assemblers we know of.
3673 @node VAX-branch, VAX-operands, VAX-opcodes, Vax-Dependent
3674 _CHAPSEC__(1+_GENERIC__) VAX Branch Improvement
3676 @cindex VAX branch improvement
3677 @cindex branch improvement, VAX
3678 @cindex pseudo-ops for branch, VAX
3679 Certain pseudo opcodes are permitted. They are for branch
3680 instructions. They expand to the shortest branch instruction that
3681 will reach the target. Generally these mnemonics are made by
3682 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3683 This feature is included both for compatibility and to help
3684 compilers. If you don't need this feature, don't use these
3685 opcodes. Here are the mnemonics, and the code they can expand into.
3689 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3691 @item (byte displacement)
3693 @item (word displacement)
3695 @item (long displacement)
3700 Unconditional branch.
3702 @item (byte displacement)
3704 @item (word displacement)
3706 @item (long displacement)
3710 @var{COND} may be any one of the conditional branches
3711 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
3712 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
3713 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
3714 @var{COND} may also be one of the bit tests
3715 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
3716 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
3717 @var{NOTCOND} is the opposite condition to @var{COND}.
3719 @item (byte displacement)
3720 @kbd{b@var{COND} @dots{}}
3721 @item (word displacement)
3722 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
3723 @item (long displacement)
3724 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
3727 @var{X} may be one of @code{b d f g h l w}.
3729 @item (word displacement)
3730 @kbd{@var{OPCODE} @dots{}}
3731 @item (long displacement)
3733 @var{OPCODE} @dots{}, foo ;
3740 @var{YYY} may be one of @code{lss leq}.
3742 @var{ZZZ} may be one of @code{geq gtr}.
3744 @item (byte displacement)
3745 @kbd{@var{OPCODE} @dots{}}
3746 @item (word displacement)
3748 @var{OPCODE} @dots{}, foo ;
3750 foo: brw @var{destination} ;
3753 @item (long displacement)
3755 @var{OPCODE} @dots{}, foo ;
3757 foo: jmp @var{destination} ;
3766 @item (byte displacement)
3767 @kbd{@var{OPCODE} @dots{}}
3768 @item (word displacement)
3770 @var{OPCODE} @dots{}, foo ;
3772 foo: brw @var{destination} ;
3775 @item (long displacement)
3777 @var{OPCODE} @dots{}, foo ;
3779 foo: jmp @var{destination} ;
3785 @node VAX-operands, VAX-no, VAX-branch, Vax-Dependent
3786 _CHAPSEC__(1+_GENERIC__) VAX Operands
3788 @cindex VAX operand notation
3789 @cindex operand notation, VAX
3790 @cindex immediate character, VAX
3791 @cindex VAX immediate character
3792 The immediate character is @samp{$} for Unix compatibility, not
3793 @samp{#} as DEC writes it.
3795 @cindex indirect character, VAX
3796 @cindex VAX indirect character
3797 The indirect character is @samp{*} for Unix compatibility, not
3798 @samp{@@} as DEC writes it.
3800 @cindex displacement sizing character, VAX
3801 @cindex VAX displacement sizing character
3802 The displacement sizing character is @samp{`} (an accent grave) for
3803 Unix compatibility, not @samp{^} as DEC writes it. The letter
3804 preceding @samp{`} may have either case. @samp{G} is not
3805 understood, but all other letters (@code{b i l s w}) are understood.
3807 @cindex register names, VAX
3808 @cindex VAX register names
3809 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
3810 pc}. Any case of letters will do.
3817 Any expression is permitted in an operand. Operands are comma
3820 @c There is some bug to do with recognizing expressions
3821 @c in operands, but I forget what it is. It is
3822 @c a syntax clash because () is used as an address mode
3823 @c and to encapsulate sub-expressions.
3825 @node VAX-no, , VAX-operands, Vax-Dependent
3826 _CHAPSEC__(1+_GENERIC__) Not Supported on VAX
3828 @cindex VAX bitfields not supported
3829 @cindex bitfields, not supported on VAX
3830 Vax bit fields can not be assembled with @code{_AS__}. Someone
3831 can add the required code if they really need it.
3836 @node AMD29K-Dependent, H8/300-Dependent, Vax-Dependent, Machine Dependent
3838 _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features
3840 @cindex AMD 29K support
3843 * AMD29K Options:: Options
3844 * AMD29K Syntax:: Syntax
3845 * AMD29K Floating Point:: Floating Point
3846 * AMD29K Directives:: AMD 29K Machine Directives
3847 * AMD29K Opcodes:: Opcodes
3850 @node AMD29K Options, AMD29K Syntax, AMD29K-Dependent, AMD29K-Dependent
3851 _CHAPSEC__(1+_GENERIC__) Options
3852 @cindex AMD 29K options (none)
3853 @cindex options for AMD29K (none)
3854 @code{_AS__} has no additional command-line options for the AMD
3857 @node AMD29K Syntax, AMD29K Floating Point, AMD29K Options, AMD29K-Dependent
3858 _CHAPSEC__(1+_GENERIC__) Syntax
3860 * AMD29K-Chars:: Special Characters
3861 * AMD29K-Regs:: Register Names
3864 @node AMD29K-Chars, AMD29K-Regs, AMD29K Syntax, AMD29K Syntax
3865 _CHAPSEC__(2+_GENERIC__) Special Characters
3867 @cindex line comment character, AMD 29K
3868 @cindex AMD 29K line comment character
3869 @samp{;} is the line comment character.
3871 @cindex line separator, AMD 29K
3872 @cindex AMD 29K line separator
3873 @cindex statement separator, AMD 29K
3874 @cindex AMD 29K statement separator
3875 @samp{@@} can be used instead of a newline to separate statements.
3877 @cindex identifiers, AMD 29K
3878 @cindex AMD 29K identifiers
3879 The character @samp{?} is permitted in identifiers (but may not begin
3882 @node AMD29K-Regs, , AMD29K-Chars, AMD29K Syntax
3883 _CHAPSEC__(2+_GENERIC__) Register Names
3885 @cindex AMD 29K register names
3886 @cindex register names, AMD 29K
3887 General-purpose registers are represented by predefined symbols of the
3888 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
3889 (for local registers), where @var{nnn} represents a number between
3890 @code{0} and @code{127}, written with no leading zeros. The leading
3891 letters may be in either upper or lower case; for example, @samp{gr13}
3892 and @samp{LR7} are both valid register names.
3894 You may also refer to general-purpose registers by specifying the
3895 register number as the result of an expression (prefixed with @samp{%%}
3896 to flag the expression as a register number):
3901 ---where @var{expression} must be an absolute expression evaluating to a
3902 number between @code{0} and @code{255}. The range [0, 127] refers to
3903 global registers, and the range [128, 255] to local registers.
3905 @cindex special purpose registers, AMD 29K
3906 @cindex AMD 29K special purpose registers
3907 @cindex protected registers, AMD 29K
3908 @cindex AMD 29K protected registers
3909 In addition, @code{_AS__} understands the following protected
3910 special-purpose register names for the AMD 29K family:
3920 These unprotected special-purpose register names are also recognized:
3928 @node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, AMD29K-Dependent
3929 _CHAPSEC__(1+_GENERIC__) Floating Point
3931 @cindex floating point, AMD 29K (@sc{ieee})
3932 @cindex AMD 29K floating point (@sc{ieee})
3933 The AMD 29K family uses @sc{ieee} floating-point numbers.
3935 @node AMD29K Directives, AMD29K Opcodes, AMD29K Floating Point, AMD29K-Dependent
3936 _CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives
3938 @cindex machine directives, AMD 29K
3939 @cindex AMD 29K machine directives
3941 @item .block @var{size} , @var{fill}
3942 @cindex @code{block} directive, AMD 29K
3943 This directive emits @var{size} bytes, each of value @var{fill}. Both
3944 @var{size} and @var{fill} are absolute expressions. If the comma
3945 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3947 In other versions of the GNU assembler, this directive is called
3953 @cindex @code{cputype} directive, AMD 29K
3954 This directive is ignored; it is accepted for compatibility with other
3958 @cindex @code{file} directive, AMD 29K
3959 This directive is ignored; it is accepted for compatibility with other
3963 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
3964 used for the directive called @code{.app-file} in the AMD 29K support.
3968 @cindex @code{line} directive, AMD 29K
3969 This directive is ignored; it is accepted for compatibility with other
3972 @item .reg @var{symbol}, @var{expression}
3973 @cindex @code{reg} directive, AMD 29K
3974 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
3977 @cindex @code{sect} directive, AMD 29K
3978 This directive is ignored; it is accepted for compatibility with other
3981 @item .use @var{section name}
3982 @cindex @code{use} directive, AMD 29K
3983 Establishes the section and subsection for the following code;
3984 @var{section name} may be one of @code{.text}, @code{.data},
3985 @code{.data1}, or @code{.lit}. With one of the first three @var{section
3986 name} options, @samp{.use} is equivalent to the machine directive
3987 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
3991 @node AMD29K Opcodes, , AMD29K Directives, AMD29K-Dependent
3992 _CHAPSEC__(1+_GENERIC__) Opcodes
3994 @cindex AMD 29K opcodes
3995 @cindex opcodes for AMD 29K
3996 @code{_AS__} implements all the standard AMD 29K opcodes. No
3997 additional pseudo-instructions are needed on this family.
3999 For information on the 29K machine instruction set, see @cite{Am29000
4000 User's Manual}, Advanced Micro Devices, Inc.
4005 @node H8/300-Dependent, i960-Dependent, AMD29K-Dependent, Machine Dependent
4007 _CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features
4009 @cindex H8/300 support
4011 * H8/300 Options:: Options
4012 * H8/300 Syntax:: Syntax
4013 * H8/300 Floating Point:: Floating Point
4014 * H8/300 Directives:: H8/300 Machine Directives
4015 * H8/300 Opcodes:: Opcodes
4018 @node H8/300 Options, H8/300 Syntax, H8/300-Dependent, H8/300-Dependent
4019 _CHAPSEC__(1+_GENERIC__) Options
4021 @cindex H8/300 options (none)
4022 @cindex options, H8/300 (none)
4023 @code{_AS__} has no additional command-line options for the Hitachi
4026 @node H8/300 Syntax, H8/300 Floating Point, H8/300 Options, H8/300-Dependent
4027 _CHAPSEC__(1+_GENERIC__) Syntax
4029 * H8/300-Chars:: Special Characters
4030 * H8/300-Regs:: Register Names
4031 * H8/300-Addressing:: Addressing Modes
4034 @node H8/300-Chars, H8/300-Regs, H8/300 Syntax, H8/300 Syntax
4035 _CHAPSEC__(2+_GENERIC__) Special Characters
4037 @cindex line comment character, H8/300
4038 @cindex H8/300 line comment character
4039 @samp{;} is the line comment character.
4041 @cindex line separator, H8/300
4042 @cindex statement separator, H8/300
4043 @cindex H8/300 line separator
4044 @samp{$} can be used instead of a newline to separate statements.
4045 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4047 @node H8/300-Regs, H8/300-Addressing, H8/300-Chars, H8/300 Syntax
4048 _CHAPSEC__(2+_GENERIC__) Register Names
4050 @cindex H8/300 registers
4051 @cindex registers, H8/300
4052 You can use predefined symbols of the form @samp{r@var{n}h} and
4053 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4054 general-purpose registers. @var{n} is a digit from @samp{0} to
4055 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4058 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4059 to the H8/300 registers as 16-bit registers (you must use this form for
4062 The two control registers are called @code{pc} (program counter; a
4063 16-bit register) and @code{ccr} (condition code register; an 8-bit
4064 register). @code{r7} is used as the stack pointer, and can also be
4067 @node H8/300-Addressing, , H8/300-Regs, H8/300 Syntax
4068 _CHAPSEC__(2+_GENERIC__) Addressing Modes
4070 @cindex addressing modes, H8/300
4071 @cindex H8/300 addressing modes
4072 _AS__ understands the following addressing modes for the H8/300:
4080 @item @@(@var{d}, r@var{n})
4081 @itemx @@(@var{d}:16, r@var{n})
4082 Register indirect: 16-bit displacement @var{d} from register @var{n}.
4083 (You may specify the @samp{:16} for clarity if you wish, but it is not
4084 required and has no effect.)
4087 Register indirect with post-increment
4090 Register indirect with pre-decrement
4092 @item @code{@@}@var{aa}
4093 @itemx @code{@@}@var{aa}:8
4094 @itemx @code{@@}@var{aa}:16
4095 Absolute address @code{aa}. You may specify the @samp{:8} or @samp{:16}
4096 for clarity, if you wish; but @code{_AS__} neither requires this nor
4097 uses it---the address size required is taken from context.
4102 Immediate data @var{xx}. You may specify the @samp{:8} or @samp{:16}
4103 for clarity, if you wish; but @code{_AS__} neither requires this nor
4104 uses it---the data size required is taken from context.
4106 @item @code{@@}@code{@@}@var{aa}
4107 @itemx @code{@@}@code{@@}@var{aa}:8
4108 Memory indirect. You may specify the @samp{:8} for clarity, if you
4109 wish; but @code{_AS__} neither requires this nor uses it.
4112 @node H8/300 Floating Point, H8/300 Directives, H8/300 Syntax, H8/300-Dependent
4113 _CHAPSEC__(1+_GENERIC__) Floating Point
4115 @cindex floating point, H8/300 (@sc{ieee})
4116 @cindex H8/300 floating point (@sc{ieee})
4117 The H8/300 family uses @sc{ieee} floating-point numbers.
4119 @node H8/300 Directives, H8/300 Opcodes, H8/300 Floating Point, H8/300-Dependent
4120 _CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives
4122 @cindex H8/300 machine directives (none)
4123 @cindex machine directives, H8/300 (none)
4124 @cindex @code{word} directive, H8/300
4125 @cindex @code{int} directive, H8/300
4126 @code{_AS__} has no machine-dependent directives for the H8/300.
4127 However, on this platform the @samp{.int} and @samp{.word} directives
4128 generate 16-bit numbers.
4130 @node H8/300 Opcodes, , H8/300 Directives, H8/300-Dependent
4131 _CHAPSEC__(1+_GENERIC__) Opcodes
4133 @cindex H8/300 opcode summary
4134 @cindex opcode summary, H8/300
4135 @cindex mnemonics, H8/300
4136 @cindex instruction summary, H8/300
4137 For detailed information on the H8/300 machine instruction set, see
4138 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025).
4140 @code{_AS__} implements all the standard H8/300 opcodes. No additional
4141 pseudo-instructions are needed on this family.
4143 The following table summarizes the opcodes and their arguments:
4144 @c kluge due to lack of group outside example
4148 Rs @r{source register}
4149 Rd @r{destination register}
4150 imm @r{immediate data}
4151 x:3 @r{a bit (as a number between 0 and 7)}
4152 d:8 @r{eight bit displacement from @code{pc}}
4153 d:16 @r{sixteen bit displacement from @code{Rs}}
4155 add.b Rs,Rd biand #x:3,Rd
4156 add.b #imm:8,Rd biand #x:3,@@Rd
4157 add.w Rs,Rd biand #x:3,@@aa:8
4158 adds #1,Rd bild #x:3,Rd
4159 adds #2,Rd bild #x:3,@@Rd
4160 addx #imm:8,Rd bild #x:3,@@aa:8
4161 addx Rs,Rd bior #x:3,Rd
4162 and #imm:8,Rd bior #x:3,@@Rd
4163 and Rs,Rd bior #x:3,@@aa:8
4164 andc #imm:8,ccr bist #x:3,Rd
4165 band #x:3,Rd bist #x:3,@@Rd
4166 band #x:3,@@Rd bist #x:3,@@aa:8
4167 bra d:8 bixor #x:3,Rd
4168 bt d:8 bixor #x:3,@@Rd
4169 brn d:8 bixor #x:3,@@aa:8
4171 bhi d:8 bld #x:3,@@Rd
4172 bls d:8 bld #x:3,@@aa:8
4173 bcc d:8 bnot #x:3,Rd
4174 bhs d:8 bnot #x:3,@@Rd
4175 bcs d:8 bnot #x:3,@@aa:8
4177 bne d:8 bnot Rs,@@Rd
4178 beq d:8 bnot Rs,@@aa:8
4180 bvs d:8 bor #x:3,@@Rd
4181 bpl d:8 bor #x:3,@@aa:8
4182 bmi d:8 bset #x:3,@@Rd
4183 bge d:8 bset #x:3,@@aa:8
4185 bgt d:8 bset Rs,@@Rd
4186 ble d:8 bset Rs,@@aa:8
4187 bclr #x:3,Rd bsr d:8
4188 bclr #x:3,@@Rd bst #x:3,Rd
4189 bclr #x:3,@@aa:8 bst #x:3,@@Rd
4190 bclr Rs,Rd bst #x:3,@@aa:8
4191 bclr Rs,@@Rd btst #x:3,Rd
4194 btst #x:3,@@Rd mov.w @@(d:16, Rs),Rd
4195 btst #x:3,@@aa:8 mov.w @@Rs+,Rd
4196 btst Rs,Rd mov.w @@aa:16,Rd
4197 btst Rs,@@Rd mov.w Rs,@@Rd
4198 btst Rs,@@aa:8 mov.w Rs,@@(d:16, Rd)
4199 bxor #x:3,Rd mov.w Rs,@@-Rd
4200 bxor #x:3,@@Rd mov.w Rs,@@aa:16
4201 bxor #x:3,@@aa:8 movfpe @@aa:16,Rd
4202 cmp.b #imm:8,Rd movtpe Rs,@@aa:16
4203 cmp.b Rs,Rd mulxu Rs,Rd
4208 divxu Rs,Rd or Rs,Rd
4209 eepmov orc #imm:8,ccr
4215 jsr @@aa:16 rotxr Rs
4220 mov.b #imm:8,Rd shll Rs
4221 mov.b @@Rs,Rd shlr Rs
4222 mov.b @@(d:16, Rs),Rd sleep
4223 mov.b @@Rs+,Rd stc ccr,Rd
4224 mov.b @@aa:16,Rd sub.b Rs,Rd
4225 mov.b @@aa:8,Rd sub.w Rs,Rd
4226 mov.b Rs,@@Rd subs #1,Rd
4227 mov.b Rs,@@(d:16, Rd) subs #2,Rd
4228 mov.b Rs,@@-Rd subx #imm:8,Rd
4229 mov.b Rs,@@aa:16 subx Rs,Rd
4230 mov.b Rs,@@aa:8 xor #imm:8,Rd
4231 mov.w Rs,Rd xor Rs,Rd
4232 mov.w #imm:16,Rd xorc #imm:8,ccr
4237 @cindex size suffixes, H8/300
4238 @cindex H8/300 size suffixes
4239 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4240 @code{sub}) are defined with variants using the suffixes @samp{.b} and
4241 @samp{.w} to specify the size of a memory operand. @code{_AS__}
4242 supports these suffixes, but does not require them; since one of the
4243 operands is always a register, @code{_AS__} can deduce the correct size.
4245 For example, since @code{r0} refers to a 16-bit register,
4248 @exdent is equivalent to
4252 If you use the size suffixes, @code{_AS__} will issue a warning if
4253 there's a mismatch between the suffix and the register size.
4258 @node i960-Dependent, M68K-Dependent, H8/300-Dependent, Machine Dependent
4260 _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features
4262 @cindex i960 support
4264 * Options-i960:: i960 Command-line Options
4265 * Floating Point-i960:: Floating Point
4266 * Directives-i960:: i960 Machine Directives
4267 * Opcodes for i960:: i960 Opcodes
4270 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
4271 @c long as they're not turned on for other machines than 960.
4272 @node Options-i960, Floating Point-i960, i960-Dependent, i960-Dependent
4274 _CHAPSEC__(1+_GENERIC__) i960 Command-line Options
4276 @cindex i960 options
4277 @cindex options, i960
4280 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
4281 @cindex i960 architecture options
4282 @cindex architecture options, i960
4283 @cindex @code{-A} options, i960
4284 Select the 80960 architecture. Instructions or features not supported
4285 by the selected architecture cause fatal errors.
4287 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
4288 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
4290 If none of these options is specified, @code{_AS__} will generate code for any
4291 instruction or feature that is supported by @emph{some} version of the
4292 960 (even if this means mixing architectures!). In principle,
4293 @code{_AS__} will attempt to deduce the minimal sufficient processor
4294 type if none is specified; depending on the object code format, the
4295 processor type may be recorded in the object file. If it is critical
4296 that the @code{_AS__} output match a specific architecture, specify that
4297 architecture explicitly.
4300 @cindex @code{-b} option, i960
4301 @cindex branch recording, i960
4302 @cindex i960 branch recording
4303 Add code to collect information about conditional branches taken, for
4304 later optimization using branch prediction bits. (The conditional branch
4305 instructions have branch prediction bits in the CA, CB, and CC
4306 architectures.) If @var{BR} represents a conditional branch instruction,
4307 the following represents the code generated by the assembler when
4308 @samp{-b} is specified:
4311 call @var{increment routine}
4312 .word 0 # pre-counter
4314 call @var{increment routine}
4315 .word 0 # post-counter
4318 The counter following a branch records the number of times that branch
4319 was @emph{not} taken; the differenc between the two counters is the
4320 number of times the branch @emph{was} taken.
4322 @cindex @code{gbr960}, i960 postprocessor
4323 @cindex branch statistics table, i960
4324 A table of every such @code{Label} is also generated, so that the
4325 external postprocessor @code{gbr960} (supplied by Intel) can locate all
4326 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
4327 this is a local symbol to permit collecting statistics for many separate
4328 object files. The table is word aligned, and begins with a two-word
4329 header. The first word, initialized to 0, is used in maintaining linked
4330 lists of branch tables. The second word is a count of the number of
4331 entries in the table, which follow immediately: each is a word, pointing
4332 to one of the labels illustrated above.
4336 @c END TEXI2ROFF-KILL
4338 +------------+------------+------------+ ... +------------+
4340 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
4342 +------------+------------+------------+ ... +------------+
4344 __BRANCH_TABLE__ layout
4350 \line{\leftskip=0pt\hskip\tableindent
4351 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
4352 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
4353 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
4355 @c END TEXI2ROFF-KILL
4357 The first word of the header is used to locate multiple branch tables,
4358 since each object file may contain one. Normally the links are
4359 maintained with a call to an initialization routine, placed at the
4360 beginning of each function in the file. The GNU C compiler will
4361 generate these calls automatically when you give it a @samp{-b} option.
4362 For further details, see the documentation of @samp{gbr960}.
4365 @cindex @code{-norelax} option, i960
4366 Normally, Compare-and-Branch instructions with targets that require
4367 displacements greater than 13 bits (or that have external targets) are
4368 replaced with the corresponding compare (or @samp{chkbit}) and branch
4369 instructions. You can use the @samp{-norelax} option to specify that
4370 @code{_AS__} should generate errors instead, if the target displacement
4371 is larger than 13 bits.
4373 This option does not affect the Compare-and-Jump instructions; the code
4374 emitted for them is @emph{always} adjusted when necessary (depending on
4375 displacement size), regardless of whether you use @samp{-norelax}.
4378 @node Floating Point-i960, Directives-i960, Options-i960, i960-Dependent
4379 _CHAPSEC__(1+_GENERIC__) Floating Point
4381 @cindex floating point, i960 (@sc{ieee})
4382 @cindex i960 floating point (@sc{ieee})
4383 @code{_AS__} generates @sc{ieee} floating-point numbers for the directives
4384 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
4386 @node Directives-i960, Opcodes for i960, Floating Point-i960, i960-Dependent
4387 _CHAPSEC__(1+_GENERIC__) i960 Machine Directives
4389 @cindex machine directives, i960
4390 @cindex i960 machine directives
4393 @cindex @code{bss} directive, i960
4394 @item .bss @var{symbol}, @var{length}, @var{align}
4395 Reserve @var{length} bytes in the bss section for a local @var{symbol},
4396 aligned to the power of two specified by @var{align}. @var{length} and
4397 @var{align} must be positive absolute expressions. This directive
4398 differs from @samp{.lcomm} only in that it permits you to specify
4399 an alignment. @xref{Lcomm,,@code{.lcomm}}.
4403 @item .extended @var{flonums}
4404 @cindex @code{extended} directive, i960
4405 @code{.extended} expects zero or more flonums, separated by commas; for
4406 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
4407 floating-point number.
4409 @item .leafproc @var{call-lab}, @var{bal-lab}
4410 @cindex @code{leafproc} directive, i960
4411 You can use the @samp{.leafproc} directive in conjunction with the
4412 optimized @code{callj} instruction to enable faster calls of leaf
4413 procedures. If a procedure is known to call no other procedures, you
4414 may define an entry point that skips procedure prolog code (and that does
4415 not depend on system-supplied saved context), and declare it as the
4416 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
4417 entry point that goes through the normal prolog, you can specify that
4418 entry point as @var{call-lab}.
4420 A @samp{.leafproc} declaration is meant for use in conjunction with the
4421 optimized call instruction @samp{callj}; the directive records the data
4422 needed later to choose between converting the @samp{callj} into a
4423 @code{bal} or a @code{call}.
4425 @var{call-lab} is optional; if only one argument is present, or if the
4426 two arguments are identical, the single argument is assumed to be the
4427 @code{bal} entry point.
4429 @item .sysproc @var{name}, @var{index}
4430 @cindex @code{sysproc} directive, i960
4431 The @samp{.sysproc} directive defines a name for a system procedure.
4432 After you define it using @samp{.sysproc}, you can use @var{name} to
4433 refer to the system procedure identified by @var{index} when calling
4434 procedures with the optimized call instruction @samp{callj}.
4436 Both arguments are required; @var{index} must be between 0 and 31
4440 @node Opcodes for i960, , Directives-i960, i960-Dependent
4441 _CHAPSEC__(1+_GENERIC__) i960 Opcodes
4443 @cindex opcodes, i960
4444 @cindex i960 opcodes
4445 All Intel 960 machine instructions are supported;
4446 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
4447 selecting the instruction subset for a particular 960
4448 architecture.@refill
4450 Some opcodes are processed beyond simply emitting a single corresponding
4451 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
4452 instructions with target displacements larger than 13 bits.
4455 * callj-i960:: @code{callj}
4456 * Compare-and-branch-i960:: Compare-and-Branch
4459 @node callj-i960, Compare-and-branch-i960, Opcodes for i960, Opcodes for i960
4460 _CHAPSEC__(2+_GENERIC__) @code{callj}
4462 @cindex @code{callj}, i960 pseudo-opcode
4463 @cindex i960 @code{callj} pseudo-opcode
4464 You can write @code{callj} to have the assembler or the linker determine
4465 the most appropriate form of subroutine call: @samp{call},
4466 @samp{bal}, or @samp{calls}. If the assembly source contains
4467 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
4468 defining the operand---then @code{_AS__} will translate the
4469 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
4470 for the linker to resolve.
4472 @node Compare-and-branch-i960, , callj-i960, Opcodes for i960
4473 _CHAPSEC__(2+_GENERIC__) Compare-and-Branch
4475 @cindex i960 compare/branch instructions
4476 @cindex compare/branch instructions, i960
4477 The 960 architectures provide combined Compare-and-Branch instructions
4478 that permit you to store the branch target in the lower 13 bits of the
4479 instruction word itself. However, if you specify a branch target far
4480 enough away that its address won't fit in 13 bits, the assembler can
4481 either issue an error, or convert your Compare-and-Branch instruction
4482 into separate instructions to do the compare and the branch.
4484 @cindex compare and jump expansions, i960
4485 @cindex i960 compare and jump expansions
4486 Whether @code{_AS__} gives an error or expands the instruction depends
4487 on two choices you can make: whether you use the @samp{-norelax} option,
4488 and whether you use a ``Compare and Branch'' instruction or a ``Compare
4489 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
4490 expanded if necessary; the ``Branch'' instructions are expanded when
4491 necessary @emph{unless} you specify @code{-norelax}---in which case
4492 @code{_AS__} gives an error instead.
4494 These are the Compare-and-Branch instructions, their ``Jump'' variants,
4495 and the instruction pairs they may expand into:
4499 @c END TEXI2ROFF-KILL
4502 Branch Jump Expanded to
4503 ------ ------ ------------
4506 cmpibe cmpije cmpi; be
4507 cmpibg cmpijg cmpi; bg
4508 cmpibge cmpijge cmpi; bge
4509 cmpibl cmpijl cmpi; bl
4510 cmpible cmpijle cmpi; ble
4511 cmpibno cmpijno cmpi; bno
4512 cmpibne cmpijne cmpi; bne
4513 cmpibo cmpijo cmpi; bo
4514 cmpobe cmpoje cmpo; be
4515 cmpobg cmpojg cmpo; bg
4516 cmpobge cmpojge cmpo; bge
4517 cmpobl cmpojl cmpo; bl
4518 cmpoble cmpojle cmpo; ble
4519 cmpobne cmpojne cmpo; bne
4525 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
4526 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
4527 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
4528 bbc& & chkbit; bno\cr
4529 bbs& & chkbit; bo\cr
4530 cmpibe& cmpije& cmpi; be\cr
4531 cmpibg& cmpijg& cmpi; bg\cr
4532 cmpibge& cmpijge& cmpi; bge\cr
4533 cmpibl& cmpijl& cmpi; bl\cr
4534 cmpible& cmpijle& cmpi; ble\cr
4535 cmpibno& cmpijno& cmpi; bno\cr
4536 cmpibne& cmpijne& cmpi; bne\cr
4537 cmpibo& cmpijo& cmpi; bo\cr
4538 cmpobe& cmpoje& cmpo; be\cr
4539 cmpobg& cmpojg& cmpo; bg\cr
4540 cmpobge& cmpojge& cmpo; bge\cr
4541 cmpobl& cmpojl& cmpo; bl\cr
4542 cmpoble& cmpojle& cmpo; ble\cr
4543 cmpobne& cmpojne& cmpo; bne\cr}
4545 @c END TEXI2ROFF-KILL
4550 @c FIXME! node conds are only sufficient for m68k alone, all, and vintage
4552 @node M68K-Dependent, Sparc-Dependent, i960-Dependent, Machine Dependent
4555 @node M68K-Dependent, Sparc-Dependent, Machine Dependent, Machine Dependent
4558 _CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features
4560 @cindex M680x0 support
4562 * M68K-Opts:: M680x0 Options
4563 * M68K-Syntax:: Syntax
4564 * M68K-Float:: Floating Point
4565 * M68K-Directives:: 680x0 Machine Directives
4566 * M68K-opcodes:: Opcodes
4569 @node M68K-Opts, M68K-Syntax, M68K-Dependent, M68K-Dependent
4570 _CHAPSEC__(1+_GENERIC__) M680x0 Options
4572 @cindex options, M680x0
4573 @cindex M680x0 options
4574 The Motorola 680x0 version of @code{_AS__} has two machine dependent options.
4575 One shortens undefined references from 32 to 16 bits, while the
4576 other is used to tell @code{_AS__} what kind of machine it is
4579 @cindex @code{-l} option, M680x0
4580 You can use the @kbd{-l} option to shorten the size of references to
4581 undefined symbols. If the @kbd{-l} option is not given, references to
4582 undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__}
4583 cannot know where these symbols will end up, @code{_AS__} can only allocate
4584 space for the linker to fill in later. Since @code{_AS__} doesn't know how
4585 far away these symbols will be, it allocates as much space as it can.)
4586 If this option is given, the references will only be one word wide (16
4587 bits). This may be useful if you want the object file to be as small as
4588 possible, and you know that the relevant symbols will be less than 17
4591 @cindex @code{-m68000} and related options
4592 @cindex architecture options, M680x0
4593 @cindex M680x0 architecture options
4594 The 680x0 version of @code{_AS__} is most frequently used to assemble
4595 programs for the Motorola MC68020 microprocessor. Occasionally it is
4596 used to assemble programs for the mostly similar, but slightly different
4597 MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options
4598 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
4599 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
4602 @node M68K-Syntax, M68K-Float, M68K-Opts, M68K-Dependent
4603 _CHAPSEC__(1+_GENERIC__) Syntax
4605 @cindex M680x0 syntax
4606 @cindex syntax, M680x0
4607 @cindex M680x0 size modifiers
4608 @cindex size modifiers, M680x0
4609 The 680x0 version of @code{_AS__} uses syntax similar to the Sun assembler.
4610 Size modifiers are appended directly to the end of the opcode without an
4611 intervening period. For example, write @samp{movl} rather than
4615 If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow
4616 Sun-style local labels of the form @samp{1$} through @samp{$9}.
4619 In the following table @dfn{apc} stands for any of the address
4620 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
4621 Program Counter (@samp{pc}), or the zero-address relative to the
4622 program counter (@samp{zpc}).
4624 @cindex M680x0 addressing modes
4625 @cindex addressing modes, M680x0
4626 The following addressing modes are understood:
4629 @samp{#@var{digits}}
4632 @samp{d0} through @samp{d7}
4634 @item Address Register
4635 @samp{a0} through @samp{a7}
4637 @item Address Register Indirect
4638 @samp{a0@@} through @samp{a7@@}
4640 @item Address Register Postincrement
4641 @samp{a0@@+} through @samp{a7@@+}
4643 @item Address Register Predecrement
4644 @samp{a0@@-} through @samp{a7@@-}
4646 @item Indirect Plus Offset
4647 @samp{@var{apc}@@(@var{digits})}
4650 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4652 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
4655 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4657 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
4660 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4662 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4664 @item Memory Indirect
4665 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
4668 @samp{@var{symbol}}, or @samp{@var{digits}}
4670 @c pesch@cygnus.com: gnu, rich concur the following needs careful
4671 @c research before documenting.
4672 , or either of the above followed
4673 by @samp{:b}, @samp{:w}, or @samp{:l}.
4677 @node M68K-Float, M68K-Directives, M68K-Syntax, M68K-Dependent
4678 _CHAPSEC__(1+_GENERIC__) Floating Point
4680 @cindex floating point, M680x0
4681 @cindex M680x0 floating point
4682 @c FIXME is this "not too well tested" crud STILL true?
4683 The floating point code is not too well tested, and may have
4686 Packed decimal (P) format floating literals are not supported.
4687 Feel free to add the code!
4689 The floating point formats generated by directives are these.
4693 @cindex @code{float} directive, M680x0
4694 @code{Single} precision floating point constants.
4697 @cindex @code{double} directive, M680x0
4698 @code{Double} precision floating point constants.
4701 There is no directive to produce regions of memory holding
4702 extended precision numbers, however they can be used as
4703 immediate operands to floating-point instructions. Adding a
4704 directive to create extended precision numbers would not be
4705 hard, but it has not yet seemed necessary.
4707 @node M68K-Directives, M68K-opcodes, M68K-Float, M68K-Dependent
4708 _CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives
4710 @cindex M680x0 directives
4711 @cindex directives, M680x0
4712 In order to be compatible with the Sun assembler the 680x0 assembler
4713 understands the following directives.
4717 @cindex @code{data1} directive, M680x0
4718 This directive is identical to a @code{.data 1} directive.
4721 @cindex @code{data2} directive, M680x0
4722 This directive is identical to a @code{.data 2} directive.
4725 @cindex @code{even} directive, M680x0
4726 This directive is identical to a @code{.align 1} directive.
4727 @c Is this true? does it work???
4730 @cindex @code{skip} directive, M680x0
4731 This directive is identical to a @code{.space} directive.
4734 @node M68K-opcodes, , M68K-Directives, M68K-Dependent
4735 _CHAPSEC__(1+_GENERIC__) Opcodes
4737 @cindex M680x0 opcodes
4738 @cindex opcodes, M680x0
4739 @cindex instruction set, M680x0
4740 @c pesch@cygnus.com: I don't see any point in the following
4741 @c paragraph. Bugs are bugs; how does saying this
4744 Danger: Several bugs have been found in the opcode table (and
4745 fixed). More bugs may exist. Be careful when using obscure
4750 * M68K-Branch:: Branch Improvement
4751 * M68K-Chars:: Special Characters
4754 @node M68K-Branch, M68K-Chars, M68K-opcodes, M68K-opcodes
4755 _CHAPSEC__(2+_GENERIC__) Branch Improvement
4757 @cindex pseudo-opcodes, M680x0
4758 @cindex M680x0 pseudo-opcodes
4759 @cindex branch improvement, M680x0
4760 @cindex M680x0 branch improvement
4761 Certain pseudo opcodes are permitted for branch instructions.
4762 They expand to the shortest branch instruction that will reach the
4763 target. Generally these mnemonics are made by substituting @samp{j} for
4764 @samp{b} at the start of a Motorola mnemonic.
4766 The following table summarizes the pseudo-operations. A @code{*} flags
4767 cases that are more fully described after the table:
4771 +-------------------------------------------------
4773 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
4774 +-------------------------------------------------
4775 jbsr |bsrs bsr bsrl jsr jsr
4776 jra |bras bra bral jmp jmp
4777 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
4778 * dbXX |dbXX dbXX dbXX; bra; jmpl
4779 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
4782 NX: negative of condition XX
4785 @center @code{*}---see full description below
4790 These are the simplest jump pseudo-operations; they always map to one
4791 particular machine instruction, depending on the displacement to the
4795 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
4796 where @var{XX} is a conditional branch or condition-code test. The full
4797 list of pseudo-ops in this family is:
4799 jhi jls jcc jcs jne jeq jvc
4800 jvs jpl jmi jge jlt jgt jle
4803 For the cases of non-PC relative displacements and long displacements on
4804 the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of
4805 @var{NX}, the opposite condition to @var{XX}:
4817 The full family of pseudo-operations covered here is
4819 dbhi dbls dbcc dbcs dbne dbeq dbvc
4820 dbvs dbpl dbmi dbge dblt dbgt dble
4824 Other than for word and byte displacements, when the source reads
4825 @samp{db@var{XX} foo}, @code{_AS__} will emit
4834 This family includes
4836 fjne fjeq fjge fjlt fjgt fjle fjf
4837 fjt fjgl fjgle fjnge fjngl fjngle fjngt
4838 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
4839 fjor fjseq fjsf fjsne fjst fjueq fjuge
4840 fjugt fjule fjult fjun
4843 For branch targets that are not PC relative, @code{_AS__} emits
4849 when it encounters @samp{fj@var{XX} foo}.
4853 @node M68K-Chars, , M68K-Branch, M68K-opcodes
4854 _CHAPSEC__(2+_GENERIC__) Special Characters
4856 @cindex special characters, M680x0
4857 @cindex M680x0 immediate character
4858 @cindex immediate character, M680x0
4859 @cindex M680x0 line comment character
4860 @cindex line comment character, M680x0
4861 @cindex comments, M680x0
4862 The immediate character is @samp{#} for Sun compatibility. The
4863 line-comment character is @samp{|}. If a @samp{#} appears at the
4864 beginning of a line, it is treated as a comment unless it looks like
4865 @samp{# line file}, in which case it is treated normally.
4869 @c pesch@cygnus.com: conditionalize on something other than 0 when filled in.
4872 The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to
4873 specify thiat it is compiling for a 32032 processor, or a
4874 @kbd{-m32532} to specify that it is compiling for a 32532 option.
4875 The default (if neither is specified) is chosen when the assembler
4879 I don't know anything about the 32x32 syntax assembled by
4880 @code{_AS__}. Someone who undersands the processor (I've never seen
4881 one) and the possible syntaxes should write this section.
4883 @subsection Floating Point
4884 The 32x32 uses @sc{ieee} floating point numbers, but @code{_AS__} will only
4885 create single or double precision values. I don't know if the 32x32
4886 understands extended precision numbers.
4888 @subsection 32x32 Machine Directives
4889 The 32x32 has no machine dependent directives.
4894 _if__(_I80386__&&_M680X0__)
4895 @node Sparc-Dependent, i386-Dependent, M68K-Dependent, Machine Dependent
4896 _fi__(_I80386__&&_M680X0__)
4897 _if__(_I80386__&&_I960__&&!_M680X0__)
4898 @node Sparc-Dependent, i386-Dependent, i960-Dependent, Machine Dependent
4899 _fi__(_I80386__&&_I960__&&!_M680X0__)
4900 _if__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
4901 @node Sparc-Dependent, i386-Dependent, AMD29K-Dependent, Machine Dependent
4902 _fi__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
4903 _if__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4904 @node Sparc-Dependent, i386-Dependent, Vax-Dependent, Machine Dependent
4905 _fi__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4906 _if__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4907 @node Sparc-Dependent, i386-Dependent, Machine Dependent, Machine Dependent
4908 _fi__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4909 _if__((!_I80386__)&&_M680X0__)
4910 @node Sparc-Dependent, , M68K-Dependent, Machine Dependent
4911 _fi__((!_I80386__)&&_M680X0__)
4912 _if__((!_I80386__)&&_I960__&&!_M680X0__)
4913 @node Sparc-Dependent, , i960-Dependent, Machine Dependent
4914 _fi__((!_I80386__)&&_I960__&&!_M680X0__)
4915 _if__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
4916 @node Sparc-Dependent, , AMD29K-Dependent, Machine Dependent
4917 _fi__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
4918 _if__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4919 @node Sparc-Dependent, , Vax-Dependent, Machine Dependent
4920 _fi__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4921 _if__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4922 @node Sparc-Dependent, , Machine Dependent, Machine Dependent
4923 _fi__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4925 _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features
4927 @cindex SPARC support
4929 * Sparc-Opts:: Options
4930 * Sparc-Float:: Floating Point
4931 * Sparc-Directives:: Sparc Machine Directives
4934 @node Sparc-Opts, Sparc-Float, Sparc-Dependent, Sparc-Dependent
4935 _CHAPSEC__(1+_GENERIC__) Options
4937 @cindex options for SPARC (none)
4938 @cindex SPARC options (none)
4939 The Sparc has no machine dependent options.
4942 @c FIXME: (sparc) Fill in "syntax" section!
4943 @c subsection syntax
4944 I don't know anything about Sparc syntax. Someone who does
4945 will have to write this section.
4948 @node Sparc-Float, Sparc-Directives, Sparc-Opts, Sparc-Dependent
4949 _CHAPSEC__(1+_GENERIC__) Floating Point
4951 @cindex floating point, SPARC (@sc{ieee})
4952 @cindex SPARC floating point (@sc{ieee})
4953 The Sparc uses @sc{ieee} floating-point numbers.
4955 @node Sparc-Directives, , Sparc-Float, Sparc-Dependent
4956 _CHAPSEC__(1+_GENERIC__) Sparc Machine Directives
4958 @cindex SPARC machine directives
4959 @cindex machine directives, SPARC
4960 The Sparc version of @code{_AS__} supports the following additional
4965 @cindex @code{common} directive, SPARC
4966 This must be followed by a symbol name, a positive number, and
4967 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
4968 syntax is different.
4971 @cindex @code{half} directive, SPARC
4972 This is functionally identical to @code{.short}.
4975 @cindex @code{proc} directive, SPARC
4976 This directive is ignored. Any text following it on the same
4977 line is also ignored.
4980 @cindex @code{reserve} directive, SPARC
4981 This must be followed by a symbol name, a positive number, and
4982 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
4983 syntax is different.
4986 @cindex @code{seg} directive, SPARC
4987 This must be followed by @code{"text"}, @code{"data"}, or
4988 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
4992 @cindex @code{skip} directive, SPARC
4993 This is functionally identical to the @code{.space} directive.
4996 @cindex @code{word} directive, SPARC
4997 On the Sparc, the .word directive produces 32 bit values,
4998 instead of the 16 bit values it produces on many other machines.
5004 @c FIXME! Conditionalize for all combinations in this section
5005 @node i386-Dependent, , Sparc-Dependent, Machine Dependent
5007 _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features
5009 @cindex i386 support
5010 @cindex i80306 support
5012 * i386-Options:: Options
5013 * i386-Syntax:: AT&T Syntax versus Intel Syntax
5014 * i386-Opcodes:: Opcode Naming
5015 * i386-Regs:: Register Naming
5016 * i386-prefixes:: Opcode Prefixes
5017 * i386-Memory:: Memory References
5018 * i386-jumps:: Handling of Jump Instructions
5019 * i386-Float:: Floating Point
5020 * i386-Notes:: Notes
5023 @node i386-Options, i386-Syntax, i386-Dependent, i386-Dependent
5024 _CHAPSEC__(1+_GENERIC__) Options
5026 @cindex options for i386 (none)
5027 @cindex i386 options (none)
5028 The 80386 has no machine dependent options.
5030 @node i386-Syntax, i386-Opcodes, i386-Options, i386-Dependent
5031 _CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax
5033 @cindex i386 syntax compatibility
5034 @cindex syntax compatibility, i386
5035 In order to maintain compatibility with the output of @code{_GCC__},
5036 @code{_AS__} supports AT&T System V/386 assembler syntax. This is quite
5037 different from Intel syntax. We mention these differences because
5038 almost all 80386 documents used only Intel syntax. Notable differences
5039 between the two syntaxes are:
5043 @cindex immediate operands, i386
5044 @cindex i386 immediate operands
5045 @cindex register operands, i386
5046 @cindex i386 register operands
5047 @cindex jump/call operands, i386
5048 @cindex i386 jump/call operands
5049 @cindex operand delimiters, i386
5050 AT&T immediate operands are preceded by @samp{$}; Intel immediate
5051 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
5052 AT&T register operands are preceded by @samp{%}; Intel register operands
5053 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
5054 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
5057 @cindex i386 source, destination operands
5058 @cindex source, destination operands; i386
5059 AT&T and Intel syntax use the opposite order for source and destination
5060 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
5061 @samp{source, dest} convention is maintained for compatibility with
5062 previous Unix assemblers.
5065 @cindex opcode suffixes, i386
5066 @cindex sizes operands, i386
5067 @cindex i386 size suffixes
5068 In AT&T syntax the size of memory operands is determined from the last
5069 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
5070 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
5071 memory references. Intel syntax accomplishes this by prefixes memory
5072 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
5073 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
5074 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
5077 @cindex return instructions, i386
5078 @cindex i386 jump, call, return
5079 Immediate form long jumps and calls are
5080 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
5082 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
5084 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
5085 @samp{ret far @var{stack-adjust}}.
5088 @cindex sections, i386
5089 @cindex i386 sections
5090 The AT&T assembler does not provide support for multiple section
5091 programs. Unix style systems expect all programs to be single sections.
5094 @node i386-Opcodes, i386-Regs, i386-Syntax, i386-Dependent
5095 _CHAPSEC__(1+_GENERIC__) Opcode Naming
5097 @cindex i386 opcode naming
5098 @cindex opcode naming, i386
5099 Opcode names are suffixed with one character modifiers which specify the
5100 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
5101 byte, word, and long operands. If no suffix is specified by an
5102 instruction and it contains no memory operands then @code{_AS__} tries to
5103 fill in the missing suffix based on the destination register operand
5104 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
5105 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
5106 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
5107 assembler which assumes that a missing opcode suffix implies long
5108 operand size. (This incompatibility does not affect compiler output
5109 since compilers always explicitly specify the opcode suffix.)
5111 Almost all opcodes have the same names in AT&T and Intel format. There
5112 are a few exceptions. The sign extend and zero extend instructions need
5113 two sizes to specify them. They need a size to sign/zero extend
5114 @emph{from} and a size to zero extend @emph{to}. This is accomplished
5115 by using two opcode suffixes in AT&T syntax. Base names for sign extend
5116 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
5117 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
5118 suffixes are tacked on to this base name, the @emph{from} suffix before
5119 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
5120 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
5121 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
5122 and @samp{wl} (from word to long).
5124 @cindex conversion instructions, i386
5125 @cindex i386 conversion instructions
5126 The Intel-syntax conversion instructions
5130 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
5133 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
5136 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
5139 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
5143 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
5144 AT&T naming. @code{_AS__} accepts either naming for these instructions.
5146 @cindex jump instructions, i386
5147 @cindex call instructions, i386
5148 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
5149 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
5152 @node i386-Regs, i386-prefixes, i386-Opcodes, i386-Dependent
5153 _CHAPSEC__(1+_GENERIC__) Register Naming
5155 @cindex i386 registers
5156 @cindex registers, i386
5157 Register operands are always prefixes with @samp{%}. The 80386 registers
5162 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
5163 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
5164 frame pointer), and @samp{%esp} (the stack pointer).
5167 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
5168 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
5171 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
5172 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
5173 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
5174 @samp{%cx}, and @samp{%dx})
5177 the 6 section registers @samp{%cs} (code section), @samp{%ds}
5178 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
5182 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
5186 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
5187 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
5190 the 2 test registers @samp{%tr6} and @samp{%tr7}.
5193 the 8 floating point register stack @samp{%st} or equivalently
5194 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
5195 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
5198 @node i386-prefixes, i386-Memory, i386-Regs, i386-Dependent
5199 _CHAPSEC__(1+_GENERIC__) Opcode Prefixes
5201 @cindex i386 opcode prefixes
5202 @cindex opcode prefixes, i386
5203 @cindex prefixes, i386
5204 Opcode prefixes are used to modify the following opcode. They are used
5205 to repeat string instructions, to provide section overrides, to perform
5206 bus lock operations, and to give operand and address size (16-bit
5207 operands are specified in an instruction by prefixing what would
5208 normally be 32-bit operands with a ``operand size'' opcode prefix).
5209 Opcode prefixes are usually given as single-line instructions with no
5210 operands, and must directly precede the instruction they act upon. For
5211 example, the @samp{scas} (scan string) instruction is repeated with:
5217 Here is a list of opcode prefixes:
5221 @cindex section override prefixes, i386
5222 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
5223 @samp{fs}, @samp{gs}. These are automatically added by specifying
5224 using the @var{section}:@var{memory-operand} form for memory references.
5227 @cindex size prefixes, i386
5228 Operand/Address size prefixes @samp{data16} and @samp{addr16}
5229 change 32-bit operands/addresses into 16-bit operands/addresses. Note
5230 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
5231 are not supported (yet).
5234 @cindex bus lock prefixes, i386
5235 @cindex inhibiting interrupts, i386
5236 The bus lock prefix @samp{lock} inhibits interrupts during
5237 execution of the instruction it precedes. (This is only valid with
5238 certain instructions; see a 80386 manual for details).
5241 @cindex coprocessor wait, i386
5242 The wait for coprocessor prefix @samp{wait} waits for the
5243 coprocessor to complete the current instruction. This should never be
5244 needed for the 80386/80387 combination.
5247 @cindex repeat prefixes, i386
5248 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
5249 to string instructions to make them repeat @samp{%ecx} times.
5252 @node i386-Memory, i386-jumps, i386-prefixes, i386-Dependent
5253 _CHAPSEC__(1+_GENERIC__) Memory References
5255 @cindex i386 memory references
5256 @cindex memory references, i386
5257 An Intel syntax indirect memory reference of the form
5260 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
5264 is translated into the AT&T syntax
5267 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
5271 where @var{base} and @var{index} are the optional 32-bit base and
5272 index registers, @var{disp} is the optional displacement, and
5273 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
5274 to calculate the address of the operand. If no @var{scale} is
5275 specified, @var{scale} is taken to be 1. @var{section} specifies the
5276 optional section register for the memory operand, and may override the
5277 default section register (see a 80386 manual for section register
5278 defaults). Note that section overrides in AT&T syntax @emph{must} have
5279 be preceded by a @samp{%}. If you specify a section override which
5280 coincides with the default section register, @code{_AS__} will @emph{not}
5281 output any section register override prefixes to assemble the given
5282 instruction. Thus, section overrides can be specified to emphasize which
5283 section register is used for a given memory operand.
5285 Here are some examples of Intel and AT&T style memory references:
5288 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
5289 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
5290 missing, and the default section is used (@samp{%ss} for addressing with
5291 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
5293 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
5294 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
5295 @samp{foo}. All other fields are missing. The section register here
5296 defaults to @samp{%ds}.
5298 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
5299 This uses the value pointed to by @samp{foo} as a memory operand.
5300 Note that @var{base} and @var{index} are both missing, but there is only
5301 @emph{one} @samp{,}. This is a syntactic exception.
5303 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
5304 This selects the contents of the variable @samp{foo} with section
5305 register @var{section} being @samp{%gs}.
5308 Absolute (as opposed to PC relative) call and jump operands must be
5309 prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will
5310 always choose PC relative addressing for jump/call labels.
5312 Any instruction that has a memory operand @emph{must} specify its size (byte,
5313 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
5316 @node i386-jumps, i386-Float, i386-Memory, i386-Dependent
5317 _CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions
5319 @cindex jump optimization, i386
5320 @cindex i386 jump optimization
5321 Jump instructions are always optimized to use the smallest possible
5322 displacements. This is accomplished by using byte (8-bit) displacement
5323 jumps whenever the target is sufficiently close. If a byte displacement
5324 is insufficient a long (32-bit) displacement is used. We do not support
5325 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
5326 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
5327 @samp{%eip} to 16 bits after the word displacement is added.
5329 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
5330 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
5331 byte displacements, so that it is possible that use of these
5332 instructions (@code{_GCC__} does not use them) will cause the assembler to
5333 print an error message (and generate incorrect code). The AT&T 80386
5334 assembler tries to get around this problem by expanding @samp{jcxz foo} to
5342 @node i386-Float, i386-Notes, i386-jumps, i386-Dependent
5343 _CHAPSEC__(1+_GENERIC__) Floating Point
5345 @cindex i386 floating point
5346 @cindex floating point, i386
5347 All 80387 floating point types except packed BCD are supported.
5348 (BCD support may be added without much difficulty). These data
5349 types are 16-, 32-, and 64- bit integers, and single (32-bit),
5350 double (64-bit), and extended (80-bit) precision floating point.
5351 Each supported type has an opcode suffix and a constructor
5352 associated with it. Opcode suffixes specify operand's data
5353 types. Constructors build these data types into memory.
5357 @cindex @code{float} directive, i386
5358 @cindex @code{single} directive, i386
5359 @cindex @code{double} directive, i386
5360 @cindex @code{tfloat} directive, i386
5361 Floating point constructors are @samp{.float} or @samp{.single},
5362 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
5363 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
5364 @samp{t} stands for temporary real, and that the 80387 only supports
5365 this format via the @samp{fldt} (load temporary real to stack top) and
5366 @samp{fstpt} (store temporary real and pop stack) instructions.
5369 @cindex @code{word} directive, i386
5370 @cindex @code{long} directive, i386
5371 @cindex @code{int} directive, i386
5372 @cindex @code{quad} directive, i386
5373 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
5374 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
5375 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
5376 (quad). As with the temporary real format the 64-bit @samp{q} format is
5377 only present in the @samp{fildq} (load quad integer to stack top) and
5378 @samp{fistpq} (store quad integer and pop stack) instructions.
5381 Register to register operations do not require opcode suffixes,
5382 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
5384 @cindex i386 @code{fwait} instruction
5385 @cindex @code{fwait instruction}, i386
5386 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
5387 instructions are almost never needed (this is not the case for the
5388 80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses
5389 the @samp{fwait} instruction whenever it is implicitly selected by one
5390 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
5391 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
5392 instructions are made equivalent to @samp{f@dots{}} instructions. If
5393 @samp{fwait} is desired it must be explicitly coded.
5395 @node i386-Notes, , i386-Float, i386-Dependent
5396 _CHAPSEC__(1+_GENERIC__) Notes
5398 @cindex i386 @code{mul}, @code{imul} instructions
5399 @cindex @code{mul} instruction, i386
5400 @cindex @code{imul} instruction, i386
5401 There is some trickery concerning the @samp{mul} and @samp{imul}
5402 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
5403 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
5404 for @samp{imul}) can be output only in the one operand form. Thus,
5405 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
5406 the expanding multiply would clobber the @samp{%edx} register, and this
5407 would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the
5408 64-bit product in @samp{%edx:%eax}.
5410 We have added a two operand form of @samp{imul} when the first operand
5411 is an immediate mode expression and the second operand is a register.
5412 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
5413 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
5418 @c pesch@cygnus.com: we ignore the following chapters, since internals are
5419 @c changing rapidly. These may need to be moved to another
5420 @c book anyhow, if we adopt the model of user/modifier
5422 @node Maintenance, Retargeting, _MACH_DEP__, Top
5423 @chapter Maintaining the Assembler
5424 [[this chapter is still being built]]
5427 We had these goals, in descending priority:
5430 For every program composed by a compiler, @code{_AS__} should emit
5431 ``correct'' code. This leaves some latitude in choosing addressing
5432 modes, order of @code{relocation_info} structures in the object
5435 @item Speed, for usual case.
5436 By far the most common use of @code{_AS__} will be assembling compiler
5439 @item Upward compatibility for existing assembler code.
5440 Well @dots{} we don't support Vax bit fields but everything else
5441 seems to be upward compatible.
5444 The code should be maintainable with few surprises. (JF: ha!)
5448 We assumed that disk I/O was slow and expensive while memory was
5449 fast and access to memory was cheap. We expect the in-memory data
5450 structures to be less than 10 times the size of the emitted object
5451 file. (Contrast this with the C compiler where in-memory structures
5452 might be 100 times object file size!)
5456 Try to read the source file from disk only one time. For other
5457 reasons, we keep large chunks of the source file in memory during
5458 assembly so this is not a problem. Also the assembly algorithm
5459 should only scan the source text once if the compiler composed the
5460 text according to a few simple rules.
5462 Emit the object code bytes only once. Don't store values and then
5465 Build the object file in memory and do direct writes to disk of
5469 RMS suggested a one-pass algorithm which seems to work well. By not
5470 parsing text during a second pass considerable time is saved on
5471 large programs (@emph{e.g.} the sort of C program @code{yacc} would
5474 It happened that the data structures needed to emit relocation
5475 information to the object file were neatly subsumed into the data
5476 structures that do backpatching of addresses after pass 1.
5478 Many of the functions began life as re-usable modules, loosely
5479 connected. RMS changed this to gain speed. For example, input
5480 parsing routines which used to work on pre-sanitized strings now
5481 must parse raw data. Hence they have to import knowledge of the
5482 assemblers' comment conventions @emph{etc}.
5484 @section Deprecated Feature(?)s
5485 We have stopped supporting some features:
5488 @code{.org} statements must have @b{defined} expressions.
5490 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
5493 It might be a good idea to not support these features in a future release:
5496 @kbd{#} should begin a comment, even in column 1.
5498 Why support the logical line & file concept any more?
5500 Subsections are a good candidate for flushing.
5501 Depends on which compilers need them I guess.
5504 @section Bugs, Ideas, Further Work
5505 Clearly the major improvement is DON'T USE A TEXT-READING
5506 ASSEMBLER for the back end of a compiler. It is much faster to
5507 interpret binary gobbledygook from a compiler's tables than to
5508 ask the compiler to write out human-readable code just so the
5509 assembler can parse it back to binary.
5511 Assuming you use @code{_AS__} for human written programs: here are
5515 Document (here) @code{APP}.
5517 Take advantage of knowing no spaces except after opcode
5518 to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces:
5519 only keep space/tabs at begin of line or between 2
5522 Put pointers in this documentation to @file{a.out} documentation.
5524 Split the assembler into parts so it can gobble direct binary
5525 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
5526 just so @code{_AS__} can parse it back to binary.
5528 Rewrite hash functions: I want a more modular, faster library.
5530 Clean up LOTS of code.
5532 Include all the non-@file{.c} files in the maintenance chapter.
5536 Implement flonum short literals.
5538 Change all talk of expression operands to expression quantities,
5539 or perhaps to expression arguments.
5543 Whenever a @code{.text} or @code{.data} statement is seen, we close
5544 of the current frag with an imaginary @code{.fill 0}. This is
5545 because we only have one obstack for frags, and we can't grow new
5546 frags for a new subsection, then go back to the old subsection and
5547 append bytes to the old frag. All this nonsense goes away if we
5548 give each subsection its own obstack. It makes code simpler in
5549 about 10 places, but nobody has bothered to do it because C compiler
5550 output rarely changes subsections (compared to ending frags with
5551 relaxable addresses, which is common).
5555 @c The following files in the @file{_AS__} directory
5556 @c are symbolic links to other files, of
5557 @c the same name, in a different directory.
5560 @c @file{atof_generic.c}
5562 @c @file{atof_vax.c}
5564 @c @file{flonum_const.c}
5566 @c @file{flonum_copy.c}
5568 @c @file{flonum_get.c}
5570 @c @file{flonum_multip.c}
5572 @c @file{flonum_normal.c}
5574 @c @file{flonum_print.c}
5577 Here is a list of the source files in the @file{_AS__} directory.
5581 This contains the pre-processing phase, which deletes comments,
5582 handles whitespace, etc. This was recently re-written, since app
5583 used to be a separate program, but RMS wanted it to be inline.
5586 This is a subroutine to append a string to another string returning a
5587 pointer just after the last @code{char} appended. (JF: All these
5588 little routines should probably all be put in one file.)
5591 Here you will find the main program of the assembler @code{_AS__}.
5594 This is a branch office of @file{read.c}. This understands
5595 expressions, arguments. Inside @code{_AS__}, arguments are called
5596 (expression) @emph{operands}. This is confusing, because we also talk
5597 (elsewhere) about instruction @emph{operands}. Also, expression
5598 operands are called @emph{quantities} explicitly to avoid confusion
5599 with instruction operands. What a mess.
5602 This implements the @b{frag} concept. Without frags, finding the
5603 right size for branch instructions would be a lot harder.
5606 This contains the symbol table, opcode table @emph{etc.} hashing
5610 This is a table of values of digits, for use in atoi() type
5611 functions. Could probably be flushed by using calls to strtol(), or
5615 This contains Operating system dependent source file reading
5616 routines. Since error messages often say where we are in reading
5617 the source file, they live here too. Since @code{_AS__} is intended to
5618 run under GNU and Unix only, this might be worth flushing. Anyway,
5619 almost all C compilers support stdio.
5622 This deals with calling the pre-processor (if needed) and feeding the
5623 chunks back to the rest of the assembler the right way.
5626 This contains operating system independent parts of fatal and
5627 warning message reporting. See @file{append.c} above.
5630 This contains operating system dependent functions that write an
5631 object file for @code{_AS__}. See @file{input-file.c} above.
5634 This implements all the directives of @code{_AS__}. This also deals
5635 with passing input lines to the machine dependent part of the
5639 This is a C library function that isn't in most C libraries yet.
5640 See @file{append.c} above.
5643 This implements subsections.
5646 This implements symbols.
5649 This contains the code to perform relaxation, and to write out
5650 the object file. It is mostly operating system independent, but
5651 different OSes have different object file formats in any case.
5654 This implements @code{malloc()} or bust. See @file{append.c} above.
5657 This implements @code{realloc()} or bust. See @file{append.c} above.
5659 @item atof-generic.c
5660 The following files were taken from a machine-independent subroutine
5661 library for manipulating floating point numbers and very large
5664 @file{atof-generic.c} turns a string into a flonum internal format
5665 floating-point number.
5667 @item flonum-const.c
5668 This contains some potentially useful floating point numbers in
5672 This copies a flonum.
5674 @item flonum-multip.c
5675 This multiplies two flonums together.
5678 This copies a bignum.
5682 Here is a table of all the machine-specific files (this includes
5683 both source and header files). Typically, there is a
5684 @var{machine}.c file, a @var{machine}-opcode.h file, and an
5685 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
5686 be identical to the one used by GDB (which uses it for disassembly.)
5691 This contains code to turn a flonum into a ieee literal constant.
5692 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}.
5695 This is the opcode-table for the i386 version of the assembler.
5698 This contains all the code for the i386 version of the assembler.
5701 This defines constants and macros used by the i386 version of the assembler.
5704 generic 68020 header file. To be linked to m68k.h on a
5705 non-sun3, non-hpux system.
5708 68010 header file for Sun2 workstations. Not well tested. To be linked
5709 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
5713 68020 header file for Sun3 workstations. To be linked to m68k.h before
5714 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
5718 68020 header file for a HPUX (system 5?) box. Which box, which
5719 version of HPUX, etc? I don't know.
5722 A hard- or symbolic- link to one of @file{m-generic.h},
5723 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
5724 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
5728 Opcode table for 68020. This is now a link to the opcode table
5729 in the @code{GDB} source directory.
5732 All the mc680x0 code, in one huge, slow-to-compile file.
5735 This contains the code for the ns32032/ns32532 version of the
5738 @item ns32k-opcode.h
5739 This contains the opcode table for the ns32032/ns32532 version
5743 Vax specific file for describing Vax operands and other Vax-ish things.
5749 Vax specific parts of @code{_AS__}. Also includes the former files
5750 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
5753 Turns a flonum into a Vax constant.
5756 This file contains the special code needed to put out a VMS
5757 style object file for the Vax.
5761 Here is a list of the header files in the source directory.
5762 (Warning: This section may not be very accurate. I didn't
5763 write the header files; I just report them.) Also note that I
5764 think many of these header files could be cleaned up or
5770 This describes the structures used to create the binary header data
5771 inside the object file. Perhaps we should use the one in
5772 @file{/usr/include}?
5775 This defines all the globally useful things, and pulls in _0__<stdio.h>_1__
5776 and _0__<assert.h>_1__.
5779 This defines macros useful for dealing with bignums.
5782 Structure and macros for dealing with expression()
5785 This defines the structure for dealing with floating point
5786 numbers. It #includes @file{bignum.h}.
5789 This contains macro for appending a byte to the current frag.
5792 Structures and function definitions for the hashing functions.
5795 Function headers for the input-file.c functions.
5798 structures and function headers for things defined in the
5799 machine dependent part of the assembler.
5802 This is the GNU systemwide include file for manipulating obstacks.
5803 Since nobody is running under real GNU yet, we include this file.
5806 Macros and function headers for reading in source files.
5808 @item struct-symbol.h
5809 Structure definition and macros for dealing with the _AS__
5810 internal form of a symbol.
5813 structure definition for dealing with the numbered subsections
5814 of the text and data sections.
5817 Macros and function headers for dealing with symbols.
5820 Structure for doing section fixups.
5823 @comment ~subsection Test Directory
5824 @comment (Note: The test directory seems to have disappeared somewhere
5825 @comment along the line. If you want it, you'll probably have to find a
5826 @comment REALLY OLD dump tape~dots{})
5828 @comment The ~file{test/} directory is used for regression testing.
5829 @comment After you modify ~@code{_AS__}, you can get a quick go/nogo
5830 @comment confidence test by running the new ~@code{_AS__} over the source
5831 @comment files in this directory. You use a shell script ~file{test/do}.
5833 @comment The tests in this suite are evolving. They are not comprehensive.
5834 @comment They have, however, caught hundreds of bugs early in the debugging
5835 @comment cycle of ~@code{_AS__}. Most test statements in this suite were naturally
5836 @comment selected: they were used to demonstrate actual ~@code{_AS__} bugs rather
5837 @comment than being written ~i{a prioi}.
5839 @comment Another testing suggestion: over 30 bugs have been found simply by
5840 @comment running examples from this manual through ~@code{_AS__}.
5841 @comment Some examples in this manual are selected
5842 @comment to distinguish boundary conditions; they are good for testing ~@code{_AS__}.
5844 @comment ~subsubsection Regression Testing
5845 @comment Each regression test involves assembling a file and comparing the
5846 @comment actual output of ~@code{_AS__} to ``known good'' output files. Both
5847 @comment the object file and the error/warning message file (stderr) are
5848 @comment inspected. Optionally the ~@code{_AS__} exit status may be checked.
5849 @comment Discrepencies are reported. Each discrepency means either that
5850 @comment you broke some part of ~@code{_AS__} or that the ``known good'' files
5851 @comment are now out of date and should be changed to reflect the new
5852 @comment definition of ``good''.
5854 @comment Each regression test lives in its own directory, in a tree
5855 @comment rooted in the directory ~file{test/}. Each such directory
5856 @comment has a name ending in ~file{.ret}, where `ret' stands for
5857 @comment REgression Test. The ~file{.ret} ending allows ~code{find
5858 @comment (1)} to find all regression tests in the tree, without
5859 @comment needing to list them explicitly.
5861 @comment Any ~file{.ret} directory must contain a file called
5862 @comment ~file{input} which is the source file to assemble. During
5863 @comment testing an object file ~file{output} is created, as well as
5864 @comment a file ~file{stdouterr} which contains the output to both
5865 @comment stderr and stderr. If there is a file ~file{output.good} in
5866 @comment the directory, and if ~file{output} contains exactly the
5867 @comment same data as ~file{output.good}, the file ~file{output} is
5868 @comment deleted. Likewise ~file{stdouterr} is removed if it exactly
5869 @comment matches a file ~file{stdouterr.good}. If file
5870 @comment ~file{status.good} is present, containing a decimal number
5871 @comment before a newline, the exit status of ~@code{_AS__} is compared
5872 @comment to this number. If the status numbers are not equal, a file
5873 @comment ~file{status} is written to the directory, containing the
5874 @comment actual status as a decimal number followed by newline.
5876 @comment Should any of the ~file{*.good} files fail to match their corresponding
5877 @comment actual files, this is noted by a 1-line message on the screen during
5878 @comment the regression test, and you can use ~@code{find (1)} to find any
5879 @comment files named ~file{status}, ~file {output} or ~file{stdouterr}.
5881 @node Retargeting, Copying, Maintenance, Top
5882 @chapter Teaching the Assembler about a New Machine
5884 This chapter describes the steps required in order to make the
5885 assembler work with another machine's assembly language. This
5886 chapter is not complete, and only describes the steps in the
5887 broadest terms. You should look at the source for the
5888 currently supported machine in order to discover some of the
5889 details that aren't mentioned here.
5891 You should create a new file called @file{@var{machine}.c}, and
5892 add the appropriate lines to the file @file{Makefile} so that
5893 you can compile your new version of the assembler. This should
5894 be straighforward; simply add lines similar to the ones there
5895 for the four current versions of the assembler.
5897 If you want to be compatible with GDB, (and the current
5898 machine-dependent versions of the assembler), you should create
5899 a file called @file{@var{machine}-opcode.h} which should
5900 contain all the information about the names of the machine
5901 instructions, their opcodes, and what addressing modes they
5902 support. If you do this right, the assembler and GDB can share
5903 this file, and you'll only have to write it once. Note that
5904 while you're writing @code{_AS__}, you may want to use an
5905 independent program (if you have access to one), to make sure
5906 that @code{_AS__} is emitting the correct bytes. Since @code{_AS__}
5907 and @code{GDB} share the opcode table, an incorrect opcode
5908 table entry may make invalid bytes look OK when you disassemble
5909 them with @code{GDB}.
5911 @section Functions You will Have to Write
5913 Your file @file{@var{machine}.c} should contain definitions for
5914 the following functions and variables. It will need to include
5915 some header files in order to use some of the structures
5916 defined in the machine-independent part of the assembler. The
5917 needed header files are mentioned in the descriptions of the
5918 functions that will need them.
5923 This long integer holds the value to place at the beginning of
5924 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
5925 machines that store additional information in the magic-number.
5927 @item char comment_chars[];
5928 This character array holds the values of the characters that
5929 start a comment anywhere in a line. Comments are stripped off
5930 automatically by the machine independent part of the
5931 assembler. Note that the @samp{/*} will always start a
5932 comment, and that only @samp{*/} will end a comment started by
5935 @item char line_comment_chars[];
5936 This character array holds the values of the chars that start a
5937 comment only if they are the first (non-whitespace) character
5938 on a line. If the character @samp{#} does not appear in this
5939 list, you may get unexpected results. (Various
5940 machine-independent parts of the assembler treat the comments
5941 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
5942 that start with @samp{#} are comments.)
5944 @item char EXP_CHARS[];
5945 This character array holds the letters that can separate the
5946 mantissa and the exponent of a floating point number. Typical
5947 values are @samp{e} and @samp{E}.
5949 @item char FLT_CHARS[];
5950 This character array holds the letters that--when they appear
5951 immediately after a leading zero--indicate that a number is a
5952 floating-point number. (Sort of how 0x indicates that a
5953 hexadecimal number follows.)
5955 @item pseudo_typeS md_pseudo_table[];
5956 (@var{pseudo_typeS} is defined in @file{md.h})
5957 This array contains a list of the machine_dependent directives
5958 the assembler must support. It contains the name of each
5959 pseudo op (Without the leading @samp{.}), a pointer to a
5960 function to be called when that directive is encountered, and
5961 an integer argument to be passed to that function.
5963 @item void md_begin(void)
5964 This function is called as part of the assembler's
5965 initialization. It should do any initialization required by
5966 any of your other routines.
5968 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
5969 This routine is called once for each option on the command line
5970 that the machine-independent part of @code{_AS__} does not
5971 understand. This function should return non-zero if the option
5972 pointed to by @var{optionPTR} is a valid option. If it is not
5973 a valid option, this routine should return zero. The variables
5974 @var{argcPTR} and @var{argvPTR} are provided in case the option
5975 requires a filename or something similar as an argument. If
5976 the option is multi-character, @var{optionPTR} should be
5977 advanced past the end of the option, otherwise every letter in
5978 the option will be treated as a separate single-character
5981 @item void md_assemble(char *string)
5982 This routine is called for every machine-dependent
5983 non-directive line in the source file. It does all the real
5984 work involved in reading the opcode, parsing the operands,
5985 etc. @var{string} is a pointer to a null-terminated string,
5986 that comprises the input line, with all excess whitespace and
5989 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
5990 This routine is called to turn a C long int, short int, or char
5991 into the series of bytes that represents that number on the
5992 target machine. @var{outputPTR} points to an array where the
5993 result should be stored; @var{value} is the value to store; and
5994 @var{nbytes} is the number of bytes in 'value' that should be
5997 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
5998 This routine is called to turn a C long int, short int, or char
5999 into the series of bytes that represent an immediate value on
6000 the target machine. It is identical to the function @code{md_number_to_chars},
6001 except on NS32K machines.@refill
6003 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
6004 This routine is called to turn a C long int, short int, or char
6005 into the series of bytes that represent an displacement value on
6006 the target machine. It is identical to the function @code{md_number_to_chars},
6007 except on NS32K machines.@refill
6009 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
6010 This routine is identical to @code{md_number_to_chars},
6011 except on NS32K machines.
6013 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
6014 (@code{struct relocation_info} is defined in @file{a.out.h})
6015 This routine emits the relocation info in @var{ri}
6016 in the appropriate bit-pattern for the target machine.
6017 The result should be stored in the location pointed
6018 to by @var{riPTR}. This routine may be a no-op unless you are
6019 attempting to do cross-assembly.
6021 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
6022 This routine turns a series of digits into the appropriate
6023 internal representation for a floating-point number.
6024 @var{type} is a character from @var{FLT_CHARS[]} that describes
6025 what kind of floating point number is wanted; @var{outputPTR}
6026 is a pointer to an array that the result should be stored in;
6027 and @var{sizePTR} is a pointer to an integer where the size (in
6028 bytes) of the result should be stored. This routine should
6029 return an error message, or an empty string (not (char *)0) for
6032 @item int md_short_jump_size;
6033 This variable holds the (maximum) size in bytes of a short (16
6034 bit or so) jump created by @code{md_create_short_jump()}. This
6035 variable is used as part of the broken-word feature, and isn't
6036 needed if the assembler is compiled with
6037 @samp{-DWORKING_DOT_WORD}.
6039 @item int md_long_jump_size;
6040 This variable holds the (maximum) size in bytes of a long (32
6041 bit or so) jump created by @code{md_create_long_jump()}. This
6042 variable is used as part of the broken-word feature, and isn't
6043 needed if the assembler is compiled with
6044 @samp{-DWORKING_DOT_WORD}.
6046 @item void md_create_short_jump(char *resultPTR,long from_addr,
6047 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6048 This function emits a jump from @var{from_addr} to @var{to_addr} in
6049 the array of bytes pointed to by @var{resultPTR}. If this creates a
6050 type of jump that must be relocated, this function should call
6051 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
6052 emitted by this function may be smaller than @var{md_short_jump_size},
6053 but it must never create a larger one.
6054 (If it creates a smaller jump, the extra bytes of memory will not be
6055 used.) This function is used as part of the broken-word feature,
6056 and isn't needed if the assembler is compiled with
6057 @samp{-DWORKING_DOT_WORD}.@refill
6059 @item void md_create_long_jump(char *ptr,long from_addr,
6060 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6061 This function is similar to the previous function,
6062 @code{md_create_short_jump()}, except that it creates a long
6063 jump instead of a short one. This function is used as part of
6064 the broken-word feature, and isn't needed if the assembler is
6065 compiled with @samp{-DWORKING_DOT_WORD}.
6067 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
6068 This function does the initial setting up for relaxation. This
6069 includes forcing references to still-undefined symbols to the
6070 appropriate addressing modes.
6072 @item relax_typeS md_relax_table[];
6073 (relax_typeS is defined in md.h)
6074 This array describes the various machine dependent states a
6075 frag may be in before relaxation. You will need one group of
6076 entries for each type of addressing mode you intend to relax.
6078 @item void md_convert_frag(fragS *fragPTR)
6079 (@var{fragS} is defined in @file{as.h})
6080 This routine does the required cleanup after relaxation.
6081 Relaxation has changed the type of the frag to a type that can
6082 reach its destination. This function should adjust the opcode
6083 of the frag to use the appropriate addressing mode.
6084 @var{fragPTR} points to the frag to clean up.
6086 @item void md_end(void)
6087 This function is called just before the assembler exits. It
6088 need not free up memory unless the operating system doesn't do
6089 it automatically on exit. (In which case you'll also have to
6090 track down all the other places where the assembler allocates
6091 space but never frees it.)
6095 @section External Variables You will Need to Use
6097 You will need to refer to or change the following external variables
6098 from within the machine-dependent part of the assembler.
6101 @item extern char flagseen[];
6102 This array holds non-zero values in locations corresponding to
6103 the options that were on the command line. Thus, if the
6104 assembler was called with @samp{-W}, @var{flagseen['W']} would
6107 @item extern fragS *frag_now;
6108 This pointer points to the current frag--the frag that bytes
6109 are currently being added to. If nothing else, you will need
6110 to pass it as an argument to various machine-independent
6111 functions. It is maintained automatically by the
6112 frag-manipulating functions; you should never have to change it
6115 @item extern LITTLENUM_TYPE generic_bignum[];
6116 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
6117 This is where @dfn{bignums}--numbers larger than 32 bits--are
6118 returned when they are encountered in an expression. You will
6119 need to use this if you need to implement directives (or
6120 anything else) that must deal with these large numbers.
6121 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
6122 @file{as.h}, and have a positive @code{X_add_number}. The
6123 @code{X_add_number} of a @code{bignum} is the number of
6124 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
6127 @item extern FLONUM_TYPE generic_floating_point_number;
6128 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
6129 The is where @dfn{flonums}--floating-point numbers within
6130 expressions--are returned. @code{Flonums} are of @code{segT}
6131 @code{SEG_BIG}, and have a negative @code{X_add_number}.
6132 @code{Flonums} are returned in a generic format. You will have
6133 to write a routine to turn this generic format into the
6134 appropriate floating-point format for your machine.
6136 @item extern int need_pass_2;
6137 If this variable is non-zero, the assembler has encountered an
6138 expression that cannot be assembled in a single pass. Since
6139 the second pass isn't implemented, this flag means that the
6140 assembler is punting, and is only looking for additional syntax
6141 errors. (Or something like that.)
6143 @item extern segT now_seg;
6144 This variable holds the value of the section the assembler is
6145 currently assembling into.
6149 @section External functions will you need
6151 You will find the following external functions useful (or
6152 indispensable) when you're writing the machine-dependent part
6157 @item char *frag_more(int bytes)
6158 This function allocates @var{bytes} more bytes in the current
6159 frag (or starts a new frag, if it can't expand the current frag
6160 any more.) for you to store some object-file bytes in. It
6161 returns a pointer to the bytes, ready for you to store data in.
6163 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
6164 This function stores a relocation fixup to be acted on later.
6165 @var{frag} points to the frag the relocation belongs in;
6166 @var{where} is the location within the frag where the relocation begins;
6167 @var{size} is the size of the relocation, and is usually 1 (a single byte),
6168 2 (sixteen bits), or 4 (a longword).
6169 The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
6170 at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the
6171 location is subtracted from the result. A relocation entry is also added
6172 to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
6173 @var{offset} may be NULL.@refill
6175 @item char *frag_var(relax_stateT type, int max_chars, int var,
6176 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
6177 This function creates a machine-dependent frag of type @var{type}
6178 (usually @code{rs_machine_dependent}).
6179 @var{max_chars} is the maximum size in bytes that the frag may grow by;
6180 @var{var} is the current size of the variable end of the frag;
6181 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
6182 @var{md_relax_table[]} during @code{relaxation}.
6183 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
6184 @var{opcode} points into a byte whose value may have to be modified if the
6185 addressing mode used by this frag changes. It typically points into the
6186 @var{fr_literal[]} of the previous frag, and is used to point to a location
6187 that @code{md_convert_frag()}, may have to change.@refill
6189 @item void frag_wane(fragS *fragPTR)
6190 This function is useful from within @code{md_convert_frag}. It
6191 changes a frag to type rs_fill, and sets the variable-sized
6192 piece of the frag to zero. The frag will never change in size
6195 @item segT expression(expressionS *retval)
6196 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
6197 This function parses the string pointed to by the external char
6198 pointer @var{input_line_pointer}, and returns the section-type
6199 of the expression. It also stores the results in the
6200 @var{expressionS} pointed to by @var{retval}.
6201 @var{input_line_pointer} is advanced to point past the end of
6202 the expression. (@var{input_line_pointer} is used by other
6203 parts of the assembler. If you modify it, be sure to restore
6204 it to its original value.)
6206 @item as_warn(char *message,@dots{})
6207 If warning messages are disabled, this function does nothing.
6208 Otherwise, it prints out the current file name, and the current
6209 line number, then uses @code{fprintf} to print the
6210 @var{message} and any arguments it was passed.
6212 @item as_bad(char *message,@dots{})
6213 This function should be called when @code{_AS__} encounters
6214 conditions that are bad enough that @code{_AS__} should not
6215 produce an object file, but should continue reading input and
6216 printing warning and bad error messages.
6218 @item as_fatal(char *message,@dots{})
6219 This function prints out the current file name and line number,
6220 prints the word @samp{FATAL:}, then uses @code{fprintf} to
6221 print the @var{message} and any arguments it was passed. Then
6222 the assembler exits. This function should only be used for
6223 serious, unrecoverable errors.
6225 @item void float_const(int float_type)
6226 This function reads floating-point constants from the current
6227 input line, and calls @code{md_atof} to assemble them. It is
6228 useful as the function to call for the directives
6229 @samp{.single}, @samp{.double}, @samp{.float}, etc.
6230 @var{float_type} must be a character from @var{FLT_CHARS}.
6232 @item void demand_empty_rest_of_line(void);
6233 This function can be used by machine-dependent directives to
6234 make sure the rest of the input line is empty. It prints a
6235 warning message if there are additional characters on the line.
6237 @item long int get_absolute_expression(void)
6238 This function can be used by machine-dependent directives to
6239 read an absolute number from the current input line. It
6240 returns the result. If it isn't given an absolute expression,
6241 it prints a warning message and returns zero.
6246 @section The concept of Frags
6248 This assembler works to optimize the size of certain addressing
6249 modes. (e.g. branch instructions) This means the size of many
6250 pieces of object code cannot be determined until after assembly
6251 is finished. (This means that the addresses of symbols cannot be
6252 determined until assembly is finished.) In order to do this,
6253 @code{_AS__} stores the output bytes as @dfn{frags}.
6255 Here is the definition of a frag (from @file{as.h})
6261 relax_stateT fr_type;
6262 relax_substateT fr_substate;
6263 unsigned long fr_address;
6265 struct symbol *fr_symbol;
6267 struct frag *fr_next;
6274 is the size of the fixed-size piece of the frag.
6277 is the maximum (?) size of the variable-sized piece of the frag.
6280 is the type of the frag.
6285 rs_machine_dependent
6288 This stores the type of machine-dependent frag this is. (what
6289 kind of addressing mode is being used, and what size is being
6293 @var{fr_address} is only valid after relaxation is finished.
6294 Before relaxation, the only way to store an address is (pointer
6295 to frag containing the address) plus (offset into the frag).
6298 This contains a number, whose meaning depends on the type of
6300 for machine_dependent frags, this contains the offset from
6301 fr_symbol that the frag wants to go to. Thus, for branch
6302 instructions it is usually zero. (unless the instruction was
6303 @samp{jba foo+12} or something like that.)
6306 for machine_dependent frags, this points to the symbol the frag
6310 This points to the location in the frag (or in a previous frag)
6311 of the opcode for the instruction that caused this to be a frag.
6312 @var{fr_opcode} is needed if the actual opcode must be changed
6313 in order to use a different form of the addressing mode.
6314 (For example, if a conditional branch only comes in size tiny,
6315 a large-size branch could be implemented by reversing the sense
6316 of the test, and turning it into a tiny branch over a large jump.
6317 This would require changing the opcode.)
6319 @var{fr_literal} is a variable-size array that contains the
6320 actual object bytes. A frag consists of a fixed size piece of
6321 object data, (which may be zero bytes long), followed by a
6322 piece of object data whose size may not have been determined
6323 yet. Other information includes the type of the frag (which
6324 controls how it is relaxed),
6327 This is the next frag in the singly-linked list. This is
6328 usually only needed by the machine-independent part of
6334 @node Copying, Index, _MACH_DEP__, Top
6335 @unnumbered GNU GENERAL PUBLIC LICENSE
6339 @cindex copying @code{_AS__}
6340 @center Version 2, June 1991
6343 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
6344 675 Mass Ave, Cambridge, MA 02139, USA
6346 Everyone is permitted to copy and distribute verbatim copies
6347 of this license document, but changing it is not allowed.
6350 @unnumberedsec Preamble
6352 The licenses for most software are designed to take away your
6353 freedom to share and change it. By contrast, the GNU General Public
6354 License is intended to guarantee your freedom to share and change free
6355 software---to make sure the software is free for all its users. This
6356 General Public License applies to most of the Free Software
6357 Foundation's software and to any other program whose authors commit to
6358 using it. (Some other Free Software Foundation software is covered by
6359 the GNU Library General Public License instead.) You can apply it to
6362 When we speak of free software, we are referring to freedom, not
6363 price. Our General Public Licenses are designed to make sure that you
6364 have the freedom to distribute copies of free software (and charge for
6365 this service if you wish), that you receive source code or can get it
6366 if you want it, that you can change the software or use pieces of it
6367 in new free programs; and that you know you can do these things.
6369 To protect your rights, we need to make restrictions that forbid
6370 anyone to deny you these rights or to ask you to surrender the rights.
6371 These restrictions translate to certain responsibilities for you if you
6372 distribute copies of the software, or if you modify it.
6374 For example, if you distribute copies of such a program, whether
6375 gratis or for a fee, you must give the recipients all the rights that
6376 you have. You must make sure that they, too, receive or can get the
6377 source code. And you must show them these terms so they know their
6380 We protect your rights with two steps: (1) copyright the software, and
6381 (2) offer you this license which gives you legal permission to copy,
6382 distribute and/or modify the software.
6384 Also, for each author's protection and ours, we want to make certain
6385 that everyone understands that there is no warranty for this free
6386 software. If the software is modified by someone else and passed on, we
6387 want its recipients to know that what they have is not the original, so
6388 that any problems introduced by others will not reflect on the original
6389 authors' reputations.
6391 Finally, any free program is threatened constantly by software
6392 patents. We wish to avoid the danger that redistributors of a free
6393 program will individually obtain patent licenses, in effect making the
6394 program proprietary. To prevent this, we have made it clear that any
6395 patent must be licensed for everyone's free use or not licensed at all.
6397 The precise terms and conditions for copying, distribution and
6398 modification follow.
6401 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6404 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6409 This License applies to any program or other work which contains
6410 a notice placed by the copyright holder saying it may be distributed
6411 under the terms of this General Public License. The ``Program'', below,
6412 refers to any such program or work, and a ``work based on the Program''
6413 means either the Program or any derivative work under copyright law:
6414 that is to say, a work containing the Program or a portion of it,
6415 either verbatim or with modifications and/or translated into another
6416 language. (Hereinafter, translation is included without limitation in
6417 the term ``modification''.) Each licensee is addressed as ``you''.
6419 Activities other than copying, distribution and modification are not
6420 covered by this License; they are outside its scope. The act of
6421 running the Program is not restricted, and the output from the Program
6422 is covered only if its contents constitute a work based on the
6423 Program (independent of having been made by running the Program).
6424 Whether that is true depends on what the Program does.
6427 You may copy and distribute verbatim copies of the Program's
6428 source code as you receive it, in any medium, provided that you
6429 conspicuously and appropriately publish on each copy an appropriate
6430 copyright notice and disclaimer of warranty; keep intact all the
6431 notices that refer to this License and to the absence of any warranty;
6432 and give any other recipients of the Program a copy of this License
6433 along with the Program.
6435 You may charge a fee for the physical act of transferring a copy, and
6436 you may at your option offer warranty protection in exchange for a fee.
6439 You may modify your copy or copies of the Program or any portion
6440 of it, thus forming a work based on the Program, and copy and
6441 distribute such modifications or work under the terms of Section 1
6442 above, provided that you also meet all of these conditions:
6446 You must cause the modified files to carry prominent notices
6447 stating that you changed the files and the date of any change.
6450 You must cause any work that you distribute or publish, that in
6451 whole or in part contains or is derived from the Program or any
6452 part thereof, to be licensed as a whole at no charge to all third
6453 parties under the terms of this License.
6456 If the modified program normally reads commands interactively
6457 when run, you must cause it, when started running for such
6458 interactive use in the most ordinary way, to print or display an
6459 announcement including an appropriate copyright notice and a
6460 notice that there is no warranty (or else, saying that you provide
6461 a warranty) and that users may redistribute the program under
6462 these conditions, and telling the user how to view a copy of this
6463 License. (Exception: if the Program itself is interactive but
6464 does not normally print such an announcement, your work based on
6465 the Program is not required to print an announcement.)
6468 These requirements apply to the modified work as a whole. If
6469 identifiable sections of that work are not derived from the Program,
6470 and can be reasonably considered independent and separate works in
6471 themselves, then this License, and its terms, do not apply to those
6472 sections when you distribute them as separate works. But when you
6473 distribute the same sections as part of a whole which is a work based
6474 on the Program, the distribution of the whole must be on the terms of
6475 this License, whose permissions for other licensees extend to the
6476 entire whole, and thus to each and every part regardless of who wrote it.
6478 Thus, it is not the intent of this section to claim rights or contest
6479 your rights to work written entirely by you; rather, the intent is to
6480 exercise the right to control the distribution of derivative or
6481 collective works based on the Program.
6483 In addition, mere aggregation of another work not based on the Program
6484 with the Program (or with a work based on the Program) on a volume of
6485 a storage or distribution medium does not bring the other work under
6486 the scope of this License.
6489 You may copy and distribute the Program (or a work based on it,
6490 under Section 2) in object code or executable form under the terms of
6491 Sections 1 and 2 above provided that you also do one of the following:
6495 Accompany it with the complete corresponding machine-readable
6496 source code, which must be distributed under the terms of Sections
6497 1 and 2 above on a medium customarily used for software interchange; or,
6500 Accompany it with a written offer, valid for at least three
6501 years, to give any third party, for a charge no more than your
6502 cost of physically performing source distribution, a complete
6503 machine-readable copy of the corresponding source code, to be
6504 distributed under the terms of Sections 1 and 2 above on a medium
6505 customarily used for software interchange; or,
6508 Accompany it with the information you received as to the offer
6509 to distribute corresponding source code. (This alternative is
6510 allowed only for noncommercial distribution and only if you
6511 received the program in object code or executable form with such
6512 an offer, in accord with Subsection b above.)
6515 The source code for a work means the preferred form of the work for
6516 making modifications to it. For an executable work, complete source
6517 code means all the source code for all modules it contains, plus any
6518 associated interface definition files, plus the scripts used to
6519 control compilation and installation of the executable. However, as a
6520 special exception, the source code distributed need not include
6521 anything that is normally distributed (in either source or binary
6522 form) with the major components (compiler, kernel, and so on) of the
6523 operating system on which the executable runs, unless that component
6524 itself accompanies the executable.
6526 If distribution of executable or object code is made by offering
6527 access to copy from a designated place, then offering equivalent
6528 access to copy the source code from the same place counts as
6529 distribution of the source code, even though third parties are not
6530 compelled to copy the source along with the object code.
6533 You may not copy, modify, sublicense, or distribute the Program
6534 except as expressly provided under this License. Any attempt
6535 otherwise to copy, modify, sublicense or distribute the Program is
6536 void, and will automatically terminate your rights under this License.
6537 However, parties who have received copies, or rights, from you under
6538 this License will not have their licenses terminated so long as such
6539 parties remain in full compliance.
6542 You are not required to accept this License, since you have not
6543 signed it. However, nothing else grants you permission to modify or
6544 distribute the Program or its derivative works. These actions are
6545 prohibited by law if you do not accept this License. Therefore, by
6546 modifying or distributing the Program (or any work based on the
6547 Program), you indicate your acceptance of this License to do so, and
6548 all its terms and conditions for copying, distributing or modifying
6549 the Program or works based on it.
6552 Each time you redistribute the Program (or any work based on the
6553 Program), the recipient automatically receives a license from the
6554 original licensor to copy, distribute or modify the Program subject to
6555 these terms and conditions. You may not impose any further
6556 restrictions on the recipients' exercise of the rights granted herein.
6557 You are not responsible for enforcing compliance by third parties to
6561 If, as a consequence of a court judgment or allegation of patent
6562 infringement or for any other reason (not limited to patent issues),
6563 conditions are imposed on you (whether by court order, agreement or
6564 otherwise) that contradict the conditions of this License, they do not
6565 excuse you from the conditions of this License. If you cannot
6566 distribute so as to satisfy simultaneously your obligations under this
6567 License and any other pertinent obligations, then as a consequence you
6568 may not distribute the Program at all. For example, if a patent
6569 license would not permit royalty-free redistribution of the Program by
6570 all those who receive copies directly or indirectly through you, then
6571 the only way you could satisfy both it and this License would be to
6572 refrain entirely from distribution of the Program.
6574 If any portion of this section is held invalid or unenforceable under
6575 any particular circumstance, the balance of the section is intended to
6576 apply and the section as a whole is intended to apply in other
6579 It is not the purpose of this section to induce you to infringe any
6580 patents or other property right claims or to contest validity of any
6581 such claims; this section has the sole purpose of protecting the
6582 integrity of the free software distribution system, which is
6583 implemented by public license practices. Many people have made
6584 generous contributions to the wide range of software distributed
6585 through that system in reliance on consistent application of that
6586 system; it is up to the author/donor to decide if he or she is willing
6587 to distribute software through any other system and a licensee cannot
6590 This section is intended to make thoroughly clear what is believed to
6591 be a consequence of the rest of this License.
6594 If the distribution and/or use of the Program is restricted in
6595 certain countries either by patents or by copyrighted interfaces, the
6596 original copyright holder who places the Program under this License
6597 may add an explicit geographical distribution limitation excluding
6598 those countries, so that distribution is permitted only in or among
6599 countries not thus excluded. In such case, this License incorporates
6600 the limitation as if written in the body of this License.
6603 The Free Software Foundation may publish revised and/or new versions
6604 of the General Public License from time to time. Such new versions will
6605 be similar in spirit to the present version, but may differ in detail to
6606 address new problems or concerns.
6608 Each version is given a distinguishing version number. If the Program
6609 specifies a version number of this License which applies to it and ``any
6610 later version'', you have the option of following the terms and conditions
6611 either of that version or of any later version published by the Free
6612 Software Foundation. If the Program does not specify a version number of
6613 this License, you may choose any version ever published by the Free Software
6617 If you wish to incorporate parts of the Program into other free
6618 programs whose distribution conditions are different, write to the author
6619 to ask for permission. For software which is copyrighted by the Free
6620 Software Foundation, write to the Free Software Foundation; we sometimes
6621 make exceptions for this. Our decision will be guided by the two goals
6622 of preserving the free status of all derivatives of our free software and
6623 of promoting the sharing and reuse of software generally.
6626 @heading NO WARRANTY
6633 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
6634 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
6635 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
6636 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
6637 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6638 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
6639 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
6640 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
6641 REPAIR OR CORRECTION.
6644 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
6645 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
6646 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
6647 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
6648 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
6649 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
6650 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
6651 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
6652 POSSIBILITY OF SUCH DAMAGES.
6656 @heading END OF TERMS AND CONDITIONS
6659 @center END OF TERMS AND CONDITIONS
6663 @unnumberedsec Applying These Terms to Your New Programs
6665 If you develop a new program, and you want it to be of the greatest
6666 possible use to the public, the best way to achieve this is to make it
6667 free software which everyone can redistribute and change under these terms.
6669 To do so, attach the following notices to the program. It is safest
6670 to attach them to the start of each source file to most effectively
6671 convey the exclusion of warranty; and each file should have at least
6672 the ``copyright'' line and a pointer to where the full notice is found.
6675 @var{one line to give the program's name and an idea of what it does.}
6676 Copyright (C) 19@var{yy} @var{name of author}
6678 This program is free software; you can redistribute it and/or
6679 modify it under the terms of the GNU General Public License
6680 as published by the Free Software Foundation; either version 2
6681 of the License, or (at your option) any later version.
6683 This program is distributed in the hope that it will be useful,
6684 but WITHOUT ANY WARRANTY; without even the implied warranty of
6685 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6686 GNU General Public License for more details.
6688 You should have received a copy of the GNU General Public License
6689 along with this program; if not, write to the
6690 Free Software Foundation, Inc., 675 Mass Ave,
6691 Cambridge, MA 02139, USA.
6694 Also add information on how to contact you by electronic and paper mail.
6696 If the program is interactive, make it output a short notice like this
6697 when it starts in an interactive mode:
6700 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
6701 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
6702 type `show w'. This is free software, and you are welcome
6703 to redistribute it under certain conditions; type `show c'
6707 The hypothetical commands @samp{show w} and @samp{show c} should show
6708 the appropriate parts of the General Public License. Of course, the
6709 commands you use may be called something other than @samp{show w} and
6710 @samp{show c}; they could even be mouse-clicks or menu items---whatever
6713 You should also get your employer (if you work as a programmer) or your
6714 school, if any, to sign a ``copyright disclaimer'' for the program, if
6715 necessary. Here is a sample; alter the names:
6718 Yoyodyne, Inc., hereby disclaims all copyright interest in
6719 the program `Gnomovision' (which makes passes at compilers)
6720 written by James Hacker.
6722 @var{signature of Ty Coon}, 1 April 1989
6723 Ty Coon, President of Vice
6726 This General Public License does not permit incorporating your program into
6727 proprietary programs. If your program is a subroutine library, you may
6728 consider it more useful to permit linking proprietary applications with the
6729 library. If this is what you want to do, use the GNU Library General
6730 Public License instead of this License.
6732 @node Index, , Copying, Top
projects / deliverable / binutils-gdb.git / blob