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
24 NOTE: this manual is marked up for preprocessing with a collection
25 of m4 macros called "pretex.m4".
27 THIS IS THE FULL SOURCE. The full source needs to be run through m4
28 before either tex- or info- formatting: for example,
29 m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
30 will produce (assuming your path finds either GNU or SysV m4; Berkeley
31 won't do) a file, configured for the M680x0 version of GAS, suitable for
32 formatting. See the text in "pretex.m4" for a fuller explanation (and
33 the macro definitions).
38 This file documents the GNU Assembler "_AS__".
40 Copyright (C) 1991 Free Software Foundation, Inc.
42 Permission is granted to make and distribute verbatim copies of
43 this manual provided the copyright notice and this permission notice
44 are preserved on all copies.
47 Permission is granted to process this file through Tex and print the
48 results, provided the printed document carries copying permission
49 notice identical to this one except for the removal of this paragraph
50 (this paragraph not being relevant to the printed manual).
53 Permission is granted to copy and distribute modified versions of this
54 manual under the conditions for verbatim copying, provided also that the
55 section entitled ``GNU General Public License'' is included exactly as
56 in the original, and provided that the entire resulting derived work is
57 distributed under the terms of a permission notice identical to this
60 Permission is granted to copy and distribute translations of this manual
61 into another language, under the above conditions for modified versions,
62 except that the section entitled ``GNU General Public License'' may be
63 included in a translation approved by the Free Software Foundation
64 instead of in the original English.
69 @subtitle The GNU Assembler
71 @subtitle for the _HOST__ family
74 @subtitle January 1992
77 The Free Software Foundation Inc. thanks The Nice Computer
78 Company of Australia for loaning Dean Elsner to write the
79 first (Vax) version of @code{as} for Project GNU.
80 The proprietors, management and staff of TNCCA thank FSF for
81 distracting the boss while they got some work
84 @author Dean Elsner, Jay Fenlason & friends
85 @c edited by: pesch@cygnus.com
88 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
89 \xdef\manvers{\$Revision$} % For use in headers, footers too
92 \hfill \TeX{}info \texinfoversion\par
94 %"boxit" macro for figures:
95 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
96 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
97 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
98 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
99 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
102 Edited by Roland Pesch for Cygnus Support.
104 @vskip 0pt plus 1filll
105 Copyright @copyright{} 1991 Free Software Foundation, Inc.
107 Permission is granted to make and distribute verbatim copies of
108 this manual provided the copyright notice and this permission notice
109 are preserved on all copies.
111 Permission is granted to copy and distribute modified versions of this
112 manual under the conditions for verbatim copying, provided also that the
113 section entitled ``GNU General Public License'' is included exactly as
114 in the original, and provided that the entire resulting derived work is
115 distributed under the terms of a permission notice identical to this
118 Permission is granted to copy and distribute translations of this manual
119 into another language, under the above conditions for modified versions,
120 except that the section entitled ``GNU General Public License'' may be
121 included in a translation approved by the Free Software Foundation
122 instead of in the original English.
125 @node Top, Overview, (dir), (dir)
127 This file is a user guide to the GNU assembler @code{_AS__}.
129 This version of the file describes @code{_AS__} configured to generate
130 code for _HOST__ architectures.
134 * Overview:: Overview
135 * Invoking:: Command-Line Options
137 * Sections:: Sections and Relocation
139 * Expressions:: Expressions
140 * Pseudo Ops:: Assembler Directives
141 * _MACH_DEP__:: Machine Dependent Features
142 * Copying:: GNU GENERAL PUBLIC LICENSE
146 @node Overview, Invoking, Top, Top
149 This manual is a user guide to the GNU assembler @code{_AS__}.
151 This version of the manual describes @code{_AS__} configured to generate
152 code for _HOST__ architectures.
156 @cindex invocation summary
157 @cindex option summary
158 @cindex summary of options
159 Here is a brief summary of how to invoke @code{_AS__}. For details,
160 @pxref{Invoking,,Comand-Line Options}.
162 @c We don't use deffn and friends for the following because they seem
163 @c to be limited to one line for the header.
165 _AS__ [ -a | -al | -as ] [ -D ] [ -f ]
166 [ -I @var{path} ] [ -k ] [ -L ]
167 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
169 @c am29k has no machine-dependent assembler options
172 @c h8/300 has no machine-dependent assembler options
175 @c see md_parse_option in i960.c
176 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
180 [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
182 [ -- | @var{files} @dots{} ]
187 Turn on assembly listings; @samp{-al}, listing only, @samp{-as}, symbols
188 only, @samp{-a}, everything.
191 This option is accepted only for script compatibility with calls to
192 other assemblers; it has no effect on @code{_AS__}.
195 ``fast''---skip preprocessing (assume source is compiler output)
198 Add @var{path} to the search list for @code{.include} directives
201 _if__((!_GENERIC__) && !_DIFFTABKLUG__)
202 This option is accepted but has no effect on the _HOST__ family.
203 _fi__((!_GENERIC__) && !_DIFFTABKLUG__)
204 _if__(_GENERIC__ || _DIFFTABKLUG__)
205 Issue warnings when difference tables altered for long displacements.
206 _fi__(_GENERIC__ || _DIFFTABKLUG__)
209 Keep (in symbol table) local symbols, starting with @samp{L}
211 @item -o @var{objfile}
212 Name the object-file output from @code{_AS__}
215 Fold data section into text section
218 Announce @code{as} version
221 Suppress warning messages
224 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
226 (When configured for Intel 960).
228 Specify which variant of the 960 architecture is the target.
232 (When configured for Intel 960).
234 Add code to collect statistics about branches taken.
238 (When configured for Intel 960).
240 Do not alter compare-and-branch instructions for long displacements;
247 (When configured for Motorola 68000).
249 Shorten references to undefined symbols, to one word instead of two
251 @item -mc68000 | -mc68010 | -mc68020
253 (When configured for Motorola 68000).
255 Specify what processor in the 68000 family is the target (default 68020)
258 @item -- | @var{files} @dots{}
259 Standard input, or source files to assemble
263 * Manual:: Structure of this Manual
264 * GNU Assembler:: _AS__, the GNU Assembler
265 * Object Formats:: Object File Formats
266 * Command Line:: Command Line
267 * Input Files:: Input Files
268 * Object:: Output (Object) File
269 * Errors:: Error and Warning Messages
272 @node Manual, GNU Assembler, Overview, Overview
273 @section Structure of this Manual
275 @cindex manual, structure and purpose
276 This manual is intended to describe what you need to know to use
277 @sc{gnu} @code{_AS__}. We cover the syntax expected in source files, including
278 notation for symbols, constants, and expressions; the directives that
279 @code{_AS__} understands; and of course how to invoke @code{_AS__}.
282 We also cover special features in the _HOST__
283 configuration of @code{_AS__}, including assembler directives.
286 This manual also describes some of the machine-dependent features of
287 various flavors of the assembler.
290 This manual also describes how the assembler works internally, and
291 provides some information that may be useful to people attempting to
292 port the assembler to another machine.
296 @cindex machine instructions (not covered)
297 On the other hand, this manual is @emph{not} intended as an introduction
298 to programming in assembly language---let alone programming in general!
299 In a similar vein, we make no attempt to introduce the machine
300 architecture; we do @emph{not} describe the instruction set, standard
301 mnemonics, registers or addressing modes that are standard to a
302 particular architecture.
304 You may want to consult the manufacturer's
305 machine architecture manual for this information.
307 _if__(_H8__&&!_GENERIC__)
308 For information on the H8/300 machine instruction set, see @cite{H8/300
309 Series Programming Manual} (Hitachi ADE--602--025).
310 _fi__(_H8__&&!_GENERIC__)
313 @c I think this is premature---pesch@cygnus.com, 17jan1991
315 Throughout this manual, we assume that you are running @dfn{GNU},
316 the portable operating system from the @dfn{Free Software
317 Foundation, Inc.}. This restricts our attention to certain kinds of
318 computer (in particular, the kinds of computers that GNU can run on);
319 once this assumption is granted examples and definitions need less
322 @code{_AS__} is part of a team of programs that turn a high-level
323 human-readable series of instructions into a low-level
324 computer-readable series of instructions. Different versions of
325 @code{_AS__} are used for different kinds of computer.
328 @c There used to be a section "Terminology" here, which defined
329 @c "contents", "byte", "word", and "long". Defining "word" to any
330 @c particular size is confusing when the .word directive may generate 16
331 @c bits on one machine and 32 bits on another; in general, for the user
332 @c version of this manual, none of these terms seem essential to define.
333 @c They were used very little even in the former draft of the manual;
334 @c this draft makes an effort to avoid them (except in names of
337 @node GNU Assembler, Object Formats, Manual, Overview
338 @section _AS__, the GNU Assembler
340 GNU @code{as} is really a family of assemblers.
342 This manual describes @code{_AS__}, a member of that family which is
343 configured for the _HOST__ architectures.
345 If you use (or have used) the GNU assembler on one architecture, you
346 should find a fairly similar environment when you use it on another
347 architecture. Each version has much in common with the others,
348 including object file formats, most assembler directives (often called
349 @dfn{pseudo-ops)} and assembler syntax.@refill
351 _if__(_GENERIC__||!_H8__)
352 @cindex purpose of @sc{gnu} @code{_AS__}
353 @code{_AS__} is primarily intended to assemble the output of the GNU C
354 compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless,
355 we've tried to make @code{_AS__} assemble correctly everything that the native
357 _fi__(_GENERIC__||!_H8__)
359 Any exceptions are documented explicitly (@pxref{_MACH_DEP__}).
361 _if__(_GENERIC__||_M680X0__)
362 This doesn't mean @code{_AS__} always uses the same syntax as another
363 assembler for the same architecture; for example, we know of several
364 incompatible versions of 680x0 assembly language syntax.
365 _fi__(_GENERIC__||_M680X0__)
367 Unlike older assemblers, @code{_AS__} is designed to assemble a source
368 program in one pass of the source file. This has a subtle impact on the
369 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
371 @node Object Formats, Command Line, GNU Assembler, Overview
372 @section Object File Formats
374 @cindex object file format
375 The GNU assembler can be configured to produce several alternative
376 object file formats. For the most part, this does not affect how you
377 write assembly language programs; but directives for debugging symbols
378 are typically different in different file formats. @xref{Symbol
379 Attributes,,Symbol Attributes}.
381 _if__(!(_I960__||_A29K__))
382 _if__(_AOUT__ && (!_COFF__) && (!_ELF__))
383 On the _HOST__, @code{_AS__} is configured to produce @code{a.out} format object
385 _fi__(_AOUT__ && (!_COFF__) && (!_ELF__))
386 _if__((!_AOUT__) && _COFF__ && (!_ELF__))
387 On the _HOST__, @code{_AS__} is configured to produce COFF format object
389 _fi__((!_AOUT__) && _COFF__ && (!_ELF__))
390 _fi__(!(_I960__||_A29K__))
392 On the _HOST__, @code{_AS__} can be configured to produce either
393 @code{a.out} or COFF format object files.
396 On the _HOST__, @code{_AS__} can be configured to produce either @code{b.out} or COFF
401 @node Command Line, Input Files, Object Formats, Overview
402 @section Command Line
404 @cindex command line conventions
405 After the program name @code{_AS__}, the command line may contain
406 options and file names. Options may appear in any order, and may be
407 before, after, or between file names. The order of file names is
410 @cindex standard input, as input file
412 @file{--} (two hyphens) by itself names the standard input file
413 explicitly, as one of the files for @code{_AS__} to assemble.
415 @cindex options, command line
416 Except for @samp{--} any command line argument that begins with a
417 hyphen (@samp{-}) is an option. Each option changes the behavior of
418 @code{_AS__}. No option changes the way another option works. An
419 option is a @samp{-} followed by one or more letters; the case of
420 the letter is important. All options are optional.
422 Some options expect exactly one file name to follow them. The file
423 name may either immediately follow the option's letter (compatible
424 with older assemblers) or it may be the next command argument (GNU
425 standard). These two command lines are equivalent:
428 _AS__ -o my-object-file.o mumble.s
429 _AS__ -omy-object-file.o mumble.s
432 @node Input Files, Object, Command Line, Overview
436 @cindex source program
438 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
439 describe the program input to one run of @code{_AS__}. The program may
440 be in one or more files; how the source is partitioned into files
441 doesn't change the meaning of the source.
443 @c I added "con" prefix to "catenation" just to prove I can overcome my
444 @c APL training... pesch@cygnus.com
445 The source program is a concatenation of the text in all the files, in the
448 Each time you run @code{_AS__} it assembles exactly one source
449 program. The source program is made up of one or more files.
450 (The standard input is also a file.)
452 You give @code{_AS__} a command line that has zero or more input file
453 names. The input files are read (from left file name to right). A
454 command line argument (in any position) that has no special meaning
455 is taken to be an input file name.
457 If you give @code{_AS__} no file names it attempts to read one input file
458 from the @code{_AS__} standard input, which is normally your terminal. You
459 may have to type @key{ctl-D} to tell @code{_AS__} there is no more program
462 Use @samp{--} if you need to explicitly name the standard input file
463 in your command line.
465 If the source is empty, @code{_AS__} will produce a small, empty object
468 @subheading Filenames and Line-numbers
470 @cindex input file linenumbers
471 @cindex line numbers, in input files
472 There are two ways of locating a line in the input file (or files) and
473 either may be used in reporting error messages. One way refers to a line
474 number in a physical file; the other refers to a line number in a
475 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
477 @dfn{Physical files} are those files named in the command line given
480 @dfn{Logical files} are simply names declared explicitly by assembler
481 directives; they bear no relation to physical files. Logical file names
482 help error messages reflect the original source file, when @code{_AS__}
483 source is itself synthesized from other files.
484 @xref{App-File,,@code{.app-file}}.
486 @node Object, Errors, Input Files, Overview
487 @section Output (Object) File
493 Every time you run @code{_AS__} it produces an output file, which is
494 your assembly language program translated into numbers. This file
495 is the object file, named @code{a.out} unless you tell @code{_AS__} to
496 give it another name by using the @code{-o} option. Conventionally,
497 object file names end with @file{.o}. The default name of
498 @file{a.out} is used for historical reasons: older assemblers were
499 capable of assembling self-contained programs directly into a
501 @c This may still work, but hasn't been tested.
505 The object file is meant for input to the linker @code{_LD__}. It contains
506 assembled program code, information to help @code{_LD__} integrate
507 the assembled program into a runnable file, and (optionally) symbolic
508 information for the debugger.
510 @c link above to some info file(s) like the description of a.out.
511 @c don't forget to describe GNU info as well as Unix lossage.
513 @node Errors, , Object, Overview
514 @section Error and Warning Messages
516 @cindex error messsages
517 @cindex warning messages
518 @cindex messages from @code{_AS__}
519 @code{_AS__} may write warnings and error messages to the standard error
520 file (usually your terminal). This should not happen when a compiler
521 runs @code{_AS__} automatically. Warnings report an assumption made so
522 that @code{_AS__} could keep assembling a flawed program; errors report a
523 grave problem that stops the assembly.
525 @cindex format of warning messages
526 Warning messages have the format
529 file_name:@b{NNN}:Warning Message Text
533 @cindex line numbers, in warnings/errors
534 (where @b{NNN} is a line number). If a logical file name has
535 been given (@pxref{App-File,,@code{.app-file}}) it is used for the filename, otherwise the
536 name of the current input file is used. If a logical line number was
539 (@pxref{Line,,@code{.line}})
542 (@pxref{Ln,,@code{.ln}})
544 then it is used to calculate the number printed,
545 otherwise the actual line in the current source file is printed. The
546 message text is intended to be self explanatory (in the grand Unix
549 @cindex format of error messages
550 Error messages have the format
552 file_name:@b{NNN}:FATAL:Error Message Text
554 The file name and line number are derived as for warning
555 messages. The actual message text may be rather less explanatory
556 because many of them aren't supposed to happen.
558 @node Invoking, Syntax, Overview, Top
559 @chapter Command-Line Options
561 @cindex options, all versions of @code{_AS__}
562 This chapter describes command-line options available in @emph{all}
563 versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific
568 to particular machine architectures.
571 @section @code{-a}, @code{-al}, @code{-as}
576 @cindex listings, enabling
577 @cindex assembly listings, enabling
578 These options enable listing output from the assembler. @samp{-a} by
579 itself requests all listing output; @samp{-al} requests only the
580 output-program listing, and @samp{-as} requests only a symbol table
583 Once you have specified one of these options, you can further control
584 listing output and its appearance using the directives @code{.list},
585 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
588 If you do not request listing output with one of the @samp{-a} options, the
589 listing-control directives have no effect.
594 This option has no effect whatsoever, but it is accepted to make it more
595 likely that scripts written for other assemblers will also work with
598 @section Work Faster: @code{-f}
601 @cindex trusted compiler
602 @cindex faster processing (@code{-f})
603 @samp{-f} should only be used when assembling programs written by a
604 (trusted) compiler. @samp{-f} stops the assembler from pre-processing
605 the input file(s) before assembling them. @xref{Pre-processing,
609 @emph{Warning:} if the files actually need to be pre-processed (if they
610 contain comments, for example), @code{_AS__} will not work correctly if
614 @section @code{.include} search path: @code{-I} @var{path}
616 @kindex -I @var{path}
617 @cindex paths for @code{.include}
618 @cindex search path for @code{.include}
619 @cindex @code{include} directive search path
620 Use this option to add a @var{path} to the list of directories
621 @code{_AS__} will search for files specified in @code{.include}
622 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
623 many times as necessary to include a variety of paths. The current
624 working directory is always searched first; after that, @code{_AS__}
625 searches any @samp{-I} directories in the same order as they were
626 specified (left to right) on the command line.
628 @section Difference Tables: @code{-k}
631 _if__((!_GENERIC__) && (!_DIFFTABKLUG__))
632 On the _HOST__ family, this option is allowed, but has no effect. It is
633 permitted for compatibility with the GNU assembler on other platforms,
634 where it can be used to warn when the assembler alters the machine code
635 generated for @samp{.word} directives in difference tables. The _HOST__
636 family does not have the addressing limitations that sometimes lead to this
637 alteration on other platforms.
638 _fi__((!_GENERIC__) && (!_DIFFTABKLUG__))
640 _if__(_GENERIC__ || _DIFFTABKLUG__ )
641 @cindex difference tables, warning
642 @cindex warning for altered difference tables
643 @code{_AS__} sometimes alters the code emitted for directives of the form
644 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
645 You can use the @samp{-k} option if you want a warning issued when this
647 _fi__(_GENERIC__ || _DIFFTABKLUG__ )
649 @section Include Local Labels: @code{-L}
652 @cindex local labels, retaining in output
653 Labels beginning with @samp{L} (upper case only) are called @dfn{local
654 labels}. @xref{Symbol Names}. Normally you don't see such labels when
655 debugging, because they are intended for the use of programs (like
656 compilers) that compose assembler programs, not for your notice.
657 Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't
658 normally debug with them.
660 This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols
661 in the object file. Usually if you do this you also tell the linker
662 @code{_LD__} to preserve symbols whose names begin with @samp{L}.
664 @section Name the Object File: @code{-o}
667 @cindex naming object file
668 @cindex object file name
669 There is always one object file output when you run @code{_AS__}. By
670 default it has the name @file{a.out}. You use this option (which
671 takes exactly one filename) to give the object file a different name.
673 Whatever the object file is called, @code{_AS__} will overwrite any
674 existing file of the same name.
676 @section Join Data and Text Sections: @code{-R}
679 @cindex data and text sections, joining
680 @cindex text and data sections, joining
681 @cindex joining text and data sections
682 @cindex merging text and data sections
683 @code{-R} tells @code{_AS__} to write the object file as if all
684 data-section data lives in the text section. This is only done at
685 the very last moment: your binary data are the same, but data
686 section parts are relocated differently. The data section part of
687 your object file is zero bytes long because all it bytes are
688 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
690 When you specify @code{-R} it would be possible to generate shorter
691 address displacements (because we don't have to cross between text and
692 data section). We refrain from doing this simply for compatibility with
693 older versions of @code{_AS__}. In future, @code{-R} may work this way.
696 When @code{_AS__} is configured for COFF output,
697 this option is only useful if you use sections named @samp{.text} and
701 @section Announce Version: @code{-v}
705 @cindex @code{_AS__} version
706 @cindex version of @code{_AS__}
707 You can find out what version of as is running by including the
708 option @samp{-v} (which you can also spell as @samp{-version}) on the
711 @section Suppress Warnings: @code{-W}
714 @cindex suppressing warnings
715 @cindex warnings, suppressing
716 @code{_AS__} should never give a warning or error message when
717 assembling compiler output. But programs written by people often
718 cause @code{_AS__} to give a warning that a particular assumption was
719 made. All such warnings are directed to the standard error file.
720 If you use this option, no warnings are issued. This option only
721 affects the warning messages: it does not change any particular of how
722 @code{_AS__} assembles your file. Errors, which stop the assembly, are
725 @node Syntax, Sections, Invoking, Top
728 @cindex machine-independent syntax
729 @cindex syntax, machine-independent
730 This chapter describes the machine-independent syntax allowed in a
731 source file. @code{_AS__} syntax is similar to what many other assemblers
732 use; it is inspired in BSD 4.2
737 assembler, except that @code{_AS__} does not assemble Vax bit-fields.
741 * Pre-processing:: Pre-processing
742 * Whitespace:: Whitespace
743 * Comments:: Comments
744 * Symbol Intro:: Symbols
745 * Statements:: Statements
746 * Constants:: Constants
749 @node Pre-processing, Whitespace, Syntax, Syntax
750 @section Pre-Processing
752 @cindex preprocessing
755 @cindex whitespace, removed by preprocessor
757 adjusts and removes extra whitespace. It leaves one space or tab before
758 the keywords on a line, and turns any other whitespace on the line into
761 @cindex comments, removed by preprocessor
763 removes all comments, replacing them with a single space, or an
764 appropriate number of newlines.
766 @cindex constants, converted by preprocessor
768 converts character constants into the appropriate numeric values.
771 Excess whitespace, comments, and character constants
772 cannot be used in the portions of the input text that are not
775 @cindex turning preprocessing on and off
776 @cindex preprocessing, turning on and off
779 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
780 option is given, the input file will not be pre-processed. Within such
781 an input file, parts of the file can be pre-processed by putting a line
782 that says @code{#APP} before the text that should be pre-processed, and
783 putting a line that says @code{#NO_APP} after them. This feature is
784 mainly intend to support @code{asm} statements in compilers whose output
785 normally does not need to be pre-processed.
787 @node Whitespace, Comments, Pre-processing, Syntax
791 @dfn{Whitespace} is one or more blanks or tabs, in any order.
792 Whitespace is used to separate symbols, and to make programs neater for
793 people to read. Unless within character constants
794 (@pxref{Characters,,Character Constants}), any whitespace means the same
795 as exactly one space.
797 @node Comments, Symbol Intro, Whitespace, Syntax
801 There are two ways of rendering comments to @code{_AS__}. In both
802 cases the comment is equivalent to one space.
804 Anything from @samp{/*} through the next @samp{*/} is a comment.
805 This means you may not nest these comments.
809 The only way to include a newline ('\n') in a comment
810 is to use this sort of comment.
813 /* This sort of comment does not nest. */
816 @cindex line comment character
817 Anything from the @dfn{line comment} character to the next newline
818 is considered a comment and is ignored. The line comment character is
823 @samp{#} on the i960;
826 @samp{|} on the 680x0;
829 @samp{;} for the AMD 29K family;
832 @samp{;} for the _HOST__ family;
834 @pxref{_MACH_DEP__}. @refill
835 @c FIXME: fill in SPARC line comment char
838 On some machines there are two different line comment characters. One
839 will only begin a comment if it is the first non-whitespace character on
840 a line, while the other will always begin a comment.
844 @cindex lines starting with @code{#}
845 @cindex logical line numbers
846 To be compatible with past assemblers, a special interpretation is
847 given to lines that begin with @samp{#}. Following the @samp{#} an
848 absolute expression (@pxref{Expressions}) is expected: this will be
849 the logical line number of the @b{next} line. Then a string
850 (@xref{Strings}.) is allowed: if present it is a new logical file
851 name. The rest of the line, if any, should be whitespace.
853 If the first non-whitespace characters on the line are not numeric,
854 the line is ignored. (Just like a comment.)
856 # This is an ordinary comment.
857 # 42-6 "new_file_name" # New logical file name
858 # This is logical line # 36.
860 This feature is deprecated, and may disappear from future versions
863 @node Symbol Intro, Statements, Comments, Syntax
867 @cindex characters used in symbols
868 A @dfn{symbol} is one or more characters chosen from the set of all
869 letters (both upper and lower case), digits and
871 the three characters @samp{_.$}
874 the two characters @samp{_.}
876 On most machines, you can also use @code{$} in symbol names; exceptions
877 are noted in @ref{_MACH_DEP__}.
880 No symbol may begin with a digit. Case is significant.
881 There is no length limit: all characters are significant. Symbols are
882 delimited by characters not in that set, or by the beginning of a file
883 (since the source program must end with a newline, the end of a file is
884 not a possible symbol delimiter). @xref{Symbols}.
885 @cindex length of symbols
887 @node Statements, Constants, Symbol Intro, Syntax
890 @cindex statements, structure of
891 @cindex line separator character
892 @cindex statement separator character
894 _if__(!(_A29K__||_H8__))
895 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
896 semicolon (@samp{;}). The newline or semicolon is considered part of
897 the preceding statement. Newlines and semicolons within character
898 constants are an exception: they don't end statements.
899 _fi__(!(_A29K__||_H8__))
901 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
902 sign (@samp{@@}). The newline or at sign is considered part of the
903 preceding statement. Newlines and at signs within character constants
904 are an exception: they don't end statements.
907 A @dfn{statement} ends at a newline character (@samp{\n}) or a dollar
908 sign (@samp{$}). The newline or dollar sign is considered part of the
909 preceding statement. Newlines and dollar signs within character constants
910 are an exception: they don't end statements.
914 A @dfn{statement} ends at a newline character (@samp{\n}) or line
915 separator character. (The line separator is usually @samp{;}, unless
916 this conflicts with the comment character; @pxref{_MACH_DEP__}.) The
917 newline or separator character is considered part of the preceding
918 statement. Newlines and separators within character constants are an
919 exception: they don't end statements.
922 @cindex newline, required at file end
923 @cindex EOF, newline must precede
924 It is an error to end any statement with end-of-file: the last
925 character of any input file should be a newline.@refill
927 @cindex continuing statements
928 @cindex multi-line statements
929 @cindex statement on multiple lines
930 You may write a statement on more than one line if you put a
931 backslash (@kbd{\}) immediately in front of any newlines within the
932 statement. When @code{_AS__} reads a backslashed newline both
933 characters are ignored. You can even put backslashed newlines in
934 the middle of symbol names without changing the meaning of your
937 An empty statement is allowed, and may include whitespace. It is ignored.
939 @cindex instructions and directives
940 @cindex directives and instructions
941 @c "key symbol" is not used elsewhere in the document; seems pedantic to
942 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
944 A statement begins with zero or more labels, optionally followed by a
945 key symbol which determines what kind of statement it is. The key
946 symbol determines the syntax of the rest of the statement. If the
947 symbol begins with a dot @samp{.} then the statement is an assembler
948 directive: typically valid for any computer. If the symbol begins with
949 a letter the statement is an assembly language @dfn{instruction}: it
950 will assemble into a machine language instruction.
952 Different versions of @code{_AS__} for different computers will
953 recognize different instructions. In fact, the same symbol may
954 represent a different instruction in a different computer's assembly
958 @cindex @code{:} (label)
959 @cindex label (@code{:})
960 A label is a symbol immediately followed by a colon (@code{:}).
961 Whitespace before a label or after a colon is permitted, but you may not
962 have whitespace between a label's symbol and its colon. @xref{Labels}.
965 label: .directive followed by something
966 another_label: # This is an empty statement.
967 instruction operand_1, operand_2, @dots{}
970 @node Constants, , Statements, Syntax
974 A constant is a number, written so that its value is known by
975 inspection, without knowing any context. Like this:
977 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
978 .ascii "Ring the bell\7" # A string constant.
979 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
980 .float 0f-314159265358979323846264338327\
981 95028841971.693993751E-40 # - pi, a flonum.
985 * Characters:: Character Constants
986 * Numbers:: Number Constants
989 @node Characters, Numbers, Constants, Constants
990 @subsection Character Constants
992 @cindex character constants
993 @cindex constants, character
994 There are two kinds of character constants. A @dfn{character} stands
995 for one character in one byte and its value may be used in
996 numeric expressions. String constants (properly called string
997 @emph{literals}) are potentially many bytes and their values may not be
998 used in arithmetic expressions.
1002 * Chars:: Characters
1005 @node Strings, Chars, Characters, Characters
1006 @subsubsection Strings
1008 @cindex string constants
1009 @cindex constants, string
1010 A @dfn{string} is written between double-quotes. It may contain
1011 double-quotes or null characters. The way to get special characters
1012 into a string is to @dfn{escape} these characters: precede them with
1013 a backslash @samp{\} character. For example @samp{\\} represents
1014 one backslash: the first @code{\} is an escape which tells
1015 @code{_AS__} to interpret the second character literally as a backslash
1016 (which prevents @code{_AS__} from recognizing the second @code{\} as an
1017 escape character). The complete list of escapes follows.
1019 @cindex escape codes, character
1020 @cindex character escape codes
1023 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1026 @cindex @code{\b} (backspace character)
1027 @cindex backspace (@code{\b})
1028 Mnemonic for backspace; for ASCII this is octal code 010.
1031 @c Mnemonic for EOText; for ASCII this is octal code 004.
1034 @cindex @code{\f} (formfeed character)
1035 @cindex formfeed (@code{\f})
1036 Mnemonic for FormFeed; for ASCII this is octal code 014.
1039 @cindex @code{\n} (newline character)
1040 @cindex newline (@code{\n})
1041 Mnemonic for newline; for ASCII this is octal code 012.
1044 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1047 @cindex @code{\r} (carriage return character)
1048 @cindex carriage return (@code{\r})
1049 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1052 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1053 @c other assemblers.
1056 @cindex @code{\t} (tab)
1057 @cindex tab (@code{\t})
1058 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1061 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1062 @c @item \x @var{digit} @var{digit} @var{digit}
1063 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1065 @item \ @var{digit} @var{digit} @var{digit}
1066 @cindex @code{\@var{ddd}} (octal character code)
1067 @cindex octal character code (@code{\@var{ddd}})
1068 An octal character code. The numeric code is 3 octal digits.
1069 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1070 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1073 @cindex @code{\\} (@samp{\} character)
1074 @cindex backslash (@code{\\})
1075 Represents one @samp{\} character.
1078 @c Represents one @samp{'} (accent acute) character.
1079 @c This is needed in single character literals
1080 @c (@xref{Characters,,Character Constants}.) to represent
1084 @cindex @code{\"} (doublequote character)
1085 @cindex doublequote (@code{\"})
1086 Represents one @samp{"} character. Needed in strings to represent
1087 this character, because an unescaped @samp{"} would end the string.
1089 @item \ @var{anything-else}
1090 Any other character when escaped by @kbd{\} will give a warning, but
1091 assemble as if the @samp{\} was not present. The idea is that if
1092 you used an escape sequence you clearly didn't want the literal
1093 interpretation of the following character. However @code{_AS__} has no
1094 other interpretation, so @code{_AS__} knows it is giving you the wrong
1095 code and warns you of the fact.
1098 Which characters are escapable, and what those escapes represent,
1099 varies widely among assemblers. The current set is what we think
1100 the BSD 4.2 assembler recognizes, and is a subset of what most C
1101 compilers recognize. If you are in doubt, don't use an escape
1104 @node Chars, , Strings, Characters
1105 @subsubsection Characters
1107 @cindex single character constant
1108 @cindex character, single
1109 @cindex constant, single character
1110 A single character may be written as a single quote immediately
1111 followed by that character. The same escapes apply to characters as
1112 to strings. So if you want to write the character backslash, you
1113 must write @kbd{'\\} where the first @code{\} escapes the second
1114 @code{\}. As you can see, the quote is an acute accent, not a
1115 grave accent. A newline
1117 _if__(!(_A29K__||_H8__))
1118 (or semicolon @samp{;})
1119 _fi__(!(_A29K__||_H8__))
1121 (or at sign @samp{@@})
1124 (or dollar sign @samp{$})
1127 immediately following an acute accent is taken as a literal character
1128 and does not count as the end of a statement. The value of a character
1129 constant in a numeric expression is the machine's byte-wide code for
1130 that character. @code{_AS__} assumes your character code is ASCII:
1131 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1133 @node Numbers, , Characters, Constants
1134 @subsection Number Constants
1136 @cindex constants, number
1137 @cindex number constants
1138 @code{_AS__} distinguishes three kinds of numbers according to how they
1139 are stored in the target machine. @emph{Integers} are numbers that
1140 would fit into an @code{int} in the C language. @emph{Bignums} are
1141 integers, but they are stored in more than 32 bits. @emph{Flonums}
1142 are floating point numbers, described below.
1145 * Integers:: Integers
1148 _if__(_I960__&&!_GENERIC__)
1149 * Bit Fields:: Bit Fields
1150 _fi__(_I960__&&!_GENERIC__)
1153 @node Integers, Bignums, Numbers, Numbers
1154 @subsubsection Integers
1156 @cindex constants, integer
1158 @cindex binary integers
1159 @cindex integers, binary
1160 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1161 the binary digits @samp{01}.
1163 @cindex octal integers
1164 @cindex integers, octal
1165 An octal integer is @samp{0} followed by zero or more of the octal
1166 digits (@samp{01234567}).
1168 @cindex decimal integers
1169 @cindex integers, decimal
1170 A decimal integer starts with a non-zero digit followed by zero or
1171 more digits (@samp{0123456789}).
1173 @cindex hexadecimal integers
1174 @cindex integers, hexadecimal
1175 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1176 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1178 Integers have the usual values. To denote a negative integer, use
1179 the prefix operator @samp{-} discussed under expressions
1180 (@pxref{Prefix Ops,,Prefix Operators}).
1182 @node Bignums, Flonums, Integers, Numbers
1183 @subsubsection Bignums
1186 @cindex constants, bignum
1187 A @dfn{bignum} has the same syntax and semantics as an integer
1188 except that the number (or its negative) takes more than 32 bits to
1189 represent in binary. The distinction is made because in some places
1190 integers are permitted while bignums are not.
1192 _if__(_I960__&&!_GENERIC__)
1193 @node Flonums, Bit Fields, Bignums, Numbers
1194 _fi__(_I960__&&!_GENERIC__)
1195 _if__(_GENERIC__||!_I960__)
1196 @node Flonums, , Bignums, Numbers
1197 _fi__(_GENERIC__||!_I960__)
1198 @subsubsection Flonums
1200 @cindex floating point numbers
1201 @cindex constants, floating point
1203 @cindex precision, floating point
1204 A @dfn{flonum} represents a floating point number. The translation is
1205 indirect: a decimal floating point number from the text is converted by
1206 @code{_AS__} to a generic binary floating point number of more than
1207 sufficient precision. This generic floating point number is converted
1208 to a particular computer's floating point format (or formats) by a
1209 portion of @code{_AS__} specialized to that computer.
1211 A flonum is written by writing (in order)
1216 A letter, to tell @code{_AS__} the rest of the number is a flonum.
1218 @kbd{e} is recommended. Case is not important.
1220 @c FIXME: verify if flonum syntax really this vague for most cases
1221 (Any otherwise illegal letter
1222 will work here, but that might be changed. Vax BSD 4.2 assembler seems
1223 to allow any of @samp{defghDEFGH}.)
1226 _if__(_A29K__||_H8__)
1228 On the AMD 29K and H8/300 architectures, the letter must be:
1230 One of the letters @samp{DFPRSX} (in upper or lower case).
1231 _fi__(_A29K__||_H8__)
1234 On the Intel 960 architecture, the letter must be:
1236 One of the letters @samp{DFT} (in upper or lower case).
1239 An optional sign: either @samp{+} or @samp{-}.
1241 An optional @dfn{integer part}: zero or more decimal digits.
1243 An optional @dfn{fractional part}: @samp{.} followed by zero
1244 or more decimal digits.
1246 An optional exponent, consisting of:
1249 An @samp{E} or @samp{e}.
1250 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1251 @c principle this can perfectly well be different on different targets.
1253 Optional sign: either @samp{+} or @samp{-}.
1255 One or more decimal digits.
1259 At least one of the integer part or the fractional part must be
1260 present. The floating point number has the usual base-10 value.
1262 @code{_AS__} does all processing using integers. Flonums are computed
1263 independently of any floating point hardware in the computer running
1266 _if__(_I960__&&!_GENERIC__)
1267 @c Bit fields are written as a general facility but are also controlled
1268 @c by a conditional-compilation flag---which is as of now (21mar91)
1269 @c turned on only by the i960 config of GAS.
1270 @node Bit Fields, , Flonums, Numbers
1271 @subsubsection Bit Fields
1274 @cindex constants, bit field
1275 You can also define numeric constants as @dfn{bit fields}.
1276 specify two numbers separated by a colon---
1278 @var{mask}:@var{value}
1281 the first will act as a mask; @code{_AS__} will bitwise-and it with the
1284 The resulting number is then packed
1286 @c this conditional paren in case bit fields turned on elsewhere than 960
1287 (in host-dependent byte order)
1289 into a field whose width depends on which assembler directive has the
1290 bit-field as its argument. Overflow (a result from the bitwise and
1291 requiring more binary digits to represent) is not an error; instead,
1292 more constants are generated, of the specified width, beginning with the
1293 least significant digits.@refill
1295 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1296 @code{.short}, and @code{.word} accept bit-field arguments.
1297 _fi__(_I960__&&!_GENERIC__)
1299 @node Sections, Symbols, Syntax, Top
1300 @chapter Sections and Relocation
1305 * Secs Background:: Background
1306 * _LD__ Sections:: _LD__ Sections
1307 * _AS__ Sections:: _AS__ Internal Sections
1308 * Sub-Sections:: Sub-Sections
1312 @node Secs Background, _LD__ Sections, Sections, Sections
1315 Roughly, a section is a range of addresses, with no gaps; all data
1316 ``in'' those addresses is treated the same for some particular purpose.
1317 For example there may be a ``read only'' section.
1319 @cindex linker, and assembler
1320 @cindex assembler, and linker
1321 The linker @code{_LD__} reads many object files (partial programs) and
1322 combines their contents to form a runnable program. When @code{_AS__}
1323 emits an object file, the partial program is assumed to start at address
1324 0. @code{_LD__} will assign the final addresses the partial program
1325 occupies, so that different partial programs don't overlap. This is
1326 actually an over-simplification, but it will suffice to explain how
1327 @code{_AS__} uses sections.
1329 @code{_LD__} moves blocks of bytes of your program to their run-time
1330 addresses. These blocks slide to their run-time addresses as rigid
1331 units; their length does not change and neither does the order of bytes
1332 within them. Such a rigid unit is called a @emph{section}. Assigning
1333 run-time addresses to sections is called @dfn{relocation}. It includes
1334 the task of adjusting mentions of object-file addresses so they refer to
1335 the proper run-time addresses.
1337 For the H8/300, @code{_AS__} pads sections if needed to ensure they end
1338 on a word (sixteen bit) boundary.
1341 @cindex standard @code{_AS__} sections
1342 An object file written by @code{_AS__} has at least three sections, any
1343 of which may be empty. These are named @dfn{text}, @dfn{data} and
1348 When it generates COFF output,
1350 @code{_AS__} can also generate whatever other named sections you specify
1351 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1352 If you don't use any directives that place output in the @samp{.text}
1353 or @samp{.data} sections, these sections will still exist, but will be empty.
1356 Within the object file, the text section starts at address @code{0}, the
1357 data section follows, and the bss section follows the data section.
1359 To let @code{_LD__} know which data will change when the sections are
1360 relocated, and how to change that data, @code{_AS__} also writes to the
1361 object file details of the relocation needed. To perform relocation
1362 @code{_LD__} must know, each time an address in the object
1366 Where in the object file is the beginning of this reference to
1369 How long (in bytes) is this reference?
1371 Which section does the address refer to? What is the numeric value of
1373 (@var{address}) @minus{} (@var{start-address of section})?
1376 Is the reference to an address ``Program-Counter relative''?
1379 @cindex addresses, format of
1380 @cindex section-relative addressing
1381 In fact, every address @code{_AS__} ever uses is expressed as
1383 (@var{section}) + (@var{offset into section})
1386 Further, every expression @code{_AS__} computes is of this section-relative
1387 nature. @dfn{Absolute expression} means an expression with section
1388 ``absolute'' (@pxref{_LD__ Sections}). A @dfn{pass1 expression} means
1389 an expression with section ``pass1'' (@pxref{_AS__ Sections,,_AS__
1390 Internal Sections}). In this manual we use the notation @{@var{secname}
1391 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1393 Apart from text, data and bss sections you need to know about the
1394 @dfn{absolute} section. When @code{_LD__} mixes partial programs,
1395 addresses in the absolute section remain unchanged. For example, address
1396 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}.
1397 Although two partial programs' data sections will not overlap addresses
1398 after linking, @emph{by definition} their absolute sections will overlap.
1399 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1400 address when the program is running as address @code{@{absolute@ 239@}} in any
1401 other partial program.
1403 The idea of sections is extended to the @dfn{undefined} section. Any
1404 address whose section is unknown at assembly time is by definition
1405 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1406 Since numbers are always defined, the only way to generate an undefined
1407 address is to mention an undefined symbol. A reference to a named
1408 common block would be such a symbol: its value is unknown at assembly
1409 time so it has section @emph{undefined}.
1411 By analogy the word @emph{section} is used to describe groups of sections in
1412 the linked program. @code{_LD__} puts all partial programs' text
1413 sections in contiguous addresses in the linked program. It is
1414 customary to refer to the @emph{text section} of a program, meaning all
1415 the addresses of all partial program's text sections. Likewise for
1416 data and bss sections.
1418 Some sections are manipulated by @code{_LD__}; others are invented for
1419 use of @code{_AS__} and have no meaning except during assembly.
1421 @node _LD__ Sections, _AS__ Sections, Secs Background, Sections
1422 @section _LD__ Sections
1423 @code{_LD__} deals with just four kinds of sections, summarized below.
1427 _if__(_GENERIC__||_COFF__)
1428 @cindex named sections
1429 @cindex sections, named
1430 @item named sections
1431 _fi__(_GENERIC__||_COFF__)
1432 _if__(_AOUT__||_BOUT__)
1433 @cindex text section
1434 @cindex data section
1437 _fi__(_AOUT__||_BOUT__)
1438 These sections hold your program. @code{_AS__} and @code{_LD__} treat them as
1439 separate but equal sections. Anything you can say of one section is
1441 _if__(_AOUT__||_BOUT__)
1442 When the program is running, however, it is
1443 customary for the text section to be unalterable. The
1444 text section is often shared among processes: it will contain
1445 instructions, constants and the like. The data section of a running
1446 program is usually alterable: for example, C variables would be stored
1447 in the data section.
1448 _fi__(_AOUT__||_BOUT__)
1452 This section contains zeroed bytes when your program begins running. It
1453 is used to hold unitialized variables or common storage. The length of
1454 each partial program's bss section is important, but because it starts
1455 out containing zeroed bytes there is no need to store explicit zero
1456 bytes in the object file. The bss section was invented to eliminate
1457 those explicit zeros from object files.
1459 @cindex absolute section
1460 @item absolute section
1461 Address 0 of this section is always ``relocated'' to runtime address 0.
1462 This is useful if you want to refer to an address that @code{_LD__} must
1463 not change when relocating. In this sense we speak of absolute
1464 addresses being ``unrelocatable'': they don't change during relocation.
1466 @cindex undefined section
1467 @item undefined section
1468 This ``section'' is a catch-all for address references to objects not in
1469 the preceding sections.
1470 @c FIXME: ref to some other doc on obj-file formats could go here.
1473 @cindex relocation example
1474 An idealized example of three relocatable sections follows.
1476 The example uses the traditional section names @samp{.text} and @samp{.data}.
1478 Memory addresses are on the horizontal axis.
1482 @c END TEXI2ROFF-KILL
1485 partial program # 1: |ttttt|dddd|00|
1492 partial program # 2: |TTT|DDD|000|
1495 +--+---+-----+--+----+---+-----+~~
1496 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1497 +--+---+-----+--+----+---+-----+~~
1499 addresses: 0 @dots{}
1503 @c FIXME make sure no page breaks inside figure!!
1506 \line{\it Partial program \#1: \hfil}
1507 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1508 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1510 \line{\it Partial program \#2: \hfil}
1511 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1512 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1514 \line{\it linked program: \hfil}
1515 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1516 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1517 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1518 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1520 \line{\it addresses: \hfil}
1524 @c END TEXI2ROFF-KILL
1526 @node _AS__ Sections, Sub-Sections, _LD__ Sections, Sections
1527 @section _AS__ Internal Sections
1529 @cindex internal @code{_AS__} sections
1530 @cindex sections in messages, internal
1531 These sections are meant only for the internal use of @code{_AS__}. They
1532 have no meaning at run-time. You don't really need to know about these
1533 sections for most purposes; but they can be mentioned in @code{_AS__}
1534 warning messages, so it might be helpful to have an idea of their
1535 meanings to @code{_AS__}. These sections are used to permit the
1536 value of every expression in your assembly language program to be a
1537 section-relative address.
1541 @cindex absent (internal section)
1542 An expression was expected and none was found.
1544 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1545 @cindex assembler internal logic error
1546 An internal assembler logic error has been found. This means there is a
1547 bug in the assembler.
1550 @cindex bignum/flonum (internal section)
1551 If a number can't be written as a C @code{int} constant (a bignum or a
1552 flonum, but not an integer), it is recorded as belonging to this
1553 ``section''. @code{_AS__} has to remember that a flonum or a bignum
1554 does not fit into 32 bits, and cannot be an argument (@pxref{Arguments})
1555 in an expression: this is done by making a flonum or bignum be in a
1556 separate internal section. This is purely for internal @code{_AS__}
1557 convenience; bignum/flonum section behaves similarly to absolute
1561 @cindex pass1 (internal section)
1562 The expression was impossible to evaluate in the first pass. The
1563 assembler will attempt a second pass (second reading of the source) to
1564 evaluate the expression. Your expression mentioned an undefined symbol
1565 in a way that defies the one-pass (section + offset in section) assembly
1566 process. No compiler need emit such an expression.
1569 @emph{Warning:} the second pass is currently not implemented. @code{_AS__}
1570 will abort with an error message if one is required.
1573 @item difference section
1574 @cindex difference (internal section)
1575 As an assist to the C compiler, expressions of the forms
1577 (@var{undefined symbol}) @minus{} (@var{expression})
1578 @var{something} @minus{} (@var{undefined symbol})
1579 (@var{undefined symbol}) @minus{} (@var{undefined symbol})
1582 are permitted, and belong to the difference section. @code{_AS__}
1583 re-evaluates such expressions after the source file has been read and
1584 the symbol table built. If by that time there are no undefined symbols
1585 in the expression then the expression assumes a new section. The
1586 intention is to permit statements like
1587 @samp{.word label - base_of_table}
1588 to be assembled in one pass where both @code{label} and
1589 @code{base_of_table} are undefined. This is useful for compiling C and
1590 Algol switch statements, Pascal case statements, FORTRAN computed goto
1591 statements and the like.
1593 @c FIXME item transfer[t] vector preload
1594 @c FIXME item transfer[t] vector postload
1595 @c FIXME item register
1598 @node Sub-Sections, bss, _AS__ Sections, Sections
1599 @section Sub-Sections
1601 @cindex numbered subsections
1602 @cindex grouping data
1603 _if__(_AOUT__||_BOUT__)
1608 fall into two sections: text and data.
1609 _fi__(_AOUT__||_BOUT__)
1610 You may have separate groups of
1611 _if__(_COFF__||_GENERIC__)
1612 data in named sections
1613 _fi__(_COFF__||_GENERIC__)
1614 _if__((_AOUT__||_BOUT__)&&!_GENERIC__)
1616 _fi__((_AOUT__||_BOUT__)&&!_GENERIC__)
1617 that you want to end up near to each other in the object
1618 file, even though they are not contiguous in the assembler source.
1619 @code{_AS__} allows you to use @dfn{subsections} for this purpose.
1620 Within each section, there can be numbered subsections with
1621 values from 0 to 8192. Objects assembled into the same subsection will
1622 be grouped with other objects in the same subsection when they are all
1623 put into the object file. For example, a compiler might want to store
1624 constants in the text section, but might not want to have them
1625 interspersed with the program being assembled. In this case, the
1626 compiler could issue a @samp{.text 0} before each section of code being
1627 output, and a @samp{.text 1} before each group of constants being output.
1629 Subsections are optional. If you don't use subsections, everything
1630 will be stored in subsection number zero.
1633 Each subsection is zero-padded up to a multiple of four bytes.
1634 (Subsections may be padded a different amount on different flavors
1639 On the H8/300 platform, each subsection is zero-padded to a word
1640 boundary (two bytes).
1643 @c FIXME section padding (alignment)?
1644 @c Rich Pixley says padding here depends on target obj code format; that
1645 @c doesn't seem particularly useful to say without further elaboration,
1646 @c so for now I say nothing about it. If this is a generic BFD issue,
1647 @c these paragraphs might need to vanish from this manual, and be
1648 @c discussed in BFD chapter of binutils (or some such).
1651 On the AMD 29K family, no particular padding is added to section or
1652 subsection sizes; _AS__ forces no alignment on this platform.
1656 Subsections appear in your object file in numeric order, lowest numbered
1657 to highest. (All this to be compatible with other people's assemblers.)
1658 The object file contains no representation of subsections; @code{_LD__} and
1659 other programs that manipulate object files will see no trace of them.
1660 They just see all your text subsections as a text section, and all your
1661 data subsections as a data section.
1663 To specify which subsection you want subsequent statements assembled
1664 into, use a numeric argument to specify it, in a @samp{.text
1665 @var{expression}} or a @samp{.data @var{expression}} statement.
1668 When generating COFF output, you
1673 can also use an extra subsection
1674 argument with arbitrary named sections: @samp{.section @var{name},
1677 @var{Expression} should be an absolute expression.
1678 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
1679 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
1680 begins in @code{text 0}. For instance:
1682 .text 0 # The default subsection is text 0 anyway.
1683 .ascii "This lives in the first text subsection. *"
1685 .ascii "But this lives in the second text subsection."
1687 .ascii "This lives in the data section,"
1688 .ascii "in the first data subsection."
1690 .ascii "This lives in the first text section,"
1691 .ascii "immediately following the asterisk (*)."
1694 Each section has a @dfn{location counter} incremented by one for every
1695 byte assembled into that section. Because subsections are merely a
1696 convenience restricted to @code{_AS__} there is no concept of a subsection
1697 location counter. There is no way to directly manipulate a location
1698 counter---but the @code{.align} directive will change it, and any label
1699 definition will capture its current value. The location counter of the
1700 section that statements are being assembled into is said to be the
1701 @dfn{active} location counter.
1703 @node bss, , Sub-Sections, Sections
1704 @section bss Section
1707 @cindex common variable storage
1708 The bss section is used for local common variable storage.
1709 You may allocate address space in the bss section, but you may
1710 not dictate data to load into it before your program executes. When
1711 your program starts running, all the contents of the bss
1712 section are zeroed bytes.
1714 Addresses in the bss section are allocated with special directives; you
1715 may not assemble anything directly into the bss section. Hence there
1716 are no bss subsections. @xref{Comm,,@code{.comm}},
1717 @pxref{Lcomm,,@code{.lcomm}}.
1719 @node Symbols, Expressions, Sections, Top
1723 Symbols are a central concept: the programmer uses symbols to name
1724 things, the linker uses symbols to link, and the debugger uses symbols
1728 @cindex debuggers, and symbol order
1729 @emph{Warning:} @code{_AS__} does not place symbols in the object file in
1730 the same order they were declared. This may break some debuggers.
1735 * Setting Symbols:: Giving Symbols Other Values
1736 * Symbol Names:: Symbol Names
1737 * Dot:: The Special Dot Symbol
1738 * Symbol Attributes:: Symbol Attributes
1741 @node Labels, Setting Symbols, Symbols, Symbols
1745 A @dfn{label} is written as a symbol immediately followed by a colon
1746 @samp{:}. The symbol then represents the current value of the
1747 active location counter, and is, for example, a suitable instruction
1748 operand. You are warned if you use the same symbol to represent two
1749 different locations: the first definition overrides any other
1752 @node Setting Symbols, Symbol Names, Labels, Symbols
1753 @section Giving Symbols Other Values
1755 @cindex assigning values to symbols
1756 @cindex symbol values, assigning
1757 A symbol can be given an arbitrary value by writing a symbol, followed
1758 by an equals sign @samp{=}, followed by an expression
1759 (@pxref{Expressions}). This is equivalent to using the @code{.set}
1760 directive. @xref{Set,,@code{.set}}.
1762 @node Symbol Names, Dot, Setting Symbols, Symbols
1763 @section Symbol Names
1765 @cindex symbol names
1766 @cindex names, symbol
1767 Symbol names begin with a letter or with one of
1774 (On most machines, you can also use @code{$} in symbol names; exceptions
1775 are noted in @ref{_MACH_DEP__}.)
1778 That character may be followed by any string of digits, letters,
1780 underscores and dollar signs.
1784 dollar signs (unless otherwise noted in @ref{_MACH_DEP__}),
1788 Case of letters is significant:
1789 @code{foo} is a different symbol name than @code{Foo}.
1792 For the AMD 29K family, @samp{?} is also allowed in the
1793 body of a symbol name, though not at its beginning.
1796 Each symbol has exactly one name. Each name in an assembly language
1797 program refers to exactly one symbol. You may use that symbol name any
1798 number of times in a program.
1800 @subheading Local Symbol Names
1802 @cindex local symbol names
1803 @cindex symbol names, local
1804 @cindex temporary symbol names
1805 @cindex symbol names, temporary
1806 Local symbols help compilers and programmers use names temporarily.
1807 There are ten local symbol names, which are re-used throughout the
1808 program. You may refer to them using the names @samp{0} @samp{1}
1809 @dots{} @samp{9}. To define a local symbol, write a label of the form
1810 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
1811 recent previous definition of that symbol write @samp{@b{N}b}, using the
1812 same digit as when you defined the label. To refer to the next
1813 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
1814 a choice of 10 forward references. The @samp{b} stands for
1815 ``backwards'' and the @samp{f} stands for ``forwards''.
1817 Local symbols are not emitted by the current GNU C compiler.
1819 There is no restriction on how you can use these labels, but
1820 remember that at any point in the assembly you can refer to at most
1821 10 prior local labels and to at most 10 forward local labels.
1823 Local symbol names are only a notation device. They are immediately
1824 transformed into more conventional symbol names before the assembler
1825 uses them. The symbol names stored in the symbol table, appearing in
1826 error messages and optionally emitted to the object file have these
1831 All local labels begin with @samp{L}. Normally both @code{_AS__} and
1832 @code{_LD__} forget symbols that start with @samp{L}. These labels are
1833 used for symbols you are never intended to see. If you give the
1834 @samp{-L} option then @code{_AS__} will retain these symbols in the
1835 object file. If you also instruct @code{_LD__} to retain these symbols,
1836 you may use them in debugging.
1839 If the label is written @samp{0:} then the digit is @samp{0}.
1840 If the label is written @samp{1:} then the digit is @samp{1}.
1841 And so on up through @samp{9:}.
1844 This unusual character is included so you don't accidentally invent
1845 a symbol of the same name. The character has ASCII value
1848 @item @emph{ordinal number}
1849 This is a serial number to keep the labels distinct. The first
1850 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
1851 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
1855 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
1856 @code{3:} is named @code{L3@ctrl{A}44}.
1858 @node Dot, Symbol Attributes, Symbol Names, Symbols
1859 @section The Special Dot Symbol
1861 @cindex dot (symbol)
1862 @cindex @code{.} (symbol)
1863 @cindex current address
1864 @cindex location counter
1865 The special symbol @samp{.} refers to the current address that
1866 @code{_AS__} is assembling into. Thus, the expression @samp{melvin:
1867 .long .} will cause @code{melvin} to contain its own address.
1868 Assigning a value to @code{.} is treated the same as a @code{.org}
1869 directive. Thus, the expression @samp{.=.+4} is the same as saying
1877 @node Symbol Attributes, , Dot, Symbols
1878 @section Symbol Attributes
1880 @cindex symbol attributes
1881 @cindex attributes, symbol
1882 Every symbol has, as well as its name, the attributes ``Value'' and
1883 ``Type''. Depending on output format, symbols can also have auxiliary
1886 The detailed definitions are in _0__<a.out.h>_1__.
1889 If you use a symbol without defining it, @code{_AS__} assumes zero for
1890 all these attributes, and probably won't warn you. This makes the
1891 symbol an externally defined symbol, which is generally what you
1895 * Symbol Value:: Value
1896 * Symbol Type:: Type
1897 _if__(_AOUT__||_BOUT__)
1898 _if__(_GENERIC__||!_BOUT__)
1899 * a.out Symbols:: Symbol Attributes: @code{a.out}
1900 _fi__(_GENERIC__||!_BOUT__)
1901 _if__(_BOUT__&&!_GENERIC__)
1902 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
1903 _fi__(_BOUT__&&!_GENERIC__)
1904 _fi__(_AOUT__||_BOUT__)
1906 * COFF Symbols:: Symbol Attributes for COFF
1910 @node Symbol Value, Symbol Type, Symbol Attributes, Symbol Attributes
1913 @cindex value of a symbol
1914 @cindex symbol value
1915 The value of a symbol is (usually) 32 bits. For a symbol which labels a
1916 location in the text, data, bss or absolute sections the value is the
1917 number of addresses from the start of that section to the label.
1918 Naturally for text, data and bss sections the value of a symbol changes
1919 as @code{_LD__} changes section base addresses during linking. Absolute
1920 symbols' values do not change during linking: that is why they are
1923 The value of an undefined symbol is treated in a special way. If it is
1924 0 then the symbol is not defined in this assembler source program, and
1925 @code{_LD__} will try to determine its value from other programs it is
1926 linked with. You make this kind of symbol simply by mentioning a symbol
1927 name without defining it. A non-zero value represents a @code{.comm}
1928 common declaration. The value is how much common storage to reserve, in
1929 bytes (addresses). The symbol refers to the first address of the
1932 _if__(!(_AOUT__||_BOUT__))
1933 @node Symbol Type, COFF Symbols, Symbol Value, Symbol Attributes
1934 _fi__(!(_AOUT__||_BOUT__))
1935 _if__((_AOUT__||_BOUT__))
1936 @node Symbol Type, a.out Symbols, Symbol Value, Symbol Attributes
1937 _fi__((_AOUT__||_BOUT__))
1940 @cindex type of a symbol
1942 The type attribute of a symbol contains relocation (section)
1943 information, any flag settings indicating that a symbol is external, and
1944 (optionally), other information for linkers and debuggers. The exact
1945 format depends on the object-code output format in use.
1947 _if__(_AOUT__||_BOUT__)
1949 @node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes
1952 @node a.out Symbols, , Symbol Type, Symbol Attributes
1954 _if__(_BOUT__&&!_GENERIC__)
1955 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
1957 @cindex @code{b.out} symbol attributes
1958 @cindex symbol attributes, @code{b.out}
1959 These symbol attributes appear only when @code{_AS__} is configured for
1960 one of the Berkeley-descended object output formats.
1961 _fi__(_BOUT__&&!_GENERIC__)
1962 _if__(_GENERIC__||!_BOUT__)
1963 @subsection Symbol Attributes: @code{a.out}
1964 _fi__(_GENERIC__||!_BOUT__)
1966 @cindex @code{a.out} symbol attributes
1967 @cindex symbol attributes, @code{a.out}
1970 * Symbol Desc:: Descriptor
1971 * Symbol Other:: Other
1974 @node Symbol Desc, Symbol Other, a.out Symbols, a.out Symbols
1975 @subsubsection Descriptor
1977 @cindex descriptor, of @code{a.out} symbol
1978 This is an arbitrary 16-bit value. You may establish a symbol's
1979 descriptor value by using a @code{.desc} statement
1980 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
1983 @node Symbol Other, , Symbol Desc, a.out Symbols
1984 @subsubsection Other
1986 @cindex other attribute, of @code{a.out} symbol
1987 This is an arbitrary 8-bit value. It means nothing to @code{_AS__}.
1988 _fi__(_AOUT__||_BOUT__)
1991 _if__(!(_AOUT__||_BOUT__))
1992 @node COFF Symbols, , Symbol Type, Symbol Attributes
1993 _fi__(!(_AOUT__||_BOUT__))
1994 _if__(_AOUT__||_BOUT__)
1995 @node COFF Symbols, , a.out Symbols, Symbol Attributes
1996 _fi__(_AOUT__||_BOUT__)
1997 @subsection Symbol Attributes for COFF
1999 @cindex COFF symbol attributes
2000 @cindex symbol attributes, COFF
2002 The COFF format supports a multitude of auxiliary symbol attributes;
2003 like the primary symbol attributes, they are set between @code{.def} and
2004 @code{.endef} directives.
2006 @subsubsection Primary Attributes
2008 @cindex primary attributes, COFF symbols
2009 The symbol name is set with @code{.def}; the value and type,
2010 respectively, with @code{.val} and @code{.type}.
2012 @subsubsection Auxiliary Attributes
2014 @cindex auxiliary attributes, COFF symbols
2015 The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl},
2016 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2017 information for COFF.
2020 @node Expressions, Pseudo Ops, Symbols, Top
2021 @chapter Expressions
2025 @cindex numeric values
2026 An @dfn{expression} specifies an address or numeric value.
2027 Whitespace may precede and/or follow an expression.
2030 * Empty Exprs:: Empty Expressions
2031 * Integer Exprs:: Integer Expressions
2034 @node Empty Exprs, Integer Exprs, Expressions, Expressions
2035 @section Empty Expressions
2037 @cindex empty expressions
2038 @cindex expressions, empty
2039 An empty expression has no value: it is just whitespace or null.
2040 Wherever an absolute expression is required, you may omit the
2041 expression and @code{_AS__} will assume a value of (absolute) 0. This
2042 is compatible with other assemblers.
2044 @node Integer Exprs, , Empty Exprs, Expressions
2045 @section Integer Expressions
2047 @cindex integer expressions
2048 @cindex expressions, integer
2049 An @dfn{integer expression} is one or more @emph{arguments} delimited
2050 by @emph{operators}.
2053 * Arguments:: Arguments
2054 * Operators:: Operators
2055 * Prefix Ops:: Prefix Operators
2056 * Infix Ops:: Infix Operators
2059 @node Arguments, Operators, Integer Exprs, Integer Exprs
2060 @subsection Arguments
2062 @cindex expression arguments
2063 @cindex arguments in expressions
2064 @cindex operands in expressions
2065 @cindex arithmetic operands
2066 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2067 contexts arguments are sometimes called ``arithmetic operands''. In
2068 this manual, to avoid confusing them with the ``instruction operands'' of
2069 the machine language, we use the term ``argument'' to refer to parts of
2070 expressions only, reserving the word ``operand'' to refer only to machine
2071 instruction operands.
2073 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2074 @var{section} is one of text, data, bss, absolute,
2075 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2078 Numbers are usually integers.
2080 A number can be a flonum or bignum. In this case, you are warned
2081 that only the low order 32 bits are used, and @code{_AS__} pretends
2082 these 32 bits are an integer. You may write integer-manipulating
2083 instructions that act on exotic constants, compatible with other
2086 @cindex subexpressions
2087 Subexpressions are a left parenthesis @samp{(} followed by an integer
2088 expression, followed by a right parenthesis @samp{)}; or a prefix
2089 operator followed by an argument.
2091 @node Operators, Prefix Ops, Arguments, Integer Exprs
2092 @subsection Operators
2094 @cindex operators, in expressions
2095 @cindex arithmetic functions
2096 @cindex functions, in expressions
2097 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2098 operators are followed by an argument. Infix operators appear
2099 between their arguments. Operators may be preceded and/or followed by
2102 @node Prefix Ops, Infix Ops, Operators, Integer Exprs
2103 @subsection Prefix Operator
2105 @cindex prefix operators
2106 @code{_AS__} has the following @dfn{prefix operators}. They each take
2107 one argument, which must be absolute.
2109 @c the tex/end tex stuff surrounding this small table is meant to make
2110 @c it align, on the printed page, with the similar table in the next
2111 @c section (which is inside an enumerate).
2113 \global\advance\leftskip by \itemindent
2118 @dfn{Negation}. Two's complement negation.
2120 @dfn{Complementation}. Bitwise not.
2124 \global\advance\leftskip by -\itemindent
2127 @node Infix Ops, , Prefix Ops, Integer Exprs
2128 @subsection Infix Operators
2130 @cindex infix operators
2131 @cindex operators, permitted arguments
2132 @dfn{Infix operators} take two arguments, one on either side. Operators
2133 have precedence, but operations with equal precedence are performed left
2134 to right. Apart from @code{+} or @code{-}, both arguments must be
2135 absolute, and the result is absolute.
2138 @cindex operator precedence
2139 @cindex precedence of operators
2146 @dfn{Multiplication}.
2149 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2156 @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__}
2160 @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__}
2164 Intermediate precedence
2169 @dfn{Bitwise Inclusive Or}.
2175 @dfn{Bitwise Exclusive Or}.
2178 @dfn{Bitwise Or Not}.
2186 @cindex addition, permitted arguments
2187 @cindex plus, permitted arguments
2188 @cindex arguments for addition
2189 @dfn{Addition}. If either argument is absolute, the result
2190 has the section of the other argument.
2191 If either argument is pass1 or undefined, the result is pass1.
2192 Otherwise @code{+} is illegal.
2195 @cindex subtraction, permitted arguments
2196 @cindex minus, permitted arguments
2197 @cindex arguments for subtraction
2198 @dfn{Subtraction}. If the right argument is absolute, the
2199 result has the section of the left argument.
2200 If either argument is pass1 the result is pass1.
2201 If either argument is undefined the result is difference section.
2202 If both arguments are in the same section, the result is absolute---provided
2203 that section is one of text, data or bss.
2204 Otherwise subtraction is illegal.
2208 The sense of the rule for addition is that it's only meaningful to add
2209 the @emph{offsets} in an address; you can only have a defined section in
2210 one of the two arguments.
2212 Similarly, you can't subtract quantities from two different sections.
2214 @node Pseudo Ops, _MACH_DEP__, Expressions, Top
2215 @chapter Assembler Directives
2217 @cindex directives, machine independent
2218 @cindex pseudo-ops, machine independent
2219 @cindex machine independent directives
2220 All assembler directives have names that begin with a period (@samp{.}).
2221 The rest of the name is letters, usually in lower case.
2223 This chapter discusses directives present regardless of the target
2224 machine configuration for the GNU assembler.
2226 @xref{_MACH_DEP__} for additional directives.
2230 * Abort:: @code{.abort}
2232 * coff-ABORT:: @code{.ABORT}
2234 _if__(_BOUT__&&!_COFF__)
2235 * bout-ABORT:: @code{.ABORT}
2236 _fi__(_BOUT__&&!_COFF__)
2237 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2238 * App-File:: @code{.app-file @var{string}}
2239 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2240 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2241 * Byte:: @code{.byte @var{expressions}}
2242 * Comm:: @code{.comm @var{symbol} , @var{length} }
2243 * Data:: @code{.data @var{subsection}}
2244 _if__(_COFF__||_BOUT__)
2245 * Def:: @code{.def @var{name}}
2246 _fi__(_COFF__||_BOUT__)
2247 _if__(_AOUT__||_BOUT__)
2248 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2249 _fi__(_AOUT__||_BOUT__)
2250 _if__(_COFF__||_BOUT__)
2252 _fi__(_COFF__||_BOUT__)
2253 * Double:: @code{.double @var{flonums}}
2254 * Eject:: @code{.eject}
2255 * Else:: @code{.else}
2256 _if__(_COFF__||_BOUT__)
2257 * Endef:: @code{.endef}
2258 _fi__(_COFF__||_BOUT__)
2259 * Endif:: @code{.endif}
2260 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2261 * Extern:: @code{.extern}
2262 _if__(_GENERIC__||!_A29K__)
2263 * File:: @code{.file @var{string}}
2264 _fi__(_GENERIC__||!_A29K__)
2265 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2266 * Float:: @code{.float @var{flonums}}
2267 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2268 * hword:: @code{.hword @var{expressions}}
2269 * Ident:: @code{.ident}
2270 * If:: @code{.if @var{absolute expression}}
2271 * Include:: @code{.include "@var{file}"}
2272 * Int:: @code{.int @var{expressions}}
2273 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2274 * Lflags:: @code{.lflags}
2275 _if__(_GENERIC__||!_A29K__)
2276 * Line:: @code{.line @var{line-number}}
2277 _fi__(_GENERIC__||!_A29K__)
2278 * Ln:: @code{.ln @var{line-number}}
2279 * List:: @code{.list}
2280 * Long:: @code{.long @var{expressions}}
2281 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2282 * Nolist:: @code{.nolist}
2283 * Octa:: @code{.octa @var{bignums}}
2284 * Org:: @code{.org @var{new-lc} , @var{fill}}
2285 * Psize:: @code{.psize @var{lines}, @var{columns}}
2286 * Quad:: @code{.quad @var{bignums}}
2287 * Sbttl:: @code{.sbttl "@var{subheading}"}
2288 _if__(_COFF__||_BOUT__)
2289 * Scl:: @code{.scl @var{class}}
2290 _fi__(_COFF__||_BOUT__)
2292 * Section:: @code{.section @var{name}, @var{subsection}}
2294 * Set:: @code{.set @var{symbol}, @var{expression}}
2295 * Short:: @code{.short @var{expressions}}
2296 * Single:: @code{.single @var{flonums}}
2297 _if__(_COFF__||_BOUT__)
2298 * Size:: @code{.size}
2299 _fi__(_COFF__||_BOUT__)
2300 * Space:: @code{.space @var{size} , @var{fill}}
2301 _if__(_GENERIC__||!_H8__)
2302 * Stab:: @code{.stabd, .stabn, .stabs}
2303 _fi__(_GENERIC__||!_H8__)
2304 _if__(_COFF__||_BOUT__)
2305 * Tag:: @code{.tag @var{structname}}
2306 _fi__(_COFF__||_BOUT__)
2307 * Text:: @code{.text @var{subsection}}
2308 * Title:: @code{.title "@var{heading}"}
2309 _if__(_COFF__||_BOUT__)
2310 * Type:: @code{.type @var{int}}
2311 * Val:: @code{.val @var{addr}}
2312 _fi__(_COFF__||_BOUT__)
2313 * Word:: @code{.word @var{expressions}}
2314 * Deprecated:: Deprecated Directives
2318 @node Abort, coff-ABORT, Pseudo Ops, Pseudo Ops
2320 _if__((!_COFF__) && _BOUT__)
2321 @node Abort, bout-ABORT, Pseudo Ops, Pseudo Ops
2322 _fi__((!_COFF__) && _BOUT__)
2323 _if__(! (_BOUT__ || _COFF__) )
2324 @node Abort, Align, Pseudo Ops, Pseudo Ops
2325 _fi__(! (_BOUT__ || _COFF__) )
2326 @section @code{.abort}
2328 @cindex @code{abort} directive
2329 @cindex stopping the assembly
2330 This directive stops the assembly immediately. It is for
2331 compatibility with other assemblers. The original idea was that the
2332 assembly language source would be piped into the assembler. If the sender
2333 of the source quit, it could use this directive tells @code{_AS__} to
2334 quit also. One day @code{.abort} will not be supported.
2337 @node coff-ABORT, Align, Abort, Pseudo Ops
2338 @section @code{.ABORT}
2340 @cindex @code{ABORT} directive
2341 When producing COFF output, @code{_AS__} accepts this directive as a
2342 synonym for @samp{.abort}.
2347 @node bout-ABORT, Align, Abort, Pseudo Ops
2348 @section @code{.ABORT}
2350 @cindex @code{ABORT} directive
2353 When producing @code{b.out} output, @code{_AS__} accepts this directive,
2357 _if__( ! (_COFF__ || _BOUT__) )
2358 @node Align, App-File, Abort, Pseudo Ops
2359 _fi__( ! (_COFF__ || _BOUT__) )
2361 @node Align, App-File, coff-ABORT, Pseudo Ops
2363 _if__( _BOUT__ && (! _COFF__))
2364 @node Align, App-File, bout-ABORT, Pseudo Ops
2365 _fi__( _BOUT__ && (! _COFF__))
2366 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2368 @cindex padding the location counter
2369 @cindex advancing location counter
2370 @cindex location counter, advancing
2371 @cindex @code{align} directive
2372 Pad the location counter (in the current subsection) to a particular
2373 storage boundary. The first expression (which must be absolute) is the
2374 number of low-order zero bits the location counter will have after
2375 advancement. For example @samp{.align 3} will advance the location
2376 counter until it a multiple of 8. If the location counter is already a
2377 multiple of 8, no change is needed.
2379 The second expression (also absolute) gives the value to be stored in
2380 the padding bytes. It (and the comma) may be omitted. If it is
2381 omitted, the padding bytes are zero.
2383 @node App-File, Ascii, Align, Pseudo Ops
2384 @section @code{.app-file @var{string}}
2386 @cindex logical file name
2387 @cindex file name, logical
2388 @cindex @code{app-file} directive
2391 (which may also be spelled @samp{.file})
2393 tells @code{_AS__} that we are about to start a new
2394 logical file. @var{string} is the new file name. In general, the
2395 filename is recognized whether or not it is surrounded by quotes @samp{"};
2396 but if you wish to specify an empty file name is permitted,
2397 you must give the quotes--@code{""}. This statement may go away in
2398 future: it is only recognized to be compatible with old @code{_AS__}
2401 @node Ascii, Asciz, App-File, Pseudo Ops
2402 @section @code{.ascii "@var{string}"}@dots{}
2404 @cindex @code{ascii} directive
2405 @cindex string literals
2406 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2407 separated by commas. It assembles each string (with no automatic
2408 trailing zero byte) into consecutive addresses.
2410 @node Asciz, Byte, Ascii, Pseudo Ops
2411 @section @code{.asciz "@var{string}"}@dots{}
2413 @cindex @code{asciz} directive
2414 @cindex zero-terminated strings
2415 @cindex null-terminated strings
2416 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2417 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2419 @node Byte, Comm, Asciz, Pseudo Ops
2420 @section @code{.byte @var{expressions}}
2422 @cindex @code{byte} directive
2423 @cindex integers, one byte
2424 @code{.byte} expects zero or more expressions, separated by commas.
2425 Each expression is assembled into the next byte.
2427 @node Comm, Data, Byte, Pseudo Ops
2428 @section @code{.comm @var{symbol} , @var{length} }
2430 @cindex @code{comm} directive
2431 @cindex symbol, common
2432 @code{.comm} declares a named common area in the bss section. Normally
2433 @code{_LD__} reserves memory addresses for it during linking, so no partial
2434 program defines the location of the symbol. Use @code{.comm} to tell
2435 @code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__}
2436 will allocate space for each @code{.comm} symbol that is at least as
2437 long as the longest @code{.comm} request in any of the partial programs
2438 linked. @var{length} is an absolute expression.
2440 _if__(_COFF__ || _BOUT__)
2441 @node Data, Def, Comm, Pseudo Ops
2442 _fi__(_COFF__ || _BOUT__)
2443 _if__(!(_COFF__ || _BOUT__) && _AOUT__)
2444 @node Data, Desc, Comm, Pseudo Ops
2445 _fi__(!(_COFF__ || _BOUT__) && _AOUT__)
2446 _if__(! (_COFF__ || _BOUT__ || _AOUT__) )
2447 @c Well, this *might* happen...
2448 @node Data, Double, Comm, Pseudo Ops
2449 _fi__(! (_COFF__ || _BOUT__ || _AOUT__) )
2450 @section @code{.data @var{subsection}}
2452 @cindex @code{data} directive
2453 @code{.data} tells @code{_AS__} to assemble the following statements onto the
2454 end of the data subsection numbered @var{subsection} (which is an
2455 absolute expression). If @var{subsection} is omitted, it defaults
2458 _if__(_COFF__ || _BOUT__)
2459 _if__(_AOUT__ || _BOUT__)
2460 @node Def, Desc, Data, Pseudo Ops
2461 _fi__(_AOUT__ || _BOUT__)
2462 _if__(!(_AOUT__ || _BOUT__))
2463 @node Def, Dim, Data, Pseudo Ops
2464 _fi__(!(_AOUT__ || _BOUT__))
2465 @section @code{.def @var{name}}
2467 @cindex @code{def} directive
2468 @cindex COFF symbols, debugging
2469 @cindex debugging COFF symbols
2470 Begin defining debugging information for a symbol @var{name}; the
2471 definition extends until the @code{.endef} directive is encountered.
2474 This directive is only observed when @code{_AS__} is configured for COFF
2475 format output; when producing @code{b.out}, @samp{.def} is recognized,
2478 _fi__(_COFF__ || _BOUT__)
2480 _if__(_AOUT__||_BOUT__)
2481 _if__(_COFF__||_BOUT__)
2482 @node Desc, Dim, Def, Pseudo Ops
2483 _fi__(_COFF__||_BOUT__)
2484 _if__(!(_COFF__||_BOUT__))
2485 @node Desc, Double, Data, Pseudo Ops
2486 _fi__(!(_COFF__||_BOUT__))
2487 @section @code{.desc @var{symbol}, @var{abs-expression}}
2489 @cindex @code{desc} directive
2490 @cindex COFF symbol descriptor
2491 @cindex symbol descriptor, COFF
2492 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2493 to the low 16 bits of an absolute expression.
2496 The @samp{.desc} directive is not available when @code{_AS__} is
2497 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2498 object format. For the sake of compatibility, @code{_AS__} will accept
2499 it, but produce no output, when configured for COFF.
2501 _fi__(_AOUT__||_BOUT__)
2503 _if__(_COFF__ || _BOUT__)
2504 _if__(_AOUT__ || _BOUT__)
2505 @node Dim, Double, Desc, Pseudo Ops
2506 _fi__(_AOUT__ || _BOUT__)
2507 _if__(!(_AOUT__ || _BOUT__))
2508 @node Dim, Double, Def, Pseudo Ops
2509 _fi__(!(_AOUT__ || _BOUT__))
2510 @section @code{.dim}
2512 @cindex @code{dim} directive
2513 @cindex COFF auxiliary symbol information
2514 @cindex auxiliary symbol information, COFF
2515 This directive is generated by compilers to include auxiliary debugging
2516 information in the symbol table. It is only permitted inside
2517 @code{.def}/@code{.endef} pairs.
2520 @samp{.dim} is only meaningful when generating COFF format output; when
2521 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2524 _fi__(_COFF__ || _BOUT__)
2526 _if__(_COFF__||_BOUT__)
2527 @node Double, Eject, Dim, Pseudo Ops
2528 _fi__(_COFF__||_BOUT__)
2529 _if__(!(_COFF__||_BOUT__))
2530 @node Double, Eject, Desc, Pseudo Ops
2531 _fi__(!(_COFF__||_BOUT__))
2532 @section @code{.double @var{flonums}}
2534 @cindex @code{double} directive
2535 @cindex floating point numbers (double)
2536 @code{.double} expects zero or more flonums, separated by commas. It
2537 assembles floating point numbers.
2539 The exact kind of floating point numbers emitted depends on how
2540 @code{_AS__} is configured. @xref{_MACH_DEP__}.
2542 _if__((!_GENERIC__) && _IEEEFLOAT__)
2543 On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers
2544 in @sc{ieee} format.
2545 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2547 @node Eject, Else, Double, Pseudo Ops
2548 @section @code{.eject}
2550 @cindex @code{eject} directive
2551 @cindex new page, in listings
2552 @cindex page, in listings
2553 @cindex listing control: new page
2554 Force a page break at this point, when generating assembly listings.
2556 _if__(_COFF__||_BOUT__)
2557 @node Else, Endef, Eject, Pseudo Ops
2558 _fi__(_COFF__||_BOUT__)
2559 _if__(!(_COFF__||_BOUT__))
2560 @node Else, Endif, Eject, Pseudo Ops
2561 _fi__(!(_COFF__||_BOUT__))
2562 @section @code{.else}
2564 @cindex @code{else} directive
2565 @code{.else} is part of the @code{_AS__} support for conditional
2566 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2567 of code to be assembled if the condition for the preceding @code{.if}
2571 @node End, Endef, Else, Pseudo Ops
2572 @section @code{.end}
2574 @cindex @code{end} directive
2575 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2576 meant to do something eventually (which is why it isn't documented here
2577 as "for compatibility with blah").
2580 _if__(_COFF__||_BOUT__)
2581 @node Endef, Endif, Else, Pseudo Ops
2582 @section @code{.endef}
2584 @cindex @code{endef} directive
2585 This directive flags the end of a symbol definition begun with
2589 @samp{.endef} is only meaningful when generating COFF format output; if
2590 @code{_AS__} is configured to generate @code{b.out}, it accepts this
2591 directive but ignores it.
2593 _fi__(_COFF__||_BOUT__)
2595 _if__(_COFF__||_BOUT__)
2596 @node Endif, Equ, Endef, Pseudo Ops
2597 _fi__(_COFF__||_BOUT__)
2598 _if__(!(_COFF__||_BOUT__))
2599 @node Endif, Equ, Else, Pseudo Ops
2600 _fi__(!(_COFF__||_BOUT__))
2601 @section @code{.endif}
2603 @cindex @code{endif} directive
2604 @code{.endif} is part of the @code{_AS__} support for conditional assembly;
2605 it marks the end of a block of code that is only assembled
2606 conditionally. @xref{If,,@code{.if}}.
2608 @node Equ, Extern, Endif, Pseudo Ops
2609 @section @code{.equ @var{symbol}, @var{expression}}
2611 @cindex @code{equ} directive
2612 @cindex assigning values to symbols
2613 @cindex symbols, assigning values to
2614 This directive sets the value of @var{symbol} to @var{expression}.
2615 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2617 _if__(_GENERIC__||!_A29K__)
2618 @node Extern, File, Equ, Pseudo Ops
2619 _fi__(_GENERIC__||!_A29K__)
2620 _if__(_A29K__&&!_GENERIC__)
2621 @node Extern, Fill, Equ, Pseudo Ops
2622 _fi__(_A29K__&&!_GENERIC__)
2623 @section @code{.extern}
2625 @cindex @code{extern} directive
2626 @code{.extern} is accepted in the source program---for compatibility
2627 with other assemblers---but it is ignored. @code{_AS__} treats
2628 all undefined symbols as external.
2630 _if__(_GENERIC__||!_A29K__)
2631 @node File, Fill, Extern, Pseudo Ops
2632 @section @code{.file @var{string}}
2634 @cindex @code{file} directive
2635 @cindex logical file name
2636 @cindex file name, logical
2637 @code{.file} (which may also be spelled @samp{.app-file}) tells
2638 @code{_AS__} that we are about to start a new logical file.
2639 @var{string} is the new file name. In general, the filename is
2640 recognized whether or not it is surrounded by quotes @samp{"}; but if
2641 you wish to specify an empty file name, you must give the
2642 quotes--@code{""}. This statement may go away in future: it is only
2643 recognized to be compatible with old @code{_AS__} programs.
2645 In some configurations of @code{_AS__}, @code{.file} has already been
2646 removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}.
2648 _fi__(_GENERIC__||!_A29K__)
2650 _if__(_GENERIC__||!_A29K__)
2651 @node Fill, Float, File, Pseudo Ops
2652 _fi__(_GENERIC__||!_A29K__)
2653 _if__(_A29K__&&!_GENERIC__)
2654 @node Fill, Float, Extern, Pseudo Ops
2655 _fi__(_A29K__&&!_GENERIC__)
2656 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2658 @cindex @code{fill} directive
2659 @cindex writing patterns in memory
2660 @cindex patterns, writing in memory
2661 @var{result}, @var{size} and @var{value} are absolute expressions.
2662 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2663 may be zero or more. @var{Size} may be zero or more, but if it is
2664 more than 8, then it is deemed to have the value 8, compatible with
2665 other people's assemblers. The contents of each @var{repeat} bytes
2666 is taken from an 8-byte number. The highest order 4 bytes are
2667 zero. The lowest order 4 bytes are @var{value} rendered in the
2668 byte-order of an integer on the computer @code{_AS__} is assembling for.
2669 Each @var{size} bytes in a repetition is taken from the lowest order
2670 @var{size} bytes of this number. Again, this bizarre behavior is
2671 compatible with other people's assemblers.
2673 @var{size} and @var{value} are optional.
2674 If the second comma and @var{value} are absent, @var{value} is
2675 assumed zero. If the first comma and following tokens are absent,
2676 @var{size} is assumed to be 1.
2678 @node Float, Global, Fill, Pseudo Ops
2679 @section @code{.float @var{flonums}}
2681 @cindex floating point numbers (single)
2682 @cindex @code{float} directive
2683 This directive assembles zero or more flonums, separated by commas. It
2684 has the same effect as @code{.single}.
2686 The exact kind of floating point numbers emitted depends on how
2687 @code{_AS__} is configured.
2690 _if__((!_GENERIC__) && _IEEEFLOAT__)
2691 On the _HOST__ family, @code{.float} emits 32-bit floating point numbers
2692 in @sc{ieee} format.
2693 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2695 @node Global, hword, Float, Pseudo Ops
2696 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2698 @cindex @code{global} directive
2699 @cindex symbol, making visible to linker
2700 @code{.global} makes the symbol visible to @code{_LD__}. If you define
2701 @var{symbol} in your partial program, its value is made available to
2702 other partial programs that are linked with it. Otherwise,
2703 @var{symbol} will take its attributes from a symbol of the same name
2704 from another partial program it is linked with.
2706 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2707 compatibility with other assemblers.
2709 _if__(_AOUT__||_BOUT__||_COFF__)
2710 @node hword, Ident, Global, Pseudo Ops
2711 _fi__(_AOUT__||_BOUT__||_COFF__)
2712 _if__(!(_AOUT__||_BOUT__||_COFF__))
2713 @node hword, If, Global, Pseudo Ops
2714 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2715 @section @code{.hword @var{expressions}}
2717 @cindex @code{hword} directive
2718 @cindex integers, 16-bit
2719 @cindex numbers, 16-bit
2720 @cindex sixteen bit integers
2721 This expects zero or more @var{expressions}, and emits
2722 a 16 bit number for each.
2725 This directive is a synonym for @samp{.short}; depending on the target
2726 architecture, it may also be a synonym for @samp{.word}.
2728 _if__( _W32__ && !_GENERIC__ )
2729 This directive is a synonym for @samp{.short}.
2730 _fi__( _W32__ && !_GENERIC__ )
2731 _if__(_W16__ && !_GENERIC__ )
2732 This directive is a synonym for both @samp{.short} and @samp{.word}.
2733 _fi__(_W16__ && !_GENERIC__ )
2735 _if__(_AOUT__||_BOUT__||_COFF__)
2736 @node Ident, If, hword, Pseudo Ops
2737 @section @code{.ident}
2739 @cindex @code{ident} directive
2740 This directive is used by some assemblers to place tags in object files.
2741 @code{_AS__} simply accepts the directive for source-file
2742 compatibility with such assemblers, but does not actually emit anything
2744 _fi__(_AOUT__||_BOUT__||_COFF__)
2746 _if__(_AOUT__||_BOUT__||_COFF__)
2747 @node If, Include, Ident, Pseudo Ops
2748 _fi__(_AOUT__||_BOUT__||_COFF__)
2749 _if__(!(_AOUT__||_BOUT__||_COFF__))
2750 @node If, Include, hword, Pseudo Ops
2751 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2752 @section @code{.if @var{absolute expression}}
2754 @cindex conditional assembly
2755 @cindex @code{if} directive
2756 @code{.if} marks the beginning of a section of code which is only
2757 considered part of the source program being assembled if the argument
2758 (which must be an @var{absolute expression}) is non-zero. The end of
2759 the conditional section of code must be marked by @code{.endif}
2760 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
2761 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
2763 The following variants of @code{.if} are also supported:
2765 @item .ifdef @var{symbol}
2766 @cindex @code{ifdef} directive
2767 Assembles the following section of code if the specified @var{symbol}
2772 @cindex @code{ifeqs} directive
2773 Not yet implemented.
2776 @item .ifndef @var{symbol}
2777 @itemx ifnotdef @var{symbol}
2778 @cindex @code{ifndef} directive
2779 @cindex @code{ifnotdef} directive
2780 Assembles the following section of code if the specified @var{symbol}
2781 has not been defined. Both spelling variants are equivalent.
2785 Not yet implemented.
2789 @node Include, Int, If, Pseudo Ops
2790 @section @code{.include "@var{file}"}
2792 @cindex @code{include} directive
2793 @cindex supporting files, including
2794 @cindex files, including
2795 This directive provides a way to include supporting files at specified
2796 points in your source program. The code from @var{file} is assembled as
2797 if it followed the point of the @code{.include}; when the end of the
2798 included file is reached, assembly of the original file continues. You
2799 can control the search paths used with the @samp{-I} command-line option
2800 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
2803 @node Int, Lcomm, Include, Pseudo Ops
2804 @section @code{.int @var{expressions}}
2806 @cindex @code{int} directive
2807 _if__(_GENERIC__||!_H8__)
2808 @cindex integers, 32-bit
2809 _fi__(_GENERIC__||!_H8__)
2810 Expect zero or more @var{expressions}, of any section, separated by
2811 commas. For each expression, emit a
2812 _if__(_GENERIC__||!_H8__)
2814 _fi__(_GENERIC__||!_H8__)
2815 _if__(_H8__&&!_GENERIC__)
2817 _fi__(_H8__&&!_GENERIC__)
2818 number that will, at run
2819 time, be the value of that expression. The byte order of the
2820 expression depends on what kind of computer will run the program.
2822 @node Lcomm, Lflags, Int, Pseudo Ops
2823 @section @code{.lcomm @var{symbol} , @var{length}}
2825 @cindex @code{lcomm} directive
2826 @cindex local common symbols
2827 @cindex symbols, local common
2828 Reserve @var{length} (an absolute expression) bytes for a local common
2829 denoted by @var{symbol}. The section and value of @var{symbol} are
2830 those of the new local common. The addresses are allocated in the bss
2831 section, so at run-time the bytes will start off zeroed. @var{Symbol}
2832 is not declared global (@pxref{Global,,@code{.global}}), so is normally
2833 not visible to @code{_LD__}.
2835 _if__(_GENERIC__||(!_A29K__))
2836 @node Lflags, Line, Lcomm, Pseudo Ops
2837 _fi__(_GENERIC__||(!_A29K__))
2838 _if__((!_GENERIC__)&& _A29K__)
2839 @node Lflags, Ln, Lcomm, Pseudo Ops
2840 _fi__((!_GENERIC__)&& _A29K__)
2841 @section @code{.lflags}
2843 @cindex @code{lflags} directive (ignored)
2844 @code{_AS__} accepts this directive, for compatibility with other
2845 assemblers, but ignores it.
2847 _if__(_GENERIC__ || !_A29K__)
2848 @node Line, Ln, Lflags, Pseudo Ops
2849 @section @code{.line @var{line-number}}
2851 @cindex @code{line} directive
2852 _fi__(_GENERIC__ || (!_A29K__))
2853 _if__(_A29K__ && (!_GENERIC__))
2854 @node Ln, List, Lflags, Pseudo Ops
2855 @section @code{.ln @var{line-number}}
2857 @cindex @code{ln} directive
2858 _fi__(_A29K__ && (!_GENERIC__))
2859 @cindex logical line number
2860 _if__(_AOUT__||_BOUT__)
2861 Tell @code{_AS__} to change the logical line number. @var{line-number} must be
2862 an absolute expression. The next line will have that logical line
2863 number. So any other statements on the current line (after a statement
2869 _if__(! (_A29K__||_H8__) )
2871 _fi__(! (_A29K__||_H8__) )
2873 character @samp{@@})
2879 will be reported as on logical line number
2880 @var{line-number} @minus{} 1.
2881 One day this directive will be unsupported: it is used only
2882 for compatibility with existing assembler programs. @refill
2884 _if__(_GENERIC__ && _A29K__)
2885 @emph{Warning:} In the AMD29K configuration of _AS__, this command is
2886 only available with the name @code{.ln}, rather than as either
2887 @code{.line} or @code{.ln}.
2888 _fi__(_GENERIC__ && _A29K__)
2889 _fi__(_AOUT__||_BOUT__)
2892 Even though this is a directive associated with the @code{a.out} or
2893 @code{b.out} object-code formats, @code{_AS__} will still recognize it
2894 when producing COFF output, and will treat @samp{.line} as though it
2895 were the COFF @samp{.ln} @emph{if} it is found outside a
2896 @code{.def}/@code{.endef} pair.
2898 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
2899 used by compilers to generate auxiliary symbol information for
2903 _if__(_AOUT__&&(_GENERIC__||!_A29K__))
2904 @node Ln, List, Line, Pseudo Ops
2905 @section @code{.ln @var{line-number}}
2907 @cindex @code{ln} directive
2908 @samp{.ln} is a synonym for @samp{.line}.
2909 _fi__(_AOUT__&&(_GENERIC__||!_A29K__))
2910 _if__(_COFF__&&!_AOUT__)
2911 @node Ln, List, Line, Pseudo Ops
2912 @section @code{.ln @var{line-number}}
2914 @cindex @code{ln} directive
2915 Tell @code{_AS__} to change the logical line number. @var{line-number}
2916 must be an absolute expression. The next line will have that logical
2917 line number, so any other statements on the current line (after a
2918 statement separator character @code{;}) will be reported as on logical
2919 line number @var{line-number} @minus{} 1.
2922 This directive is accepted, but ignored, when @code{_AS__} is configured for
2923 @code{b.out}; its effect is only associated with COFF output format.
2925 _fi__(_COFF__&&!_AOUT__)
2927 @node List, Long, Ln, Pseudo Ops
2928 @section @code{.list}
2930 @cindex @code{list} directive
2931 @cindex listing control, turning on
2932 Control (in conjunction with the @code{.nolist} directive) whether or
2933 not assembly listings are generated. These two directives maintain an
2934 internal counter (which is zero initially). @code{.list} increments the
2935 counter, and @code{.nolist} decrements it. Assembly listings are
2936 generated whenever the counter is greater than zero.
2938 By default, listings are disabled. When you enable them (with the
2939 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
2940 the initial value of the listing counter is one.
2942 @node Long, Lsym, List, Pseudo Ops
2943 @section @code{.long @var{expressions}}
2945 @cindex @code{long} directive
2946 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
2948 @node Lsym, Nolist, Long, Pseudo Ops
2949 @section @code{.lsym @var{symbol}, @var{expression}}
2951 @cindex @code{lsym} directive
2952 @cindex symbol, not referenced in assembly
2953 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
2954 the hash table, ensuring it cannot be referenced by name during the
2955 rest of the assembly. This sets the attributes of the symbol to be
2956 the same as the expression value:
2958 @var{other} = @var{descriptor} = 0
2959 @var{type} = @r{(section of @var{expression})}
2960 @var{value} = @var{expression}
2963 The new symbol is not flagged as external.
2965 @node Nolist, Octa, Lsym, Pseudo Ops
2966 @section @code{.nolist}
2968 @cindex @code{nolist} directive
2969 @cindex listing control, turning off
2970 Control (in conjunction with the @code{.list} directive) whether or
2971 not assembly listings are generated. These two directives maintain an
2972 internal counter (which is zero initially). @code{.list} increments the
2973 counter, and @code{.nolist} decrements it. Assembly listings are
2974 generated whenever the counter is greater than zero.
2976 @node Octa, Org, Nolist, Pseudo Ops
2977 @section @code{.octa @var{bignums}}
2979 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
2980 @cindex @code{octa} directive
2981 @cindex integer, 16-byte
2982 @cindex sixteen byte integer
2983 This directive expects zero or more bignums, separated by commas. For each
2984 bignum, it emits a 16-byte integer.
2986 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
2987 hence @emph{octa}-word for 16 bytes.
2989 @node Org, Psize, Octa, Pseudo Ops
2990 @section @code{.org @var{new-lc} , @var{fill}}
2992 @cindex @code{org} directive
2993 @cindex location counter, advancing
2994 @cindex advancing location counter
2995 @cindex current address, advancing
2996 @code{.org} will advance the location counter of the current section to
2997 @var{new-lc}. @var{new-lc} is either an absolute expression or an
2998 expression with the same section as the current subsection. That is,
2999 you can't use @code{.org} to cross sections: if @var{new-lc} has the
3000 wrong section, the @code{.org} directive is ignored. To be compatible
3001 with former assemblers, if the section of @var{new-lc} is absolute,
3002 @code{_AS__} will issue a warning, then pretend the section of @var{new-lc}
3003 is the same as the current subsection.
3005 @code{.org} may only increase the location counter, or leave it
3006 unchanged; you cannot use @code{.org} to move the location counter
3009 @c double negative used below "not undefined" because this is a specific
3010 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
3011 @c section. pesch@cygnus.com 18feb91
3012 Because @code{_AS__} tries to assemble programs in one pass @var{new-lc}
3013 may not be undefined. If you really detest this restriction we eagerly await
3014 a chance to share your improved assembler.
3016 Beware that the origin is relative to the start of the section, not
3017 to the start of the subsection. This is compatible with other
3018 people's assemblers.
3020 When the location counter (of the current subsection) is advanced, the
3021 intervening bytes are filled with @var{fill} which should be an
3022 absolute expression. If the comma and @var{fill} are omitted,
3023 @var{fill} defaults to zero.
3025 @node Psize, Quad, Org, Pseudo Ops
3026 @section @code{.psize @var{lines} , @var{columns}}
3028 @cindex @code{psize} directive
3029 @cindex listing control: paper size
3030 @cindex paper size, for listings
3031 Use this directive to declare the number of lines---and, optionally, the
3032 number of columns---to use for each page, when generating listings.
3034 If you don't use @code{.psize}, listings will use a default line-count
3035 of 60. You may omit the comma and @var{columns} specification; the
3036 default width is 200 columns.
3038 @code{_AS__} will generate formfeeds whenever the specified number of
3039 lines is exceeded (or whenever you explicitly request one, using
3042 If you specify @var{lines} as @code{0}, no formfeeds are generated save
3043 those explicitly specified with @code{.eject}.
3045 @node Quad, Sbttl, Psize, Pseudo Ops
3046 @section @code{.quad @var{bignums}}
3048 @cindex @code{quad} directive
3049 @code{.quad} expects zero or more bignums, separated by commas. For
3050 each bignum, it emits
3051 _if__(_GENERIC__||(!_I960__))
3052 an 8-byte integer. If the bignum won't fit in 8
3053 bytes, it prints a warning message; and just takes the lowest order 8
3054 bytes of the bignum.@refill
3055 @cindex eight-byte integer
3056 @cindex integer, 8-byte
3058 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
3059 hence @emph{quad}-word for 8 bytes.
3060 _fi__(_GENERIC__||(!_I960__))
3061 _if__(_I960__&&(!_GENERIC__))
3062 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
3063 warning message; and just takes the lowest order 16 bytes of the
3065 @cindex sixteen-byte integer
3066 @cindex integer, 16-byte
3067 _fi__(_I960__&&(!_GENERIC__))
3069 _if__(_COFF__||_BOUT__)
3070 @node Sbttl, Scl, Quad, Pseudo Ops
3071 _fi__(_COFF__||_BOUT__)
3072 _if__(!(_COFF__||_BOUT__))
3073 @node Sbttl, Set, Quad, Pseudo Ops
3074 _fi__(!(_COFF__||_BOUT__))
3075 @section @code{.sbttl "@var{subheading}"}
3077 @cindex @code{sbttl} directive
3078 @cindex subtitles for listings
3079 @cindex listing control: subtitle
3080 Use @var{subheading} as the title (third line, immediately after the
3081 title line) when generating assembly listings.
3083 This directive affects subsequent pages, as well as the current page if
3084 it appears within ten lines of the top of a page.
3086 _if__(_COFF__||_BOUT__)
3088 @node Scl, Set, Sbttl, Pseudo Ops
3091 @node Scl, Section, Sbttl, Pseudo Ops
3093 @section @code{.scl @var{class}}
3095 @cindex @code{scl} directive
3096 @cindex symbol storage class (COFF)
3097 @cindex COFF symbol storage class
3098 Set the storage-class value for a symbol. This directive may only be
3099 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3100 whether a symbol is static or external, or it may record further
3101 symbolic debugging information.
3104 The @samp{.scl} directive is primarily associated with COFF output; when
3105 configured to generate @code{b.out} output format, @code{_AS__} will
3106 accept this directive but ignore it.
3108 _fi__(_COFF__||_BOUT__)
3111 @node Section, Set, Scl, Pseudo Ops
3112 @section @code{.section @var{name}, @var{subsection}}
3114 @cindex @code{section} directive
3115 @cindex named section (COFF)
3116 @cindex COFF named section
3117 Assemble the following code into end of subsection numbered
3118 @var{subsection} in the COFF named section @var{name}. If you omit
3119 @var{subsection}, @code{_AS__} uses subsection number zero.
3120 @samp{.section .text} is equivalent to the @code{.text} directive;
3121 @samp{.section .data} is equivalent to the @code{.data} directive.
3123 @node Set, Short, Section, Pseudo Ops
3126 @node Set, Short, Scl, Pseudo Ops
3128 _if__(!(_COFF__||_BOUT__))
3129 @node Set, Short, Quad, Pseudo Ops
3130 _fi__(!(_COFF__||_BOUT__))
3131 @section @code{.set @var{symbol}, @var{expression}}
3133 @cindex @code{set} directive
3134 @cindex symbol value, setting
3135 This directive sets the value of @var{symbol} to @var{expression}. This
3136 will change @var{symbol}'s value and type to conform to
3137 @var{expression}. If @var{symbol} was flagged as external, it remains
3138 flagged. (@xref{Symbol Attributes}.)
3140 You may @code{.set} a symbol many times in the same assembly.
3141 If the expression's section is unknowable during pass 1, a second
3142 pass over the source program will be forced. The second pass is
3143 currently not implemented. @code{_AS__} will abort with an error
3144 message if one is required.
3146 If you @code{.set} a global symbol, the value stored in the object
3147 file is the last value stored into it.
3149 @node Short, Single, Set, Pseudo Ops
3150 @section @code{.short @var{expressions}}
3152 @cindex @code{short} directive
3153 _if__(_GENERIC__ || _W16__)
3154 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3156 In some configurations, however, @code{.short} and @code{.word} generate
3157 numbers of different lengths; @pxref{_MACH_DEP__}.
3159 _fi__(_GENERIC__|| _W16__)
3160 _if__((!_GENERIC__) && _W32__)
3161 This expects zero or more @var{expressions}, and emits
3162 a 16 bit number for each.
3163 _fi__((!_GENERIC__) && _W32__)
3164 _if__(_COFF__||_BOUT__)
3165 @node Single, Size, Short, Pseudo Ops
3166 _fi__(_COFF__||_BOUT__)
3167 _if__(!(_COFF__||_BOUT__))
3168 @node Single, Space, Short, Pseudo Ops
3169 _fi__(!(_COFF__||_BOUT__))
3170 @section @code{.single @var{flonums}}
3172 @cindex @code{single} directive
3173 @cindex floating point numbers (single)
3174 This directive assembles zero or more flonums, separated by commas. It
3175 has the same effect as @code{.float}.
3177 The exact kind of floating point numbers emitted depends on how
3178 @code{_AS__} is configured. @xref{_MACH_DEP__}.
3180 _if__((!_GENERIC__) && _IEEEFLOAT__)
3181 On the _HOST__ family, @code{.single} emits 32-bit floating point
3182 numbers in @sc{ieee} format.
3183 _fi__((!_GENERIC__) && _IEEEFLOAT__)
3185 _if__(_COFF__||_BOUT__)
3186 @node Size, Space, Single, Pseudo Ops
3187 @section @code{.size}
3189 @cindex @code{size} directive
3190 This directive is generated by compilers to include auxiliary debugging
3191 information in the symbol table. It is only permitted inside
3192 @code{.def}/@code{.endef} pairs.
3195 @samp{.size} is only meaningful when generating COFF format output; when
3196 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3199 _fi__(_COFF__||_BOUT__)
3202 @node Space, Tag, Size, Pseudo Ops
3205 _if__(_COFF__||_BOUT__)
3206 @node Space, Stab, Size, Pseudo Ops
3207 _fi__(_COFF__||_BOUT__)
3208 _if__(!(_COFF__||_BOUT__))
3209 @node Space, Stab, Single, Pseudo Ops
3210 _fi__(!(_COFF__||_BOUT__))
3212 _if__(_GENERIC__ || !_A29K__)
3213 @section @code{.space @var{size} , @var{fill}}
3215 @cindex @code{space} directive
3216 @cindex filling memory
3217 This directive emits @var{size} bytes, each of value @var{fill}. Both
3218 @var{size} and @var{fill} are absolute expressions. If the comma
3219 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3220 _fi__(_GENERIC__ || !_A29K__)
3223 @section @code{.space}
3225 @cindex @code{space} directive
3226 On the AMD 29K, this directive is ignored; it is accepted for
3227 compatibility with other AMD 29K assemblers.
3230 @emph{Warning:} In other versions of the GNU assembler, the directive
3231 @code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}.
3235 _if__(_GENERIC__||!_H8__)
3236 _if__(_AOUT__||_BOUT__||_COFF__)
3237 _if__(_COFF__||_BOUT__)
3238 @node Stab, Tag, Space, Pseudo Ops
3239 _fi__(_COFF__||_BOUT__)
3240 _if__(!(_COFF__||_BOUT__))
3241 @node Stab, Text, Space, Pseudo Ops
3242 _fi__(!(_COFF__||_BOUT__))
3243 @section @code{.stabd, .stabn, .stabs}
3245 @cindex symbolic debuggers, information for
3246 @cindex @code{stab@var{x}} directives
3247 There are three directives that begin @samp{.stab}.
3248 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3249 The symbols are not entered in the @code{_AS__} hash table: they
3250 cannot be referenced elsewhere in the source file.
3251 Up to five fields are required:
3254 This is the symbol's name. It may contain any character except @samp{\000},
3255 so is more general than ordinary symbol names. Some debuggers used to
3256 code arbitrarily complex structures into symbol names using this field.
3258 An absolute expression. The symbol's type is set to the low 8
3259 bits of this expression.
3260 Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on
3263 An absolute expression.
3264 The symbol's ``other'' attribute is set to the low 8 bits of this expression.
3266 An absolute expression.
3267 The symbol's descriptor is set to the low 16 bits of this expression.
3269 An absolute expression which becomes the symbol's value.
3272 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3273 or @code{.stabs} statement, the symbol has probably already been created
3274 and you will get a half-formed symbol in your object file. This is
3275 compatible with earlier assemblers!
3278 @cindex @code{stabd} directive
3279 @item .stabd @var{type} , @var{other} , @var{desc}
3281 The ``name'' of the symbol generated is not even an empty string.
3282 It is a null pointer, for compatibility. Older assemblers used a
3283 null pointer so they didn't waste space in object files with empty
3286 The symbol's value is set to the location counter,
3287 relocatably. When your program is linked, the value of this symbol
3288 will be where the location counter was when the @code{.stabd} was
3291 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3292 @cindex @code{stabn} directive
3293 The name of the symbol is set to the empty string @code{""}.
3295 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3296 @cindex @code{stabs} directive
3297 All five fields are specified.
3299 _fi__(_AOUT__||_BOUT__||_COFF__)
3300 _fi__(_GENERIC__||!_H8__)
3302 _if__(_COFF__||_BOUT__)
3304 @node Tag, Text, Stab, Pseudo Ops
3307 @node Tag, Text, Space, Pseudo Ops
3309 @section @code{.tag @var{structname}}
3311 @cindex COFF structure debugging
3312 @cindex structure debugging, COFF
3313 @cindex @code{tag} directive
3314 This directive is generated by compilers to include auxiliary debugging
3315 information in the symbol table. It is only permitted inside
3316 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3317 definitions in the symbol table with instances of those structures.
3320 @samp{.tag} is only used when generating COFF format output; when
3321 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3324 _fi__(_COFF__||_BOUT__)
3326 _if__(_COFF__||_BOUT__)
3327 @node Text, Title, Tag, Pseudo Ops
3328 _fi__(_COFF__||_BOUT__)
3329 _if__(!(_COFF__||_BOUT__))
3330 @node Text, Title, Stab, Pseudo Ops
3331 _fi__(!(_COFF__||_BOUT__))
3332 @section @code{.text @var{subsection}}
3334 @cindex @code{text} directive
3335 Tells @code{_AS__} to assemble the following statements onto the end of
3336 the text subsection numbered @var{subsection}, which is an absolute
3337 expression. If @var{subsection} is omitted, subsection number zero
3340 _if__(_COFF__||_BOUT__)
3341 @node Title, Type, Text, Pseudo Ops
3342 _fi__(_COFF__||_BOUT__)
3343 _if__(!(_COFF__||_BOUT__))
3344 @node Title, Word, Text, Pseudo Ops
3345 _fi__(!(_COFF__||_BOUT__))
3346 @section @code{.title "@var{heading}"}
3348 @cindex @code{title} directive
3349 @cindex listing control: title line
3350 Use @var{heading} as the title (second line, immediately after the
3351 source file name and pagenumber) when generating assembly listings.
3353 This directive affects subsequent pages, as well as the current page if
3354 it appears within ten lines of the top of a page.
3356 _if__(_COFF__||_BOUT__)
3357 @node Type, Val, Title, Pseudo Ops
3358 @section @code{.type @var{int}}
3360 @cindex COFF symbol type
3361 @cindex symbol type, COFF
3362 @cindex @code{type} directive
3363 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3364 records the integer @var{int} as the type attribute of a symbol table entry.
3367 @samp{.type} is associated only with COFF format output; when
3368 @code{_AS__} is configured for @code{b.out} output, it accepts this
3369 directive but ignores it.
3371 _fi__(_COFF__||_BOUT__)
3373 _if__(_COFF__||_BOUT__)
3374 @node Val, Word, Type, Pseudo Ops
3375 @section @code{.val @var{addr}}
3377 @cindex @code{val} directive
3378 @cindex COFF value attribute
3379 @cindex value attribute, COFF
3380 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3381 records the address @var{addr} as the value attribute of a symbol table
3385 @samp{.val} is used only for COFF output; when @code{_AS__} is
3386 configured for @code{b.out}, it accepts this directive but ignores it.
3388 _fi__(_COFF__||_BOUT__)
3390 _if__(_COFF__||_BOUT__)
3391 @node Word, Deprecated, Val, Pseudo Ops
3392 _fi__(_COFF__||_BOUT__)
3393 _if__(!(_COFF__||_BOUT__))
3394 @node Word, Deprecated, Text, Pseudo Ops
3395 _fi__(!(_COFF__||_BOUT__))
3396 @section @code{.word @var{expressions}}
3398 @cindex @code{word} directive
3399 This directive expects zero or more @var{expressions}, of any section,
3400 separated by commas.
3401 _if__((!_GENERIC__) && _W32__)
3402 For each expression, @code{_AS__} emits a 32-bit number.
3403 _fi__((!_GENERIC__) && _W32__)
3404 _if__((!_GENERIC__) && _W16__)
3405 For each expression, @code{_AS__} emits a 16-bit number.
3406 _fi__((!_GENERIC__) && _W16__)
3409 The size of the number emitted, and its byte order,
3410 depends on what kind of computer will run the program.
3413 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3414 @c happen---32-bit addressability, period; no long/short jumps.
3415 _if__(_GENERIC__ || _DIFFTABKLUG__)
3416 @cindex difference tables altered
3417 @cindex altered difference tables
3419 @emph{Warning: Special Treatment to support Compilers}
3423 Machines with a 32-bit address space, but that do less than 32-bit
3424 addressing, require the following special treatment. If the machine of
3425 interest to you does 32-bit addressing (or doesn't require it;
3426 @pxref{_MACH_DEP__}), you can ignore this issue.
3429 In order to assemble compiler output into something that will work,
3430 @code{_AS__} will occasionlly do strange things to @samp{.word} directives.
3431 Directives of the form @samp{.word sym1-sym2} are often emitted by
3432 compilers as part of jump tables. Therefore, when @code{_AS__} assembles a
3433 directive of the form @samp{.word sym1-sym2}, and the difference between
3434 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will
3435 create a @dfn{secondary jump table}, immediately before the next label.
3436 This secondary jump table will be preceded by a short-jump to the
3437 first byte after the secondary table. This short-jump prevents the flow
3438 of control from accidentally falling into the new table. Inside the
3439 table will be a long-jump to @code{sym2}. The original @samp{.word}
3440 will contain @code{sym1} minus the address of the long-jump to
3443 If there were several occurrences of @samp{.word sym1-sym2} before the
3444 secondary jump table, all of them will be adjusted. If there was a
3445 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3446 long-jump to @code{sym4} will be included in the secondary jump table,
3447 and the @code{.word} directives will be adjusted to contain @code{sym3}
3448 minus the address of the long-jump to @code{sym4}; and so on, for as many
3449 entries in the original jump table as necessary.
3452 @emph{This feature may be disabled by compiling @code{_AS__} with the
3453 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3454 assembly language programmers.
3456 _fi__(_GENERIC__ || _DIFFTABKLUG__)
3458 @node Deprecated, , Word, Pseudo Ops
3459 @section Deprecated Directives
3461 @cindex deprecated directives
3462 @cindex obsolescent directives
3463 One day these directives won't work.
3464 They are included for compatibility with older assemblers.
3471 @node _MACH_DEP__, Copying, Pseudo Ops, Top
3473 @chapter Machine Dependent Features
3475 @cindex machine dependencies
3476 The machine instruction sets are (almost by definition) different on
3477 each machine where @code{_AS__} runs. Floating point representations
3478 vary as well, and @code{_AS__} often supports a few additional
3479 directives or command-line options for compatibility with other
3480 assemblers on a particular platform. Finally, some versions of
3481 @code{_AS__} support special pseudo-instructions for branch
3484 This chapter discusses most of these differences, though it does not
3485 include details on any machine's instruction set. For details on that
3486 subject, see the hardware manufacturer's manual.
3490 * Vax-Dependent:: VAX Dependent Features
3493 * AMD29K-Dependent:: AMD 29K Dependent Features
3496 * H8/300-Dependent:: AMD 29K Dependent Features
3499 * i960-Dependent:: Intel 80960 Dependent Features
3502 * M68K-Dependent:: M680x0 Dependent Features
3505 * Sparc-Dependent:: SPARC Dependent Features
3508 * i386-Dependent:: 80386 Dependent Features
3515 @node Vax-Dependent, AMD29K-Dependent, Machine Dependent, Machine Dependent
3517 _CHAPSEC__(0+_GENERIC__) VAX Dependent Features
3521 * Vax-Opts:: VAX Command-Line Options
3522 * VAX-float:: VAX Floating Point
3523 * VAX-directives:: Vax Machine Directives
3524 * VAX-opcodes:: VAX Opcodes
3525 * VAX-branch:: VAX Branch Improvement
3526 * VAX-operands:: VAX Operands
3527 * VAX-no:: Not Supported on VAX
3530 @node Vax-Opts, VAX-float, Vax-Dependent, Vax-Dependent
3531 _CHAPSEC__(1+_GENERIC__) VAX Command-Line Options
3533 @cindex command-line options ignored, VAX
3534 @cindex VAX command-line options ignored
3535 The Vax version of @code{_AS__} accepts any of the following options,
3536 gives a warning message that the option was ignored and proceeds.
3537 These options are for compatibility with scripts designed for other
3538 people's assemblers.
3541 @item @kbd{-D} (Debug)
3542 @itemx @kbd{-S} (Symbol Table)
3543 @itemx @kbd{-T} (Token Trace)
3544 @cindex @code{-D}, ignored on VAX
3545 @cindex @code{-S}, ignored on VAX
3546 @cindex @code{-T}, ignored on VAX
3547 These are obsolete options used to debug old assemblers.
3549 @item @kbd{-d} (Displacement size for JUMPs)
3550 @cindex @code{-d}, VAX option
3551 This option expects a number following the @kbd{-d}. Like options
3552 that expect filenames, the number may immediately follow the
3553 @kbd{-d} (old standard) or constitute the whole of the command line
3554 argument that follows @kbd{-d} (GNU standard).
3556 @item @kbd{-V} (Virtualize Interpass Temporary File)
3557 @cindex @code{-V}, redundant on VAX
3558 Some other assemblers use a temporary file. This option
3559 commanded them to keep the information in active memory rather
3560 than in a disk file. @code{_AS__} always does this, so this
3561 option is redundant.
3563 @item @kbd{-J} (JUMPify Longer Branches)
3564 @cindex @code{-J}, ignored on VAX
3565 Many 32-bit computers permit a variety of branch instructions
3566 to do the same job. Some of these instructions are short (and
3567 fast) but have a limited range; others are long (and slow) but
3568 can branch anywhere in virtual memory. Often there are 3
3569 flavors of branch: short, medium and long. Some other
3570 assemblers would emit short and medium branches, unless told by
3571 this option to emit short and long branches.
3573 @item @kbd{-t} (Temporary File Directory)
3574 @cindex @code{-t}, ignored on VAX
3575 Some other assemblers may use a temporary file, and this option
3576 takes a filename being the directory to site the temporary
3577 file. @code{_AS__} does not use a temporary disk file, so this
3578 option makes no difference. @kbd{-t} needs exactly one
3582 @cindex VMS (VAX) options
3583 @cindex options for VAX/VMS
3584 @cindex VAX/VMS options
3585 @cindex @code{-h} option, VAX/VMS
3586 @cindex @code{-+} option, VAX/VMS
3587 @cindex Vax-11 C compatibility
3588 @cindex symbols with lowercase, VAX/VMS
3589 @c FIXME! look into "I think" below, correct if needed, delete.
3590 The Vax version of the assembler accepts two options when
3591 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
3592 @kbd{-h} option prevents @code{_AS__} from modifying the
3593 symbol-table entries for symbols that contain lowercase
3594 characters (I think). The @kbd{-+} option causes @code{_AS__} to
3595 print warning messages if the FILENAME part of the object file,
3596 or any symbol name is larger than 31 characters. The @kbd{-+}
3597 option also insertes some code following the @samp{_main}
3598 symbol so that the object file will be compatible with Vax-11
3601 @node VAX-float, VAX-directives, Vax-Opts, Vax-Dependent
3602 _CHAPSEC__(1+_GENERIC__) VAX Floating Point
3604 @cindex VAX floating point
3605 @cindex floating point, VAX
3606 Conversion of flonums to floating point is correct, and
3607 compatible with previous assemblers. Rounding is
3608 towards zero if the remainder is exactly half the least significant bit.
3610 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3613 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3614 are rendered correctly. Again, rounding is towards zero in the
3617 @cindex @code{float} directive, VAX
3618 @cindex @code{double} directive, VAX
3619 The @code{.float} directive produces @code{f} format numbers.
3620 The @code{.double} directive produces @code{d} format numbers.
3622 @node VAX-directives, VAX-opcodes, VAX-float, Vax-Dependent
3623 _CHAPSEC__(1+_GENERIC__) Vax Machine Directives
3625 @cindex machine directives, VAX
3626 @cindex VAX machine directives
3627 The Vax version of the assembler supports four directives for
3628 generating Vax floating point constants. They are described in the
3631 @cindex wide floating point directives, VAX
3634 @cindex @code{dfloat} directive, VAX
3635 This expects zero or more flonums, separated by commas, and
3636 assembles Vax @code{d} format 64-bit floating point constants.
3639 @cindex @code{ffloat} directive, VAX
3640 This expects zero or more flonums, separated by commas, and
3641 assembles Vax @code{f} format 32-bit floating point constants.
3644 @cindex @code{gfloat} directive, VAX
3645 This expects zero or more flonums, separated by commas, and
3646 assembles Vax @code{g} format 64-bit floating point constants.
3649 @cindex @code{hfloat} directive, VAX
3650 This expects zero or more flonums, separated by commas, and
3651 assembles Vax @code{h} format 128-bit floating point constants.
3655 @node VAX-opcodes, VAX-branch, VAX-directives, Vax-Dependent
3656 _CHAPSEC__(1+_GENERIC__) VAX Opcodes
3658 @cindex VAX opcode mnemonics
3659 @cindex opcode mnemonics, VAX
3660 @cindex mnemonics for opcodes, VAX
3661 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3662 instructions have exactly 3 operands. The dispatch table that
3663 follows the @code{case@dots{}} instruction should be made with
3664 @code{.word} statements. This is compatible with all unix
3665 assemblers we know of.
3667 @node VAX-branch, VAX-operands, VAX-opcodes, Vax-Dependent
3668 _CHAPSEC__(1+_GENERIC__) VAX Branch Improvement
3670 @cindex VAX branch improvement
3671 @cindex branch improvement, VAX
3672 @cindex pseudo-ops for branch, VAX
3673 Certain pseudo opcodes are permitted. They are for branch
3674 instructions. They expand to the shortest branch instruction that
3675 will reach the target. Generally these mnemonics are made by
3676 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3677 This feature is included both for compatibility and to help
3678 compilers. If you don't need this feature, don't use these
3679 opcodes. Here are the mnemonics, and the code they can expand into.
3683 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3685 @item (byte displacement)
3687 @item (word displacement)
3689 @item (long displacement)
3694 Unconditional branch.
3696 @item (byte displacement)
3698 @item (word displacement)
3700 @item (long displacement)
3704 @var{COND} may be any one of the conditional branches
3705 @code{neq nequ eql eqlu gtr geq lss gtru lequ vc vs gequ cc lssu cs}.
3706 @var{COND} may also be one of the bit tests
3707 @code{bs bc bss bcs bsc bcc bssi bcci lbs lbc}.
3708 @var{NOTCOND} is the opposite condition to @var{COND}.
3710 @item (byte displacement)
3711 @kbd{b@var{COND} @dots{}}
3712 @item (word displacement)
3713 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
3714 @item (long displacement)
3715 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
3718 @var{X} may be one of @code{b d f g h l w}.
3720 @item (word displacement)
3721 @kbd{@var{OPCODE} @dots{}}
3722 @item (long displacement)
3724 @var{OPCODE} @dots{}, foo ;
3731 @var{YYY} may be one of @code{lss leq}.
3733 @var{ZZZ} may be one of @code{geq gtr}.
3735 @item (byte displacement)
3736 @kbd{@var{OPCODE} @dots{}}
3737 @item (word displacement)
3739 @var{OPCODE} @dots{}, foo ;
3741 foo: brw @var{destination} ;
3744 @item (long displacement)
3746 @var{OPCODE} @dots{}, foo ;
3748 foo: jmp @var{destination} ;
3757 @item (byte displacement)
3758 @kbd{@var{OPCODE} @dots{}}
3759 @item (word displacement)
3761 @var{OPCODE} @dots{}, foo ;
3763 foo: brw @var{destination} ;
3766 @item (long displacement)
3768 @var{OPCODE} @dots{}, foo ;
3770 foo: jmp @var{destination} ;
3776 @node VAX-operands, VAX-no, VAX-branch, Vax-Dependent
3777 _CHAPSEC__(1+_GENERIC__) VAX Operands
3779 @cindex VAX operand notation
3780 @cindex operand notation, VAX
3781 @cindex immediate character, VAX
3782 @cindex VAX immediate character
3783 The immediate character is @samp{$} for Unix compatibility, not
3784 @samp{#} as DEC writes it.
3786 @cindex indirect character, VAX
3787 @cindex VAX indirect character
3788 The indirect character is @samp{*} for Unix compatibility, not
3789 @samp{@@} as DEC writes it.
3791 @cindex displacement sizing character, VAX
3792 @cindex VAX displacement sizing character
3793 The displacement sizing character is @samp{`} (an accent grave) for
3794 Unix compatibility, not @samp{^} as DEC writes it. The letter
3795 preceding @samp{`} may have either case. @samp{G} is not
3796 understood, but all other letters (@code{b i l s w}) are understood.
3798 @cindex register names, VAX
3799 @cindex VAX register names
3800 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
3801 pc}. Any case of letters will do.
3808 Any expression is permitted in an operand. Operands are comma
3811 @c There is some bug to do with recognizing expressions
3812 @c in operands, but I forget what it is. It is
3813 @c a syntax clash because () is used as an address mode
3814 @c and to encapsulate sub-expressions.
3816 @node VAX-no, , VAX-operands, Vax-Dependent
3817 _CHAPSEC__(1+_GENERIC__) Not Supported on VAX
3819 @cindex VAX bitfields not supported
3820 @cindex bitfields, not supported on VAX
3821 Vax bit fields can not be assembled with @code{_AS__}. Someone
3822 can add the required code if they really need it.
3827 @node AMD29K-Dependent, H8/300-Dependent, Vax-Dependent, Machine Dependent
3829 _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features
3831 @cindex AMD 29K support
3834 * AMD29K Options:: Options
3835 * AMD29K Syntax:: Syntax
3836 * AMD29K Floating Point:: Floating Point
3837 * AMD29K Directives:: AMD 29K Machine Directives
3838 * AMD29K Opcodes:: Opcodes
3841 @node AMD29K Options, AMD29K Syntax, AMD29K-Dependent, AMD29K-Dependent
3842 _CHAPSEC__(1+_GENERIC__) Options
3843 @cindex AMD 29K options (none)
3844 @cindex options for AMD29K (none)
3845 @code{_AS__} has no additional command-line options for the AMD
3848 @node AMD29K Syntax, AMD29K Floating Point, AMD29K Options, AMD29K-Dependent
3849 _CHAPSEC__(1+_GENERIC__) Syntax
3851 * AMD29K-Chars:: Special Characters
3852 * AMD29K-Regs:: Register Names
3855 @node AMD29K-Chars, AMD29K-Regs, AMD29K Syntax, AMD29K Syntax
3856 _CHAPSEC__(2+_GENERIC__) Special Characters
3858 @cindex line comment character, AMD 29K
3859 @cindex AMD 29K line comment character
3860 @samp{;} is the line comment character.
3862 @cindex line separator, AMD 29K
3863 @cindex AMD 29K line separator
3864 @cindex statement separator, AMD 29K
3865 @cindex AMD 29K statement separator
3866 @samp{@@} can be used instead of a newline to separate statements.
3868 @cindex identifiers, AMD 29K
3869 @cindex AMD 29K identifiers
3870 The character @samp{?} is permitted in identifiers (but may not begin
3873 @node AMD29K-Regs, , AMD29K-Chars, AMD29K Syntax
3874 _CHAPSEC__(2+_GENERIC__) Register Names
3876 @cindex AMD 29K register names
3877 @cindex register names, AMD 29K
3878 General-purpose registers are represented by predefined symbols of the
3879 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
3880 (for local registers), where @var{nnn} represents a number between
3881 @code{0} and @code{127}, written with no leading zeros. The leading
3882 letters may be in either upper or lower case; for example, @samp{gr13}
3883 and @samp{LR7} are both valid register names.
3885 You may also refer to general-purpose registers by specifying the
3886 register number as the result of an expression (prefixed with @samp{%%}
3887 to flag the expression as a register number):
3892 ---where @var{expression} must be an absolute expression evaluating to a
3893 number between @code{0} and @code{255}. The range [0, 127] refers to
3894 global registers, and the range [128, 255] to local registers.
3896 @cindex special purpose registers, AMD 29K
3897 @cindex AMD 29K special purpose registers
3898 @cindex protected registers, AMD 29K
3899 @cindex AMD 29K protected registers
3900 In addition, @code{_AS__} understands the following protected
3901 special-purpose register names for the AMD 29K family:
3911 These unprotected special-purpose register names are also recognized:
3919 @node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, AMD29K-Dependent
3920 _CHAPSEC__(1+_GENERIC__) Floating Point
3922 @cindex floating point, AMD 29K (@sc{ieee})
3923 @cindex AMD 29K floating point (@sc{ieee})
3924 The AMD 29K family uses @sc{ieee} floating-point numbers.
3926 @node AMD29K Directives, AMD29K Opcodes, AMD29K Floating Point, AMD29K-Dependent
3927 _CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives
3929 @cindex machine directives, AMD 29K
3930 @cindex AMD 29K machine directives
3932 @item .block @var{size} , @var{fill}
3933 @cindex @code{block} directive, AMD 29K
3934 This directive emits @var{size} bytes, each of value @var{fill}. Both
3935 @var{size} and @var{fill} are absolute expressions. If the comma
3936 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3938 In other versions of the GNU assembler, this directive is called
3944 @cindex @code{cputype} directive, AMD 29K
3945 This directive is ignored; it is accepted for compatibility with other
3949 @cindex @code{file} directive, AMD 29K
3950 This directive is ignored; it is accepted for compatibility with other
3954 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
3955 used for the directive called @code{.app-file} in the AMD 29K support.
3959 @cindex @code{line} directive, AMD 29K
3960 This directive is ignored; it is accepted for compatibility with other
3963 @item .reg @var{symbol}, @var{expression}
3964 @cindex @code{reg} directive, AMD 29K
3965 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
3968 @cindex @code{sect} directive, AMD 29K
3969 This directive is ignored; it is accepted for compatibility with other
3972 @item .use @var{section name}
3973 @cindex @code{use} directive, AMD 29K
3974 Establishes the section and subsection for the following code;
3975 @var{section name} may be one of @code{.text}, @code{.data},
3976 @code{.data1}, or @code{.lit}. With one of the first three @var{section
3977 name} options, @samp{.use} is equivalent to the machine directive
3978 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
3982 @node AMD29K Opcodes, , AMD29K Directives, AMD29K-Dependent
3983 _CHAPSEC__(1+_GENERIC__) Opcodes
3985 @cindex AMD 29K opcodes
3986 @cindex opcodes for AMD 29K
3987 @code{_AS__} implements all the standard AMD 29K opcodes. No
3988 additional pseudo-instructions are needed on this family.
3990 For information on the 29K machine instruction set, see @cite{Am29000
3991 User's Manual}, Advanced Micro Devices, Inc.
3996 @node H8/300-Dependent, i960-Dependent, AMD29K-Dependent, Machine Dependent
3998 _CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features
4000 @cindex H8/300 support
4002 * H8/300 Options:: Options
4003 * H8/300 Syntax:: Syntax
4004 * H8/300 Floating Point:: Floating Point
4005 * H8/300 Directives:: H8/300 Machine Directives
4006 * H8/300 Opcodes:: Opcodes
4009 @node H8/300 Options, H8/300 Syntax, H8/300-Dependent, H8/300-Dependent
4010 _CHAPSEC__(1+_GENERIC__) Options
4012 @cindex H8/300 options (none)
4013 @cindex options, H8/300 (none)
4014 @code{_AS__} has no additional command-line options for the Hitachi
4017 @node H8/300 Syntax, H8/300 Floating Point, H8/300 Options, H8/300-Dependent
4018 _CHAPSEC__(1+_GENERIC__) Syntax
4020 * H8/300-Chars:: Special Characters
4021 * H8/300-Regs:: Register Names
4022 * H8/300-Addressing:: Addressing Modes
4025 @node H8/300-Chars, H8/300-Regs, H8/300 Syntax, H8/300 Syntax
4026 _CHAPSEC__(2+_GENERIC__) Special Characters
4028 @cindex line comment character, H8/300
4029 @cindex H8/300 line comment character
4030 @samp{;} is the line comment character.
4032 @cindex line separator, H8/300
4033 @cindex statement separator, H8/300
4034 @cindex H8/300 line separator
4035 @samp{$} can be used instead of a newline to separate statements.
4036 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
4038 @node H8/300-Regs, H8/300-Addressing, H8/300-Chars, H8/300 Syntax
4039 _CHAPSEC__(2+_GENERIC__) Register Names
4041 @cindex H8/300 registers
4042 @cindex registers, H8/300
4043 You can use predefined symbols of the form @samp{r@var{n}h} and
4044 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
4045 general-purpose registers. @var{n} is a digit from @samp{0} to
4046 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
4049 You can also use the eight predefined symbols @samp{r@var{n}} to refer
4050 to the H8/300 registers as 16-bit registers (you must use this form for
4053 The two control registers are called @code{pc} (program counter; a
4054 16-bit register) and @code{ccr} (condition code register; an 8-bit
4055 register). @code{r7} is used as the stack pointer, and can also be
4058 @node H8/300-Addressing, , H8/300-Regs, H8/300 Syntax
4059 _CHAPSEC__(2+_GENERIC__) Addressing Modes
4061 @cindex addressing modes, H8/300
4062 @cindex H8/300 addressing modes
4063 _AS__ understands the following addressing modes for the H8/300:
4071 @item @@(@var{d}, r@var{n})
4072 @itemx @@(@var{d}:16, r@var{n})
4073 Register indirect: 16-bit displacement @var{d} from register @var{n}.
4074 (You may specify the @samp{:16} for clarity if you wish, but it is not
4075 required and has no effect.)
4078 Register indirect with post-increment
4081 Register indirect with pre-decrement
4083 @item @code{@@}@var{aa}
4084 @itemx @code{@@}@var{aa}:8
4085 @itemx @code{@@}@var{aa}:16
4086 Absolute address @code{aa}. You may specify the @samp{:8} or @samp{:16}
4087 for clarity, if you wish; but @code{_AS__} neither requires this nor
4088 uses it---the address size required is taken from context.
4093 Immediate data @var{xx}. You may specify the @samp{:8} or @samp{:16}
4094 for clarity, if you wish; but @code{_AS__} neither requires this nor
4095 uses it---the data size required is taken from context.
4097 @item @code{@@}@code{@@}@var{aa}
4098 @itemx @code{@@}@code{@@}@var{aa}:8
4099 Memory indirect. You may specify the @samp{:8} for clarity, if you
4100 wish; but @code{_AS__} neither requires this nor uses it.
4103 @node H8/300 Floating Point, H8/300 Directives, H8/300 Syntax, H8/300-Dependent
4104 _CHAPSEC__(1+_GENERIC__) Floating Point
4106 @cindex floating point, H8/300 (@sc{ieee})
4107 @cindex H8/300 floating point (@sc{ieee})
4108 The H8/300 family uses @sc{ieee} floating-point numbers.
4110 @node H8/300 Directives, H8/300 Opcodes, H8/300 Floating Point, H8/300-Dependent
4111 _CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives
4113 @cindex H8/300 machine directives (none)
4114 @cindex machine directives, H8/300 (none)
4115 @cindex @code{word} directive, H8/300
4116 @cindex @code{int} directive, H8/300
4117 @code{_AS__} has no machine-dependent directives for the H8/300.
4118 However, on this platform the @samp{.int} and @samp{.word} directives
4119 generate 16-bit numbers.
4121 @node H8/300 Opcodes, , H8/300 Directives, H8/300-Dependent
4122 _CHAPSEC__(1+_GENERIC__) Opcodes
4124 @cindex H8/300 opcode summary
4125 @cindex opcode summary, H8/300
4126 @cindex mnemonics, H8/300
4127 @cindex instruction summary, H8/300
4128 For detailed information on the H8/300 machine instruction set, see
4129 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025).
4131 @code{_AS__} implements all the standard H8/300 opcodes. No additional
4132 pseudo-instructions are needed on this family.
4134 The following table summarizes the opcodes and their arguments:
4135 @c kluge due to lack of group outside example
4139 Rs @r{source register}
4140 Rd @r{destination register}
4141 imm @r{immediate data}
4142 x:3 @r{a bit (as a number between 0 and 7)}
4143 d:8 @r{eight bit displacement from @code{pc}}
4144 d:16 @r{sixteen bit displacement from @code{Rs}}
4146 add.b Rs,Rd biand #x:3,Rd
4147 add.b #imm:8,Rd biand #x:3,@@Rd
4148 add.w Rs,Rd biand #x:3,@@aa:8
4149 adds #1,Rd bild #x:3,Rd
4150 adds #2,Rd bild #x:3,@@Rd
4151 addx #imm:8,Rd bild #x:3,@@aa:8
4152 addx Rs,Rd bior #x:3,Rd
4153 and #imm:8,Rd bior #x:3,@@Rd
4154 and Rs,Rd bior #x:3,@@aa:8
4155 andc #imm:8,ccr bist #x:3,Rd
4156 band #x:3,Rd bist #x:3,@@Rd
4157 band #x:3,@@Rd bist #x:3,@@aa:8
4158 bra d:8 bixor #x:3,Rd
4159 bt d:8 bixor #x:3,@@Rd
4160 brn d:8 bixor #x:3,@@aa:8
4162 bhi d:8 bld #x:3,@@Rd
4163 bls d:8 bld #x:3,@@aa:8
4164 bcc d:8 bnot #x:3,Rd
4165 bhs d:8 bnot #x:3,@@Rd
4166 bcs d:8 bnot #x:3,@@aa:8
4168 bne d:8 bnot Rs,@@Rd
4169 beq d:8 bnot Rs,@@aa:8
4171 bvs d:8 bor #x:3,@@Rd
4172 bpl d:8 bor #x:3,@@aa:8
4173 bmi d:8 bset #x:3,@@Rd
4174 bge d:8 bset #x:3,@@aa:8
4176 bgt d:8 bset Rs,@@Rd
4177 ble d:8 bset Rs,@@aa:8
4178 bclr #x:3,Rd bsr d:8
4179 bclr #x:3,@@Rd bst #x:3,Rd
4180 bclr #x:3,@@aa:8 bst #x:3,@@Rd
4181 bclr Rs,Rd bst #x:3,@@aa:8
4182 bclr Rs,@@Rd btst #x:3,Rd
4185 btst #x:3,@@Rd mov.w @@(d:16, Rs),Rd
4186 btst #x:3,@@aa:8 mov.w @@Rs+,Rd
4187 btst Rs,Rd mov.w @@aa:16,Rd
4188 btst Rs,@@Rd mov.w Rs,@@Rd
4189 btst Rs,@@aa:8 mov.w Rs,@@(d:16, Rd)
4190 bxor #x:3,Rd mov.w Rs,@@-Rd
4191 bxor #x:3,@@Rd mov.w Rs,@@aa:16
4192 bxor #x:3,@@aa:8 movfpe @@aa:16,Rd
4193 cmp.b #imm:8,Rd movtpe Rs,@@aa:16
4194 cmp.b Rs,Rd mulxu Rs,Rd
4199 divxu Rs,Rd or Rs,Rd
4200 eepmov orc #imm:8,ccr
4206 jsr @@aa:16 rotxr Rs
4211 mov.b #imm:8,Rd shll Rs
4212 mov.b @@Rs,Rd shlr Rs
4213 mov.b @@(d:16, Rs),Rd sleep
4214 mov.b @@Rs+,Rd stc ccr,Rd
4215 mov.b @@aa:16,Rd sub.b Rs,Rd
4216 mov.b @@aa:8,Rd sub.w Rs,Rd
4217 mov.b Rs,@@Rd subs #1,Rd
4218 mov.b Rs,@@(d:16, Rd) subs #2,Rd
4219 mov.b Rs,@@-Rd subx #imm:8,Rd
4220 mov.b Rs,@@aa:16 subx Rs,Rd
4221 mov.b Rs,@@aa:8 xor #imm:8,Rd
4222 mov.w Rs,Rd xor Rs,Rd
4223 mov.w #imm:16,Rd xorc #imm:8,ccr
4228 @cindex size suffixes, H8/300
4229 @cindex H8/300 size suffixes
4230 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4231 @code{sub}) are defined with variants using the suffixes @samp{.b} and
4232 @samp{.w} to specify the size of a memory operand. @code{_AS__}
4233 supports these suffixes, but does not require them; since one of the
4234 operands is always a register, @code{_AS__} can deduce the correct size.
4236 For example, since @code{r0} refers to a 16-bit register,
4239 @exdent is equivalent to
4243 If you use the size suffixes, @code{_AS__} will issue a warning if
4244 there's a mismatch between the suffix and the register size.
4249 @node i960-Dependent, M68K-Dependent, H8/300-Dependent, Machine Dependent
4251 _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features
4253 @cindex i960 support
4255 * Options-i960:: i960 Command-line Options
4256 * Floating Point-i960:: Floating Point
4257 * Directives-i960:: i960 Machine Directives
4258 * Opcodes for i960:: i960 Opcodes
4261 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
4262 @c long as they're not turned on for other machines than 960.
4263 @node Options-i960, Floating Point-i960, i960-Dependent, i960-Dependent
4265 _CHAPSEC__(1+_GENERIC__) i960 Command-line Options
4267 @cindex i960 options
4268 @cindex options, i960
4271 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
4272 @cindex i960 architecture options
4273 @cindex architecture options, i960
4274 @cindex @code{-A} options, i960
4275 Select the 80960 architecture. Instructions or features not supported
4276 by the selected architecture cause fatal errors.
4278 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
4279 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
4281 If none of these options is specified, @code{_AS__} will generate code for any
4282 instruction or feature that is supported by @emph{some} version of the
4283 960 (even if this means mixing architectures!). In principle,
4284 @code{_AS__} will attempt to deduce the minimal sufficient processor
4285 type if none is specified; depending on the object code format, the
4286 processor type may be recorded in the object file. If it is critical
4287 that the @code{_AS__} output match a specific architecture, specify that
4288 architecture explicitly.
4291 @cindex @code{-b} option, i960
4292 @cindex branch recording, i960
4293 @cindex i960 branch recording
4294 Add code to collect information about conditional branches taken, for
4295 later optimization using branch prediction bits. (The conditional branch
4296 instructions have branch prediction bits in the CA, CB, and CC
4297 architectures.) If @var{BR} represents a conditional branch instruction,
4298 the following represents the code generated by the assembler when
4299 @samp{-b} is specified:
4302 call @var{increment routine}
4303 .word 0 # pre-counter
4305 call @var{increment routine}
4306 .word 0 # post-counter
4309 The counter following a branch records the number of times that branch
4310 was @emph{not} taken; the differenc between the two counters is the
4311 number of times the branch @emph{was} taken.
4313 @cindex @code{gbr960}, i960 postprocessor
4314 @cindex branch statistics table, i960
4315 A table of every such @code{Label} is also generated, so that the
4316 external postprocessor @code{gbr960} (supplied by Intel) can locate all
4317 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
4318 this is a local symbol to permit collecting statistics for many separate
4319 object files. The table is word aligned, and begins with a two-word
4320 header. The first word, initialized to 0, is used in maintaining linked
4321 lists of branch tables. The second word is a count of the number of
4322 entries in the table, which follow immediately: each is a word, pointing
4323 to one of the labels illustrated above.
4327 @c END TEXI2ROFF-KILL
4329 +------------+------------+------------+ ... +------------+
4331 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
4333 +------------+------------+------------+ ... +------------+
4335 __BRANCH_TABLE__ layout
4341 \line{\leftskip=0pt\hskip\tableindent
4342 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
4343 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
4344 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
4346 @c END TEXI2ROFF-KILL
4348 The first word of the header is used to locate multiple branch tables,
4349 since each object file may contain one. Normally the links are
4350 maintained with a call to an initialization routine, placed at the
4351 beginning of each function in the file. The GNU C compiler will
4352 generate these calls automatically when you give it a @samp{-b} option.
4353 For further details, see the documentation of @samp{gbr960}.
4356 @cindex @code{-norelax} option, i960
4357 Normally, Compare-and-Branch instructions with targets that require
4358 displacements greater than 13 bits (or that have external targets) are
4359 replaced with the corresponding compare (or @samp{chkbit}) and branch
4360 instructions. You can use the @samp{-norelax} option to specify that
4361 @code{_AS__} should generate errors instead, if the target displacement
4362 is larger than 13 bits.
4364 This option does not affect the Compare-and-Jump instructions; the code
4365 emitted for them is @emph{always} adjusted when necessary (depending on
4366 displacement size), regardless of whether you use @samp{-norelax}.
4369 @node Floating Point-i960, Directives-i960, Options-i960, i960-Dependent
4370 _CHAPSEC__(1+_GENERIC__) Floating Point
4372 @cindex floating point, i960 (@sc{ieee})
4373 @cindex i960 floating point (@sc{ieee})
4374 @code{_AS__} generates @sc{ieee} floating-point numbers for the directives
4375 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
4377 @node Directives-i960, Opcodes for i960, Floating Point-i960, i960-Dependent
4378 _CHAPSEC__(1+_GENERIC__) i960 Machine Directives
4380 @cindex machine directives, i960
4381 @cindex i960 machine directives
4384 @cindex @code{bss} directive, i960
4385 @item .bss @var{symbol}, @var{length}, @var{align}
4386 Reserve @var{length} bytes in the bss section for a local @var{symbol},
4387 aligned to the power of two specified by @var{align}. @var{length} and
4388 @var{align} must be positive absolute expressions. This directive
4389 differs from @samp{.lcomm} only in that it permits you to specify
4390 an alignment. @xref{Lcomm,,@code{.lcomm}}.
4394 @item .extended @var{flonums}
4395 @cindex @code{extended} directive, i960
4396 @code{.extended} expects zero or more flonums, separated by commas; for
4397 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
4398 floating-point number.
4400 @item .leafproc @var{call-lab}, @var{bal-lab}
4401 @cindex @code{leafproc} directive, i960
4402 You can use the @samp{.leafproc} directive in conjunction with the
4403 optimized @code{callj} instruction to enable faster calls of leaf
4404 procedures. If a procedure is known to call no other procedures, you
4405 may define an entry point that skips procedure prolog code (and that does
4406 not depend on system-supplied saved context), and declare it as the
4407 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
4408 entry point that goes through the normal prolog, you can specify that
4409 entry point as @var{call-lab}.
4411 A @samp{.leafproc} declaration is meant for use in conjunction with the
4412 optimized call instruction @samp{callj}; the directive records the data
4413 needed later to choose between converting the @samp{callj} into a
4414 @code{bal} or a @code{call}.
4416 @var{call-lab} is optional; if only one argument is present, or if the
4417 two arguments are identical, the single argument is assumed to be the
4418 @code{bal} entry point.
4420 @item .sysproc @var{name}, @var{index}
4421 @cindex @code{sysproc} directive, i960
4422 The @samp{.sysproc} directive defines a name for a system procedure.
4423 After you define it using @samp{.sysproc}, you can use @var{name} to
4424 refer to the system procedure identified by @var{index} when calling
4425 procedures with the optimized call instruction @samp{callj}.
4427 Both arguments are required; @var{index} must be between 0 and 31
4431 @node Opcodes for i960, , Directives-i960, i960-Dependent
4432 _CHAPSEC__(1+_GENERIC__) i960 Opcodes
4434 @cindex opcodes, i960
4435 @cindex i960 opcodes
4436 All Intel 960 machine instructions are supported;
4437 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
4438 selecting the instruction subset for a particular 960
4439 architecture.@refill
4441 Some opcodes are processed beyond simply emitting a single corresponding
4442 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
4443 instructions with target displacements larger than 13 bits.
4446 * callj-i960:: @code{callj}
4447 * Compare-and-branch-i960:: Compare-and-Branch
4450 @node callj-i960, Compare-and-branch-i960, Opcodes for i960, Opcodes for i960
4451 _CHAPSEC__(2+_GENERIC__) @code{callj}
4453 @cindex @code{callj}, i960 pseudo-opcode
4454 @cindex i960 @code{callj} pseudo-opcode
4455 You can write @code{callj} to have the assembler or the linker determine
4456 the most appropriate form of subroutine call: @samp{call},
4457 @samp{bal}, or @samp{calls}. If the assembly source contains
4458 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
4459 defining the operand---then @code{_AS__} will translate the
4460 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
4461 for the linker to resolve.
4463 @node Compare-and-branch-i960, , callj-i960, Opcodes for i960
4464 _CHAPSEC__(2+_GENERIC__) Compare-and-Branch
4466 @cindex i960 compare and branch instructions
4467 @cindex compare and branch instructions, i960
4468 The 960 architectures provide combined Compare-and-Branch instructions
4469 that permit you to store the branch target in the lower 13 bits of the
4470 instruction word itself. However, if you specify a branch target far
4471 enough away that its address won't fit in 13 bits, the assembler can
4472 either issue an error, or convert your Compare-and-Branch instruction
4473 into separate instructions to do the compare and the branch.
4475 @cindex compare and jump expansions, i960
4476 @cindex i960 compare and jump expansions
4477 Whether @code{_AS__} gives an error or expands the instruction depends
4478 on two choices you can make: whether you use the @samp{-norelax} option,
4479 and whether you use a ``Compare and Branch'' instruction or a ``Compare
4480 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
4481 expanded if necessary; the ``Branch'' instructions are expanded when
4482 necessary @emph{unless} you specify @code{-norelax}---in which case
4483 @code{_AS__} gives an error instead.
4485 These are the Compare-and-Branch instructions, their ``Jump'' variants,
4486 and the instruction pairs they may expand into:
4490 @c END TEXI2ROFF-KILL
4493 Branch Jump Expanded to
4494 ------ ------ ------------
4497 cmpibe cmpije cmpi; be
4498 cmpibg cmpijg cmpi; bg
4499 cmpibge cmpijge cmpi; bge
4500 cmpibl cmpijl cmpi; bl
4501 cmpible cmpijle cmpi; ble
4502 cmpibno cmpijno cmpi; bno
4503 cmpibne cmpijne cmpi; bne
4504 cmpibo cmpijo cmpi; bo
4505 cmpobe cmpoje cmpo; be
4506 cmpobg cmpojg cmpo; bg
4507 cmpobge cmpojge cmpo; bge
4508 cmpobl cmpojl cmpo; bl
4509 cmpoble cmpojle cmpo; ble
4510 cmpobne cmpojne cmpo; bne
4516 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
4517 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
4518 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
4519 bbc& & chkbit; bno\cr
4520 bbs& & chkbit; bo\cr
4521 cmpibe& cmpije& cmpi; be\cr
4522 cmpibg& cmpijg& cmpi; bg\cr
4523 cmpibge& cmpijge& cmpi; bge\cr
4524 cmpibl& cmpijl& cmpi; bl\cr
4525 cmpible& cmpijle& cmpi; ble\cr
4526 cmpibno& cmpijno& cmpi; bno\cr
4527 cmpibne& cmpijne& cmpi; bne\cr
4528 cmpibo& cmpijo& cmpi; bo\cr
4529 cmpobe& cmpoje& cmpo; be\cr
4530 cmpobg& cmpojg& cmpo; bg\cr
4531 cmpobge& cmpojge& cmpo; bge\cr
4532 cmpobl& cmpojl& cmpo; bl\cr
4533 cmpoble& cmpojle& cmpo; ble\cr
4534 cmpobne& cmpojne& cmpo; bne\cr}
4536 @c END TEXI2ROFF-KILL
4541 @c FIXME! node conds are only sufficient for m68k alone, all, and vintage
4543 @node M68K-Dependent, Sparc-Dependent, i960-Dependent, Machine Dependent
4546 @node M68K-Dependent, Sparc-Dependent, Machine Dependent, Machine Dependent
4549 _CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features
4551 @cindex M680x0 support
4553 * M68K-Opts:: M680x0 Options
4554 * M68K-Syntax:: Syntax
4555 * M68K-Float:: Floating Point
4556 * M68K-Directives:: 680x0 Machine Directives
4557 * M68K-opcodes:: Opcodes
4560 @node M68K-Opts, M68K-Syntax, M68K-Dependent, M68K-Dependent
4561 _CHAPSEC__(1+_GENERIC__) M680x0 Options
4563 @cindex options, M680x0
4564 @cindex M680x0 options
4565 The Motorola 680x0 version of @code{_AS__} has two machine dependent options.
4566 One shortens undefined references from 32 to 16 bits, while the
4567 other is used to tell @code{_AS__} what kind of machine it is
4570 @cindex @code{-l} option, M680x0
4571 You can use the @kbd{-l} option to shorten the size of references to
4572 undefined symbols. If the @kbd{-l} option is not given, references to
4573 undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__}
4574 cannot know where these symbols will end up, @code{_AS__} can only allocate
4575 space for the linker to fill in later. Since @code{_AS__} doesn't know how
4576 far away these symbols will be, it allocates as much space as it can.)
4577 If this option is given, the references will only be one word wide (16
4578 bits). This may be useful if you want the object file to be as small as
4579 possible, and you know that the relevant symbols will be less than 17
4582 @cindex @code{-m68000} and related options, M680x0
4583 @cindex architecture options, M680x0
4584 @cindex M680x0 architecture options
4585 The 680x0 version of @code{_AS__} is most frequently used to assemble
4586 programs for the Motorola MC68020 microprocessor. Occasionally it is
4587 used to assemble programs for the mostly similar, but slightly different
4588 MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options
4589 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
4590 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
4593 @node M68K-Syntax, M68K-Float, M68K-Opts, M68K-Dependent
4594 _CHAPSEC__(1+_GENERIC__) Syntax
4596 @cindex M680x0 syntax
4597 @cindex syntax, M680x0
4598 @cindex M680x0 size modifiers
4599 @cindex size modifiers, M680x0
4600 The 680x0 version of @code{_AS__} uses syntax similar to the Sun assembler.
4601 Size modifiers are appended directly to the end of the opcode without an
4602 intervening period. For example, write @samp{movl} rather than
4606 If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow
4607 Sun-style local labels of the form @samp{1$} through @samp{$9}.
4610 In the following table @dfn{apc} stands for any of the address
4611 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
4612 Program Counter (@samp{pc}), or the zero-address relative to the
4613 program counter (@samp{zpc}).
4615 @cindex M680x0 addressing modes
4616 @cindex addressing modes, M680x0
4617 The following addressing modes are understood:
4620 @samp{#@var{digits}}
4623 @samp{d0} through @samp{d7}
4625 @item Address Register
4626 @samp{a0} through @samp{a7}
4628 @item Address Register Indirect
4629 @samp{a0@@} through @samp{a7@@}
4631 @item Address Register Postincrement
4632 @samp{a0@@+} through @samp{a7@@+}
4634 @item Address Register Predecrement
4635 @samp{a0@@-} through @samp{a7@@-}
4637 @item Indirect Plus Offset
4638 @samp{@var{apc}@@(@var{digits})}
4641 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4643 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
4646 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4648 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
4651 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4653 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4655 @item Memory Indirect
4656 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
4659 @samp{@var{symbol}}, or @samp{@var{digits}}
4661 @c pesch@cygnus.com: gnu, rich concur the following needs careful
4662 @c research before documenting.
4663 , or either of the above followed
4664 by @samp{:b}, @samp{:w}, or @samp{:l}.
4668 @node M68K-Float, M68K-Directives, M68K-Syntax, M68K-Dependent
4669 _CHAPSEC__(1+_GENERIC__) Floating Point
4671 @cindex floating point, M680x0
4672 @cindex M680x0 floating point
4673 @c FIXME is this "not too well tested" crud STILL true?
4674 The floating point code is not too well tested, and may have
4677 Packed decimal (P) format floating literals are not supported.
4678 Feel free to add the code!
4680 The floating point formats generated by directives are these.
4684 @cindex @code{float} directive, M680x0
4685 @code{Single} precision floating point constants.
4688 @cindex @code{double} directive, M680x0
4689 @code{Double} precision floating point constants.
4692 There is no directive to produce regions of memory holding
4693 extended precision numbers, however they can be used as
4694 immediate operands to floating-point instructions. Adding a
4695 directive to create extended precision numbers would not be
4696 hard, but it has not yet seemed necessary.
4698 @node M68K-Directives, M68K-opcodes, M68K-Float, M68K-Dependent
4699 _CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives
4701 @cindex M680x0 directives
4702 @cindex directives, M680x0
4703 In order to be compatible with the Sun assembler the 680x0 assembler
4704 understands the following directives.
4708 @cindex @code{data1} directive, M680x0
4709 This directive is identical to a @code{.data 1} directive.
4712 @cindex @code{data2} directive, M680x0
4713 This directive is identical to a @code{.data 2} directive.
4716 @cindex @code{even} directive, M680x0
4717 This directive is identical to a @code{.align 1} directive.
4718 @c Is this true? does it work???
4721 @cindex @code{skip} directive, M680x0
4722 This directive is identical to a @code{.space} directive.
4725 @node M68K-opcodes, , M68K-Directives, M68K-Dependent
4726 _CHAPSEC__(1+_GENERIC__) Opcodes
4728 @cindex M680x0 opcodes
4729 @cindex opcodes, M680x0
4730 @cindex instruction set, M680x0
4731 @c pesch@cygnus.com: I don't see any point in the following
4732 @c paragraph. Bugs are bugs; how does saying this
4735 Danger: Several bugs have been found in the opcode table (and
4736 fixed). More bugs may exist. Be careful when using obscure
4741 * M68K-Branch:: Branch Improvement
4742 * M68K-Chars:: Special Characters
4745 @node M68K-Branch, M68K-Chars, M68K-opcodes, M68K-opcodes
4746 _CHAPSEC__(2+_GENERIC__) Branch Improvement
4748 @cindex pseudo-opcodes, M680x0
4749 @cindex M680x0 pseudo-opcodes
4750 @cindex branch improvement, M680x0
4751 @cindex M680x0 branch improvement
4752 Certain pseudo opcodes are permitted for branch instructions.
4753 They expand to the shortest branch instruction that will reach the
4754 target. Generally these mnemonics are made by substituting @samp{j} for
4755 @samp{b} at the start of a Motorola mnemonic.
4757 The following table summarizes the pseudo-operations. A @code{*} flags
4758 cases that are more fully described after the table:
4762 +---------------------------------------------------------
4764 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
4765 +---------------------------------------------------------
4766 jbsr |bsrs bsr bsrl jsr jsr
4767 jra |bras bra bral jmp jmp
4768 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
4769 * dbXX |dbXX dbXX dbXX; bra; jmpl
4770 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
4773 NX: negative of condition XX
4776 @center @code{*}---see full description below
4781 These are the simplest jump pseudo-operations; they always map to one
4782 particular machine instruction, depending on the displacement to the
4786 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
4787 where @var{XX} is a conditional branch or condition-code test. The full
4788 list of pseudo-ops in this family is:
4790 jhi jls jcc jcs jne jeq jvc
4791 jvs jpl jmi jge jlt jgt jle
4794 For the cases of non-PC relative displacements and long displacements on
4795 the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of
4796 @var{NX}, the opposite condition to @var{XX}:
4808 The full family of pseudo-operations covered here is
4810 dbhi dbls dbcc dbcs dbne dbeq dbvc
4811 dbvs dbpl dbmi dbge dblt dbgt dble
4815 Other than for word and byte displacements, when the source reads
4816 @samp{db@var{XX} foo}, @code{_AS__} will emit
4825 This family includes
4827 fjne fjeq fjge fjlt fjgt fjle fjf
4828 fjt fjgl fjgle fjnge fjngl fjngle fjngt
4829 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
4830 fjor fjseq fjsf fjsne fjst fjueq fjuge
4831 fjugt fjule fjult fjun
4834 For branch targets that are not PC relative, @code{_AS__} emits
4840 when it encounters @samp{fj@var{XX} foo}.
4844 @node M68K-Chars, , M68K-Branch, M68K-opcodes
4845 _CHAPSEC__(2+_GENERIC__) Special Characters
4847 @cindex special characters, M680x0
4848 @cindex M680x0 immediate character
4849 @cindex immediate character, M680x0
4850 @cindex M680x0 line comment character
4851 @cindex line comment character, M680x0
4852 @cindex comments, M680x0
4853 The immediate character is @samp{#} for Sun compatibility. The
4854 line-comment character is @samp{|}. If a @samp{#} appears at the
4855 beginning of a line, it is treated as a comment unless it looks like
4856 @samp{# line file}, in which case it is treated normally.
4860 @c pesch@cygnus.com: conditionalize on something other than 0 when filled in.
4863 The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to
4864 specify thiat it is compiling for a 32032 processor, or a
4865 @kbd{-m32532} to specify that it is compiling for a 32532 option.
4866 The default (if neither is specified) is chosen when the assembler
4870 I don't know anything about the 32x32 syntax assembled by
4871 @code{_AS__}. Someone who undersands the processor (I've never seen
4872 one) and the possible syntaxes should write this section.
4874 @subsection Floating Point
4875 The 32x32 uses @sc{ieee} floating point numbers, but @code{_AS__} will only
4876 create single or double precision values. I don't know if the 32x32
4877 understands extended precision numbers.
4879 @subsection 32x32 Machine Directives
4880 The 32x32 has no machine dependent directives.
4885 _if__(_I80386__&&_M680X0__)
4886 @node Sparc-Dependent, i386-Dependent, M68K-Dependent, Machine Dependent
4887 _fi__(_I80386__&&_M680X0__)
4888 _if__(_I80386__&&_I960__&&!_M680X0__)
4889 @node Sparc-Dependent, i386-Dependent, i960-Dependent, Machine Dependent
4890 _fi__(_I80386__&&_I960__&&!_M680X0__)
4891 _if__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
4892 @node Sparc-Dependent, i386-Dependent, AMD29K-Dependent, Machine Dependent
4893 _fi__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
4894 _if__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4895 @node Sparc-Dependent, i386-Dependent, Vax-Dependent, Machine Dependent
4896 _fi__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4897 _if__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4898 @node Sparc-Dependent, i386-Dependent, Machine Dependent, Machine Dependent
4899 _fi__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4900 _if__((!_I80386__)&&_M680X0__)
4901 @node Sparc-Dependent, , M68K-Dependent, Machine Dependent
4902 _fi__((!_I80386__)&&_M680X0__)
4903 _if__((!_I80386__)&&_I960__&&!_M680X0__)
4904 @node Sparc-Dependent, , i960-Dependent, Machine Dependent
4905 _fi__((!_I80386__)&&_I960__&&!_M680X0__)
4906 _if__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
4907 @node Sparc-Dependent, , AMD29K-Dependent, Machine Dependent
4908 _fi__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
4909 _if__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4910 @node Sparc-Dependent, , Vax-Dependent, Machine Dependent
4911 _fi__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4912 _if__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4913 @node Sparc-Dependent, , Machine Dependent, Machine Dependent
4914 _fi__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
4916 _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features
4918 @cindex SPARC support
4920 * Sparc-Opts:: Options
4921 * Sparc-Float:: Floating Point
4922 * Sparc-Directives:: Sparc Machine Directives
4925 @node Sparc-Opts, Sparc-Float, Sparc-Dependent, Sparc-Dependent
4926 _CHAPSEC__(1+_GENERIC__) Options
4928 @cindex options for SPARC (none)
4929 @cindex SPARC options (none)
4930 The Sparc has no machine dependent options.
4933 @c FIXME: (sparc) Fill in "syntax" section!
4934 @c subsection syntax
4935 I don't know anything about Sparc syntax. Someone who does
4936 will have to write this section.
4939 @node Sparc-Float, Sparc-Directives, Sparc-Opts, Sparc-Dependent
4940 _CHAPSEC__(1+_GENERIC__) Floating Point
4942 @cindex floating point, SPARC (@sc{ieee})
4943 @cindex SPARC floating point (@sc{ieee})
4944 The Sparc uses @sc{ieee} floating-point numbers.
4946 @node Sparc-Directives, , Sparc-Float, Sparc-Dependent
4947 _CHAPSEC__(1+_GENERIC__) Sparc Machine Directives
4949 @cindex SPARC machine directives
4950 @cindex machine directives, SPARC
4951 The Sparc version of @code{_AS__} supports the following additional
4956 @cindex @code{common} directive, SPARC
4957 This must be followed by a symbol name, a positive number, and
4958 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
4959 syntax is different.
4962 @cindex @code{half} directive, SPARC
4963 This is functionally identical to @code{.short}.
4966 @cindex @code{proc} directive, SPARC
4967 This directive is ignored. Any text following it on the same
4968 line is also ignored.
4971 @cindex @code{reserve} directive, SPARC
4972 This must be followed by a symbol name, a positive number, and
4973 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
4974 syntax is different.
4977 @cindex @code{seg} directive, SPARC
4978 This must be followed by @code{"text"}, @code{"data"}, or
4979 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
4983 @cindex @code{skip} directive, SPARC
4984 This is functionally identical to the @code{.space} directive.
4987 @cindex @code{word} directive, SPARC
4988 On the Sparc, the .word directive produces 32 bit values,
4989 instead of the 16 bit values it produces on many other machines.
4995 @c FIXME! Conditionalize for all combinations in this section
4996 @node i386-Dependent, , Sparc-Dependent, Machine Dependent
4998 _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features
5000 @cindex i386 support
5001 @cindex i80306 support
5003 * i386-Options:: Options
5004 * i386-Syntax:: AT&T Syntax versus Intel Syntax
5005 * i386-Opcodes:: Opcode Naming
5006 * i386-Regs:: Register Naming
5007 * i386-prefixes:: Opcode Prefixes
5008 * i386-Memory:: Memory References
5009 * i386-jumps:: Handling of Jump Instructions
5010 * i386-Float:: Floating Point
5011 * i386-Notes:: Notes
5014 @node i386-Options, i386-Syntax, i386-Dependent, i386-Dependent
5015 _CHAPSEC__(1+_GENERIC__) Options
5017 @cindex options for i386 (none)
5018 @cindex i386 options (none)
5019 The 80386 has no machine dependent options.
5021 @node i386-Syntax, i386-Opcodes, i386-Options, i386-Dependent
5022 _CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax
5024 @cindex i386 syntax compatibility
5025 @cindex syntax compatibility, i386
5026 In order to maintain compatibility with the output of @code{_GCC__},
5027 @code{_AS__} supports AT&T System V/386 assembler syntax. This is quite
5028 different from Intel syntax. We mention these differences because
5029 almost all 80386 documents used only Intel syntax. Notable differences
5030 between the two syntaxes are:
5034 @cindex immediate operands, i386
5035 @cindex i386 immediate operands
5036 @cindex register operands, i386
5037 @cindex i386 register operands
5038 @cindex jump/call operands, i386
5039 @cindex i386 jump/call operands
5040 @cindex operand delimiters, i386
5041 AT&T immediate operands are preceded by @samp{$}; Intel immediate
5042 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
5043 AT&T register operands are preceded by @samp{%}; Intel register operands
5044 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
5045 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
5048 @cindex i386 source, destination operands
5049 @cindex source, destination operands; i386
5050 AT&T and Intel syntax use the opposite order for source and destination
5051 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
5052 @samp{source, dest} convention is maintained for compatibility with
5053 previous Unix assemblers.
5056 @cindex opcode suffixes, i386
5057 @cindex sizes operands, i386
5058 @cindex i386 size suffixes
5059 In AT&T syntax the size of memory operands is determined from the last
5060 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
5061 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
5062 memory references. Intel syntax accomplishes this by prefixes memory
5063 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
5064 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
5065 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
5068 @cindex return instructions, i386
5069 @cindex i386 jump, call, return
5070 Immediate form long jumps and calls are
5071 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
5073 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
5075 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
5076 @samp{ret far @var{stack-adjust}}.
5079 @cindex sections, i386
5080 @cindex i386 sections
5081 The AT&T assembler does not provide support for multiple section
5082 programs. Unix style systems expect all programs to be single sections.
5085 @node i386-Opcodes, i386-Regs, i386-Syntax, i386-Dependent
5086 _CHAPSEC__(1+_GENERIC__) Opcode Naming
5088 @cindex i386 opcode naming
5089 @cindex opcode naming, i386
5090 Opcode names are suffixed with one character modifiers which specify the
5091 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
5092 byte, word, and long operands. If no suffix is specified by an
5093 instruction and it contains no memory operands then @code{_AS__} tries to
5094 fill in the missing suffix based on the destination register operand
5095 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
5096 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
5097 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
5098 assembler which assumes that a missing opcode suffix implies long
5099 operand size. (This incompatibility does not affect compiler output
5100 since compilers always explicitly specify the opcode suffix.)
5102 Almost all opcodes have the same names in AT&T and Intel format. There
5103 are a few exceptions. The sign extend and zero extend instructions need
5104 two sizes to specify them. They need a size to sign/zero extend
5105 @emph{from} and a size to zero extend @emph{to}. This is accomplished
5106 by using two opcode suffixes in AT&T syntax. Base names for sign extend
5107 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
5108 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
5109 suffixes are tacked on to this base name, the @emph{from} suffix before
5110 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
5111 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
5112 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
5113 and @samp{wl} (from word to long).
5115 @cindex conversion instructions, i386
5116 @cindex i386 conversion instructions
5117 The Intel-syntax conversion instructions
5121 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
5124 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
5127 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
5130 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
5134 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
5135 AT&T naming. @code{_AS__} accepts either naming for these instructions.
5137 @cindex jump instructions, i386
5138 @cindex call instructions, i386
5139 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
5140 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
5143 @node i386-Regs, i386-prefixes, i386-Opcodes, i386-Dependent
5144 _CHAPSEC__(1+_GENERIC__) Register Naming
5146 @cindex i386 registers
5147 @cindex registers, i386
5148 Register operands are always prefixes with @samp{%}. The 80386 registers
5153 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
5154 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
5155 frame pointer), and @samp{%esp} (the stack pointer).
5158 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
5159 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
5162 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
5163 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
5164 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
5165 @samp{%cx}, and @samp{%dx})
5168 the 6 section registers @samp{%cs} (code section), @samp{%ds}
5169 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
5173 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
5177 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
5178 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
5181 the 2 test registers @samp{%tr6} and @samp{%tr7}.
5184 the 8 floating point register stack @samp{%st} or equivalently
5185 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
5186 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
5189 @node i386-prefixes, i386-Memory, i386-Regs, i386-Dependent
5190 _CHAPSEC__(1+_GENERIC__) Opcode Prefixes
5192 @cindex i386 opcode prefixes
5193 @cindex opcode prefixes, i386
5194 @cindex prefixes, i386
5195 Opcode prefixes are used to modify the following opcode. They are used
5196 to repeat string instructions, to provide section overrides, to perform
5197 bus lock operations, and to give operand and address size (16-bit
5198 operands are specified in an instruction by prefixing what would
5199 normally be 32-bit operands with a ``operand size'' opcode prefix).
5200 Opcode prefixes are usually given as single-line instructions with no
5201 operands, and must directly precede the instruction they act upon. For
5202 example, the @samp{scas} (scan string) instruction is repeated with:
5208 Here is a list of opcode prefixes:
5212 @cindex section override prefixes, i386
5213 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
5214 @samp{fs}, @samp{gs}. These are automatically added by specifying
5215 using the @var{section}:@var{memory-operand} form for memory references.
5218 @cindex size prefixes, i386
5219 Operand/Address size prefixes @samp{data16} and @samp{addr16}
5220 change 32-bit operands/addresses into 16-bit operands/addresses. Note
5221 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
5222 are not supported (yet).
5225 @cindex bus lock prefixes, i386
5226 @cindex inhibiting interrupts, i386
5227 The bus lock prefix @samp{lock} inhibits interrupts during
5228 execution of the instruction it precedes. (This is only valid with
5229 certain instructions; see a 80386 manual for details).
5232 @cindex coprocessor wait, i386
5233 The wait for coprocessor prefix @samp{wait} waits for the
5234 coprocessor to complete the current instruction. This should never be
5235 needed for the 80386/80387 combination.
5238 @cindex repeat prefixes, i386
5239 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
5240 to string instructions to make them repeat @samp{%ecx} times.
5243 @node i386-Memory, i386-jumps, i386-prefixes, i386-Dependent
5244 _CHAPSEC__(1+_GENERIC__) Memory References
5246 @cindex i386 memory references
5247 @cindex memory references, i386
5248 An Intel syntax indirect memory reference of the form
5251 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
5255 is translated into the AT&T syntax
5258 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
5262 where @var{base} and @var{index} are the optional 32-bit base and
5263 index registers, @var{disp} is the optional displacement, and
5264 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
5265 to calculate the address of the operand. If no @var{scale} is
5266 specified, @var{scale} is taken to be 1. @var{section} specifies the
5267 optional section register for the memory operand, and may override the
5268 default section register (see a 80386 manual for section register
5269 defaults). Note that section overrides in AT&T syntax @emph{must} have
5270 be preceded by a @samp{%}. If you specify a section override which
5271 coincides with the default section register, @code{_AS__} will @emph{not}
5272 output any section register override prefixes to assemble the given
5273 instruction. Thus, section overrides can be specified to emphasize which
5274 section register is used for a given memory operand.
5276 Here are some examples of Intel and AT&T style memory references:
5279 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
5280 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
5281 missing, and the default section is used (@samp{%ss} for addressing with
5282 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
5284 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
5285 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
5286 @samp{foo}. All other fields are missing. The section register here
5287 defaults to @samp{%ds}.
5289 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
5290 This uses the value pointed to by @samp{foo} as a memory operand.
5291 Note that @var{base} and @var{index} are both missing, but there is only
5292 @emph{one} @samp{,}. This is a syntactic exception.
5294 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
5295 This selects the contents of the variable @samp{foo} with section
5296 register @var{section} being @samp{%gs}.
5299 Absolute (as opposed to PC relative) call and jump operands must be
5300 prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will
5301 always choose PC relative addressing for jump/call labels.
5303 Any instruction that has a memory operand @emph{must} specify its size (byte,
5304 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
5307 @node i386-jumps, i386-Float, i386-Memory, i386-Dependent
5308 _CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions
5310 @cindex jump optimization, i386
5311 @cindex i386 jump optimization
5312 Jump instructions are always optimized to use the smallest possible
5313 displacements. This is accomplished by using byte (8-bit) displacement
5314 jumps whenever the target is sufficiently close. If a byte displacement
5315 is insufficient a long (32-bit) displacement is used. We do not support
5316 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
5317 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
5318 @samp{%eip} to 16 bits after the word displacement is added.
5320 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
5321 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
5322 byte displacements, so that it is possible that use of these
5323 instructions (@code{_GCC__} does not use them) will cause the assembler to
5324 print an error message (and generate incorrect code). The AT&T 80386
5325 assembler tries to get around this problem by expanding @samp{jcxz foo} to
5333 @node i386-Float, i386-Notes, i386-jumps, i386-Dependent
5334 _CHAPSEC__(1+_GENERIC__) Floating Point
5336 @cindex i386 floating point
5337 @cindex floating point, i386
5338 All 80387 floating point types except packed BCD are supported.
5339 (BCD support may be added without much difficulty). These data
5340 types are 16-, 32-, and 64- bit integers, and single (32-bit),
5341 double (64-bit), and extended (80-bit) precision floating point.
5342 Each supported type has an opcode suffix and a constructor
5343 associated with it. Opcode suffixes specify operand's data
5344 types. Constructors build these data types into memory.
5348 @cindex @code{float} directive, i386
5349 @cindex @code{single} directive, i386
5350 @cindex @code{double} directive, i386
5351 @cindex @code{tfloat} directive, i386
5352 Floating point constructors are @samp{.float} or @samp{.single},
5353 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
5354 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
5355 @samp{t} stands for temporary real, and that the 80387 only supports
5356 this format via the @samp{fldt} (load temporary real to stack top) and
5357 @samp{fstpt} (store temporary real and pop stack) instructions.
5360 @cindex @code{word} directive, i386
5361 @cindex @code{long} directive, i386
5362 @cindex @code{int} directive, i386
5363 @cindex @code{quad} directive, i386
5364 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
5365 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
5366 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
5367 (quad). As with the temporary real format the 64-bit @samp{q} format is
5368 only present in the @samp{fildq} (load quad integer to stack top) and
5369 @samp{fistpq} (store quad integer and pop stack) instructions.
5372 Register to register operations do not require opcode suffixes,
5373 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
5375 @cindex i386 @code{fwait} instruction
5376 @cindex @code{fwait instruction}, i386
5377 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
5378 instructions are almost never needed (this is not the case for the
5379 80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses
5380 the @samp{fwait} instruction whenever it is implicitly selected by one
5381 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
5382 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
5383 instructions are made equivalent to @samp{f@dots{}} instructions. If
5384 @samp{fwait} is desired it must be explicitly coded.
5386 @node i386-Notes, , i386-Float, i386-Dependent
5387 _CHAPSEC__(1+_GENERIC__) Notes
5389 @cindex i386 @code{mul}, @code{imul} instructions
5390 @cindex @code{mul} instruction, i386
5391 @cindex @code{imul} instruction, i386
5392 There is some trickery concerning the @samp{mul} and @samp{imul}
5393 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
5394 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
5395 for @samp{imul}) can be output only in the one operand form. Thus,
5396 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
5397 the expanding multiply would clobber the @samp{%edx} register, and this
5398 would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the
5399 64-bit product in @samp{%edx:%eax}.
5401 We have added a two operand form of @samp{imul} when the first operand
5402 is an immediate mode expression and the second operand is a register.
5403 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
5404 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
5409 @c pesch@cygnus.com: we ignore the following chapters, since internals are
5410 @c changing rapidly. These may need to be moved to another
5411 @c book anyhow, if we adopt the model of user/modifier
5413 @node Maintenance, Retargeting, _MACH_DEP__, Top
5414 @chapter Maintaining the Assembler
5415 [[this chapter is still being built]]
5418 We had these goals, in descending priority:
5421 For every program composed by a compiler, @code{_AS__} should emit
5422 ``correct'' code. This leaves some latitude in choosing addressing
5423 modes, order of @code{relocation_info} structures in the object
5426 @item Speed, for usual case.
5427 By far the most common use of @code{_AS__} will be assembling compiler
5430 @item Upward compatibility for existing assembler code.
5431 Well @dots{} we don't support Vax bit fields but everything else
5432 seems to be upward compatible.
5435 The code should be maintainable with few surprises. (JF: ha!)
5439 We assumed that disk I/O was slow and expensive while memory was
5440 fast and access to memory was cheap. We expect the in-memory data
5441 structures to be less than 10 times the size of the emitted object
5442 file. (Contrast this with the C compiler where in-memory structures
5443 might be 100 times object file size!)
5447 Try to read the source file from disk only one time. For other
5448 reasons, we keep large chunks of the source file in memory during
5449 assembly so this is not a problem. Also the assembly algorithm
5450 should only scan the source text once if the compiler composed the
5451 text according to a few simple rules.
5453 Emit the object code bytes only once. Don't store values and then
5456 Build the object file in memory and do direct writes to disk of
5460 RMS suggested a one-pass algorithm which seems to work well. By not
5461 parsing text during a second pass considerable time is saved on
5462 large programs (@emph{e.g.} the sort of C program @code{yacc} would
5465 It happened that the data structures needed to emit relocation
5466 information to the object file were neatly subsumed into the data
5467 structures that do backpatching of addresses after pass 1.
5469 Many of the functions began life as re-usable modules, loosely
5470 connected. RMS changed this to gain speed. For example, input
5471 parsing routines which used to work on pre-sanitized strings now
5472 must parse raw data. Hence they have to import knowledge of the
5473 assemblers' comment conventions @emph{etc}.
5475 @section Deprecated Feature(?)s
5476 We have stopped supporting some features:
5479 @code{.org} statements must have @b{defined} expressions.
5481 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
5484 It might be a good idea to not support these features in a future release:
5487 @kbd{#} should begin a comment, even in column 1.
5489 Why support the logical line & file concept any more?
5491 Subsections are a good candidate for flushing.
5492 Depends on which compilers need them I guess.
5495 @section Bugs, Ideas, Further Work
5496 Clearly the major improvement is DON'T USE A TEXT-READING
5497 ASSEMBLER for the back end of a compiler. It is much faster to
5498 interpret binary gobbledygook from a compiler's tables than to
5499 ask the compiler to write out human-readable code just so the
5500 assembler can parse it back to binary.
5502 Assuming you use @code{_AS__} for human written programs: here are
5506 Document (here) @code{APP}.
5508 Take advantage of knowing no spaces except after opcode
5509 to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces:
5510 only keep space/tabs at begin of line or between 2
5513 Put pointers in this documentation to @file{a.out} documentation.
5515 Split the assembler into parts so it can gobble direct binary
5516 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
5517 just so @code{_AS__} can parse it back to binary.
5519 Rewrite hash functions: I want a more modular, faster library.
5521 Clean up LOTS of code.
5523 Include all the non-@file{.c} files in the maintenance chapter.
5527 Implement flonum short literals.
5529 Change all talk of expression operands to expression quantities,
5530 or perhaps to expression arguments.
5534 Whenever a @code{.text} or @code{.data} statement is seen, we close
5535 of the current frag with an imaginary @code{.fill 0}. This is
5536 because we only have one obstack for frags, and we can't grow new
5537 frags for a new subsection, then go back to the old subsection and
5538 append bytes to the old frag. All this nonsense goes away if we
5539 give each subsection its own obstack. It makes code simpler in
5540 about 10 places, but nobody has bothered to do it because C compiler
5541 output rarely changes subsections (compared to ending frags with
5542 relaxable addresses, which is common).
5546 @c The following files in the @file{_AS__} directory
5547 @c are symbolic links to other files, of
5548 @c the same name, in a different directory.
5551 @c @file{atof_generic.c}
5553 @c @file{atof_vax.c}
5555 @c @file{flonum_const.c}
5557 @c @file{flonum_copy.c}
5559 @c @file{flonum_get.c}
5561 @c @file{flonum_multip.c}
5563 @c @file{flonum_normal.c}
5565 @c @file{flonum_print.c}
5568 Here is a list of the source files in the @file{_AS__} directory.
5572 This contains the pre-processing phase, which deletes comments,
5573 handles whitespace, etc. This was recently re-written, since app
5574 used to be a separate program, but RMS wanted it to be inline.
5577 This is a subroutine to append a string to another string returning a
5578 pointer just after the last @code{char} appended. (JF: All these
5579 little routines should probably all be put in one file.)
5582 Here you will find the main program of the assembler @code{_AS__}.
5585 This is a branch office of @file{read.c}. This understands
5586 expressions, arguments. Inside @code{_AS__}, arguments are called
5587 (expression) @emph{operands}. This is confusing, because we also talk
5588 (elsewhere) about instruction @emph{operands}. Also, expression
5589 operands are called @emph{quantities} explicitly to avoid confusion
5590 with instruction operands. What a mess.
5593 This implements the @b{frag} concept. Without frags, finding the
5594 right size for branch instructions would be a lot harder.
5597 This contains the symbol table, opcode table @emph{etc.} hashing
5601 This is a table of values of digits, for use in atoi() type
5602 functions. Could probably be flushed by using calls to strtol(), or
5606 This contains Operating system dependent source file reading
5607 routines. Since error messages often say where we are in reading
5608 the source file, they live here too. Since @code{_AS__} is intended to
5609 run under GNU and Unix only, this might be worth flushing. Anyway,
5610 almost all C compilers support stdio.
5613 This deals with calling the pre-processor (if needed) and feeding the
5614 chunks back to the rest of the assembler the right way.
5617 This contains operating system independent parts of fatal and
5618 warning message reporting. See @file{append.c} above.
5621 This contains operating system dependent functions that write an
5622 object file for @code{_AS__}. See @file{input-file.c} above.
5625 This implements all the directives of @code{_AS__}. This also deals
5626 with passing input lines to the machine dependent part of the
5630 This is a C library function that isn't in most C libraries yet.
5631 See @file{append.c} above.
5634 This implements subsections.
5637 This implements symbols.
5640 This contains the code to perform relaxation, and to write out
5641 the object file. It is mostly operating system independent, but
5642 different OSes have different object file formats in any case.
5645 This implements @code{malloc()} or bust. See @file{append.c} above.
5648 This implements @code{realloc()} or bust. See @file{append.c} above.
5650 @item atof-generic.c
5651 The following files were taken from a machine-independent subroutine
5652 library for manipulating floating point numbers and very large
5655 @file{atof-generic.c} turns a string into a flonum internal format
5656 floating-point number.
5658 @item flonum-const.c
5659 This contains some potentially useful floating point numbers in
5663 This copies a flonum.
5665 @item flonum-multip.c
5666 This multiplies two flonums together.
5669 This copies a bignum.
5673 Here is a table of all the machine-specific files (this includes
5674 both source and header files). Typically, there is a
5675 @var{machine}.c file, a @var{machine}-opcode.h file, and an
5676 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
5677 be identical to the one used by GDB (which uses it for disassembly.)
5682 This contains code to turn a flonum into a ieee literal constant.
5683 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}.
5686 This is the opcode-table for the i386 version of the assembler.
5689 This contains all the code for the i386 version of the assembler.
5692 This defines constants and macros used by the i386 version of the assembler.
5695 generic 68020 header file. To be linked to m68k.h on a
5696 non-sun3, non-hpux system.
5699 68010 header file for Sun2 workstations. Not well tested. To be linked
5700 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
5704 68020 header file for Sun3 workstations. To be linked to m68k.h before
5705 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
5709 68020 header file for a HPUX (system 5?) box. Which box, which
5710 version of HPUX, etc? I don't know.
5713 A hard- or symbolic- link to one of @file{m-generic.h},
5714 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
5715 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
5719 Opcode table for 68020. This is now a link to the opcode table
5720 in the @code{GDB} source directory.
5723 All the mc680x0 code, in one huge, slow-to-compile file.
5726 This contains the code for the ns32032/ns32532 version of the
5729 @item ns32k-opcode.h
5730 This contains the opcode table for the ns32032/ns32532 version
5734 Vax specific file for describing Vax operands and other Vax-ish things.
5740 Vax specific parts of @code{_AS__}. Also includes the former files
5741 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
5744 Turns a flonum into a Vax constant.
5747 This file contains the special code needed to put out a VMS
5748 style object file for the Vax.
5752 Here is a list of the header files in the source directory.
5753 (Warning: This section may not be very accurate. I didn't
5754 write the header files; I just report them.) Also note that I
5755 think many of these header files could be cleaned up or
5761 This describes the structures used to create the binary header data
5762 inside the object file. Perhaps we should use the one in
5763 @file{/usr/include}?
5766 This defines all the globally useful things, and pulls in _0__<stdio.h>_1__
5767 and _0__<assert.h>_1__.
5770 This defines macros useful for dealing with bignums.
5773 Structure and macros for dealing with expression()
5776 This defines the structure for dealing with floating point
5777 numbers. It #includes @file{bignum.h}.
5780 This contains macro for appending a byte to the current frag.
5783 Structures and function definitions for the hashing functions.
5786 Function headers for the input-file.c functions.
5789 structures and function headers for things defined in the
5790 machine dependent part of the assembler.
5793 This is the GNU systemwide include file for manipulating obstacks.
5794 Since nobody is running under real GNU yet, we include this file.
5797 Macros and function headers for reading in source files.
5799 @item struct-symbol.h
5800 Structure definition and macros for dealing with the _AS__
5801 internal form of a symbol.
5804 structure definition for dealing with the numbered subsections
5805 of the text and data sections.
5808 Macros and function headers for dealing with symbols.
5811 Structure for doing section fixups.
5814 @comment ~subsection Test Directory
5815 @comment (Note: The test directory seems to have disappeared somewhere
5816 @comment along the line. If you want it, you'll probably have to find a
5817 @comment REALLY OLD dump tape~dots{})
5819 @comment The ~file{test/} directory is used for regression testing.
5820 @comment After you modify ~@code{_AS__}, you can get a quick go/nogo
5821 @comment confidence test by running the new ~@code{_AS__} over the source
5822 @comment files in this directory. You use a shell script ~file{test/do}.
5824 @comment The tests in this suite are evolving. They are not comprehensive.
5825 @comment They have, however, caught hundreds of bugs early in the debugging
5826 @comment cycle of ~@code{_AS__}. Most test statements in this suite were naturally
5827 @comment selected: they were used to demonstrate actual ~@code{_AS__} bugs rather
5828 @comment than being written ~i{a prioi}.
5830 @comment Another testing suggestion: over 30 bugs have been found simply by
5831 @comment running examples from this manual through ~@code{_AS__}.
5832 @comment Some examples in this manual are selected
5833 @comment to distinguish boundary conditions; they are good for testing ~@code{_AS__}.
5835 @comment ~subsubsection Regression Testing
5836 @comment Each regression test involves assembling a file and comparing the
5837 @comment actual output of ~@code{_AS__} to ``known good'' output files. Both
5838 @comment the object file and the error/warning message file (stderr) are
5839 @comment inspected. Optionally the ~@code{_AS__} exit status may be checked.
5840 @comment Discrepencies are reported. Each discrepency means either that
5841 @comment you broke some part of ~@code{_AS__} or that the ``known good'' files
5842 @comment are now out of date and should be changed to reflect the new
5843 @comment definition of ``good''.
5845 @comment Each regression test lives in its own directory, in a tree
5846 @comment rooted in the directory ~file{test/}. Each such directory
5847 @comment has a name ending in ~file{.ret}, where `ret' stands for
5848 @comment REgression Test. The ~file{.ret} ending allows ~code{find
5849 @comment (1)} to find all regression tests in the tree, without
5850 @comment needing to list them explicitly.
5852 @comment Any ~file{.ret} directory must contain a file called
5853 @comment ~file{input} which is the source file to assemble. During
5854 @comment testing an object file ~file{output} is created, as well as
5855 @comment a file ~file{stdouterr} which contains the output to both
5856 @comment stderr and stderr. If there is a file ~file{output.good} in
5857 @comment the directory, and if ~file{output} contains exactly the
5858 @comment same data as ~file{output.good}, the file ~file{output} is
5859 @comment deleted. Likewise ~file{stdouterr} is removed if it exactly
5860 @comment matches a file ~file{stdouterr.good}. If file
5861 @comment ~file{status.good} is present, containing a decimal number
5862 @comment before a newline, the exit status of ~@code{_AS__} is compared
5863 @comment to this number. If the status numbers are not equal, a file
5864 @comment ~file{status} is written to the directory, containing the
5865 @comment actual status as a decimal number followed by newline.
5867 @comment Should any of the ~file{*.good} files fail to match their corresponding
5868 @comment actual files, this is noted by a 1-line message on the screen during
5869 @comment the regression test, and you can use ~@code{find (1)} to find any
5870 @comment files named ~file{status}, ~file {output} or ~file{stdouterr}.
5872 @node Retargeting, Copying, Maintenance, Top
5873 @chapter Teaching the Assembler about a New Machine
5875 This chapter describes the steps required in order to make the
5876 assembler work with another machine's assembly language. This
5877 chapter is not complete, and only describes the steps in the
5878 broadest terms. You should look at the source for the
5879 currently supported machine in order to discover some of the
5880 details that aren't mentioned here.
5882 You should create a new file called @file{@var{machine}.c}, and
5883 add the appropriate lines to the file @file{Makefile} so that
5884 you can compile your new version of the assembler. This should
5885 be straighforward; simply add lines similar to the ones there
5886 for the four current versions of the assembler.
5888 If you want to be compatible with GDB, (and the current
5889 machine-dependent versions of the assembler), you should create
5890 a file called @file{@var{machine}-opcode.h} which should
5891 contain all the information about the names of the machine
5892 instructions, their opcodes, and what addressing modes they
5893 support. If you do this right, the assembler and GDB can share
5894 this file, and you'll only have to write it once. Note that
5895 while you're writing @code{_AS__}, you may want to use an
5896 independent program (if you have access to one), to make sure
5897 that @code{_AS__} is emitting the correct bytes. Since @code{_AS__}
5898 and @code{GDB} share the opcode table, an incorrect opcode
5899 table entry may make invalid bytes look OK when you disassemble
5900 them with @code{GDB}.
5902 @section Functions You will Have to Write
5904 Your file @file{@var{machine}.c} should contain definitions for
5905 the following functions and variables. It will need to include
5906 some header files in order to use some of the structures
5907 defined in the machine-independent part of the assembler. The
5908 needed header files are mentioned in the descriptions of the
5909 functions that will need them.
5914 This long integer holds the value to place at the beginning of
5915 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
5916 machines that store additional information in the magic-number.
5918 @item char comment_chars[];
5919 This character array holds the values of the characters that
5920 start a comment anywhere in a line. Comments are stripped off
5921 automatically by the machine independent part of the
5922 assembler. Note that the @samp{/*} will always start a
5923 comment, and that only @samp{*/} will end a comment started by
5926 @item char line_comment_chars[];
5927 This character array holds the values of the chars that start a
5928 comment only if they are the first (non-whitespace) character
5929 on a line. If the character @samp{#} does not appear in this
5930 list, you may get unexpected results. (Various
5931 machine-independent parts of the assembler treat the comments
5932 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
5933 that start with @samp{#} are comments.)
5935 @item char EXP_CHARS[];
5936 This character array holds the letters that can separate the
5937 mantissa and the exponent of a floating point number. Typical
5938 values are @samp{e} and @samp{E}.
5940 @item char FLT_CHARS[];
5941 This character array holds the letters that--when they appear
5942 immediately after a leading zero--indicate that a number is a
5943 floating-point number. (Sort of how 0x indicates that a
5944 hexadecimal number follows.)
5946 @item pseudo_typeS md_pseudo_table[];
5947 (@var{pseudo_typeS} is defined in @file{md.h})
5948 This array contains a list of the machine_dependent directives
5949 the assembler must support. It contains the name of each
5950 pseudo op (Without the leading @samp{.}), a pointer to a
5951 function to be called when that directive is encountered, and
5952 an integer argument to be passed to that function.
5954 @item void md_begin(void)
5955 This function is called as part of the assembler's
5956 initialization. It should do any initialization required by
5957 any of your other routines.
5959 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
5960 This routine is called once for each option on the command line
5961 that the machine-independent part of @code{_AS__} does not
5962 understand. This function should return non-zero if the option
5963 pointed to by @var{optionPTR} is a valid option. If it is not
5964 a valid option, this routine should return zero. The variables
5965 @var{argcPTR} and @var{argvPTR} are provided in case the option
5966 requires a filename or something similar as an argument. If
5967 the option is multi-character, @var{optionPTR} should be
5968 advanced past the end of the option, otherwise every letter in
5969 the option will be treated as a separate single-character
5972 @item void md_assemble(char *string)
5973 This routine is called for every machine-dependent
5974 non-directive line in the source file. It does all the real
5975 work involved in reading the opcode, parsing the operands,
5976 etc. @var{string} is a pointer to a null-terminated string,
5977 that comprises the input line, with all excess whitespace and
5980 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
5981 This routine is called to turn a C long int, short int, or char
5982 into the series of bytes that represents that number on the
5983 target machine. @var{outputPTR} points to an array where the
5984 result should be stored; @var{value} is the value to store; and
5985 @var{nbytes} is the number of bytes in 'value' that should be
5988 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
5989 This routine is called to turn a C long int, short int, or char
5990 into the series of bytes that represent an immediate value on
5991 the target machine. It is identical to the function @code{md_number_to_chars},
5992 except on NS32K machines.@refill
5994 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
5995 This routine is called to turn a C long int, short int, or char
5996 into the series of bytes that represent an displacement value on
5997 the target machine. It is identical to the function @code{md_number_to_chars},
5998 except on NS32K machines.@refill
6000 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
6001 This routine is identical to @code{md_number_to_chars},
6002 except on NS32K machines.
6004 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
6005 (@code{struct relocation_info} is defined in @file{a.out.h})
6006 This routine emits the relocation info in @var{ri}
6007 in the appropriate bit-pattern for the target machine.
6008 The result should be stored in the location pointed
6009 to by @var{riPTR}. This routine may be a no-op unless you are
6010 attempting to do cross-assembly.
6012 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
6013 This routine turns a series of digits into the appropriate
6014 internal representation for a floating-point number.
6015 @var{type} is a character from @var{FLT_CHARS[]} that describes
6016 what kind of floating point number is wanted; @var{outputPTR}
6017 is a pointer to an array that the result should be stored in;
6018 and @var{sizePTR} is a pointer to an integer where the size (in
6019 bytes) of the result should be stored. This routine should
6020 return an error message, or an empty string (not (char *)0) for
6023 @item int md_short_jump_size;
6024 This variable holds the (maximum) size in bytes of a short (16
6025 bit or so) jump created by @code{md_create_short_jump()}. This
6026 variable is used as part of the broken-word feature, and isn't
6027 needed if the assembler is compiled with
6028 @samp{-DWORKING_DOT_WORD}.
6030 @item int md_long_jump_size;
6031 This variable holds the (maximum) size in bytes of a long (32
6032 bit or so) jump created by @code{md_create_long_jump()}. This
6033 variable is used as part of the broken-word feature, and isn't
6034 needed if the assembler is compiled with
6035 @samp{-DWORKING_DOT_WORD}.
6037 @item void md_create_short_jump(char *resultPTR,long from_addr,
6038 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6039 This function emits a jump from @var{from_addr} to @var{to_addr} in
6040 the array of bytes pointed to by @var{resultPTR}. If this creates a
6041 type of jump that must be relocated, this function should call
6042 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
6043 emitted by this function may be smaller than @var{md_short_jump_size},
6044 but it must never create a larger one.
6045 (If it creates a smaller jump, the extra bytes of memory will not be
6046 used.) This function is used as part of the broken-word feature,
6047 and isn't needed if the assembler is compiled with
6048 @samp{-DWORKING_DOT_WORD}.@refill
6050 @item void md_create_long_jump(char *ptr,long from_addr,
6051 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6052 This function is similar to the previous function,
6053 @code{md_create_short_jump()}, except that it creates a long
6054 jump instead of a short one. This function is used as part of
6055 the broken-word feature, and isn't needed if the assembler is
6056 compiled with @samp{-DWORKING_DOT_WORD}.
6058 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
6059 This function does the initial setting up for relaxation. This
6060 includes forcing references to still-undefined symbols to the
6061 appropriate addressing modes.
6063 @item relax_typeS md_relax_table[];
6064 (relax_typeS is defined in md.h)
6065 This array describes the various machine dependent states a
6066 frag may be in before relaxation. You will need one group of
6067 entries for each type of addressing mode you intend to relax.
6069 @item void md_convert_frag(fragS *fragPTR)
6070 (@var{fragS} is defined in @file{as.h})
6071 This routine does the required cleanup after relaxation.
6072 Relaxation has changed the type of the frag to a type that can
6073 reach its destination. This function should adjust the opcode
6074 of the frag to use the appropriate addressing mode.
6075 @var{fragPTR} points to the frag to clean up.
6077 @item void md_end(void)
6078 This function is called just before the assembler exits. It
6079 need not free up memory unless the operating system doesn't do
6080 it automatically on exit. (In which case you'll also have to
6081 track down all the other places where the assembler allocates
6082 space but never frees it.)
6086 @section External Variables You will Need to Use
6088 You will need to refer to or change the following external variables
6089 from within the machine-dependent part of the assembler.
6092 @item extern char flagseen[];
6093 This array holds non-zero values in locations corresponding to
6094 the options that were on the command line. Thus, if the
6095 assembler was called with @samp{-W}, @var{flagseen['W']} would
6098 @item extern fragS *frag_now;
6099 This pointer points to the current frag--the frag that bytes
6100 are currently being added to. If nothing else, you will need
6101 to pass it as an argument to various machine-independent
6102 functions. It is maintained automatically by the
6103 frag-manipulating functions; you should never have to change it
6106 @item extern LITTLENUM_TYPE generic_bignum[];
6107 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
6108 This is where @dfn{bignums}--numbers larger than 32 bits--are
6109 returned when they are encountered in an expression. You will
6110 need to use this if you need to implement directives (or
6111 anything else) that must deal with these large numbers.
6112 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
6113 @file{as.h}, and have a positive @code{X_add_number}. The
6114 @code{X_add_number} of a @code{bignum} is the number of
6115 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
6118 @item extern FLONUM_TYPE generic_floating_point_number;
6119 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
6120 The is where @dfn{flonums}--floating-point numbers within
6121 expressions--are returned. @code{Flonums} are of @code{segT}
6122 @code{SEG_BIG}, and have a negative @code{X_add_number}.
6123 @code{Flonums} are returned in a generic format. You will have
6124 to write a routine to turn this generic format into the
6125 appropriate floating-point format for your machine.
6127 @item extern int need_pass_2;
6128 If this variable is non-zero, the assembler has encountered an
6129 expression that cannot be assembled in a single pass. Since
6130 the second pass isn't implemented, this flag means that the
6131 assembler is punting, and is only looking for additional syntax
6132 errors. (Or something like that.)
6134 @item extern segT now_seg;
6135 This variable holds the value of the section the assembler is
6136 currently assembling into.
6140 @section External functions will you need
6142 You will find the following external functions useful (or
6143 indispensable) when you're writing the machine-dependent part
6148 @item char *frag_more(int bytes)
6149 This function allocates @var{bytes} more bytes in the current
6150 frag (or starts a new frag, if it can't expand the current frag
6151 any more.) for you to store some object-file bytes in. It
6152 returns a pointer to the bytes, ready for you to store data in.
6154 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
6155 This function stores a relocation fixup to be acted on later.
6156 @var{frag} points to the frag the relocation belongs in;
6157 @var{where} is the location within the frag where the relocation begins;
6158 @var{size} is the size of the relocation, and is usually 1 (a single byte),
6159 2 (sixteen bits), or 4 (a longword).
6160 The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
6161 at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the
6162 location is subtracted from the result. A relocation entry is also added
6163 to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
6164 @var{offset} may be NULL.@refill
6166 @item char *frag_var(relax_stateT type, int max_chars, int var,
6167 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
6168 This function creates a machine-dependent frag of type @var{type}
6169 (usually @code{rs_machine_dependent}).
6170 @var{max_chars} is the maximum size in bytes that the frag may grow by;
6171 @var{var} is the current size of the variable end of the frag;
6172 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
6173 @var{md_relax_table[]} during @code{relaxation}.
6174 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
6175 @var{opcode} points into a byte whose value may have to be modified if the
6176 addressing mode used by this frag changes. It typically points into the
6177 @var{fr_literal[]} of the previous frag, and is used to point to a location
6178 that @code{md_convert_frag()}, may have to change.@refill
6180 @item void frag_wane(fragS *fragPTR)
6181 This function is useful from within @code{md_convert_frag}. It
6182 changes a frag to type rs_fill, and sets the variable-sized
6183 piece of the frag to zero. The frag will never change in size
6186 @item segT expression(expressionS *retval)
6187 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
6188 This function parses the string pointed to by the external char
6189 pointer @var{input_line_pointer}, and returns the section-type
6190 of the expression. It also stores the results in the
6191 @var{expressionS} pointed to by @var{retval}.
6192 @var{input_line_pointer} is advanced to point past the end of
6193 the expression. (@var{input_line_pointer} is used by other
6194 parts of the assembler. If you modify it, be sure to restore
6195 it to its original value.)
6197 @item as_warn(char *message,@dots{})
6198 If warning messages are disabled, this function does nothing.
6199 Otherwise, it prints out the current file name, and the current
6200 line number, then uses @code{fprintf} to print the
6201 @var{message} and any arguments it was passed.
6203 @item as_bad(char *message,@dots{})
6204 This function should be called when @code{_AS__} encounters
6205 conditions that are bad enough that @code{_AS__} should not
6206 produce an object file, but should continue reading input and
6207 printing warning and bad error messages.
6209 @item as_fatal(char *message,@dots{})
6210 This function prints out the current file name and line number,
6211 prints the word @samp{FATAL:}, then uses @code{fprintf} to
6212 print the @var{message} and any arguments it was passed. Then
6213 the assembler exits. This function should only be used for
6214 serious, unrecoverable errors.
6216 @item void float_const(int float_type)
6217 This function reads floating-point constants from the current
6218 input line, and calls @code{md_atof} to assemble them. It is
6219 useful as the function to call for the directives
6220 @samp{.single}, @samp{.double}, @samp{.float}, etc.
6221 @var{float_type} must be a character from @var{FLT_CHARS}.
6223 @item void demand_empty_rest_of_line(void);
6224 This function can be used by machine-dependent directives to
6225 make sure the rest of the input line is empty. It prints a
6226 warning message if there are additional characters on the line.
6228 @item long int get_absolute_expression(void)
6229 This function can be used by machine-dependent directives to
6230 read an absolute number from the current input line. It
6231 returns the result. If it isn't given an absolute expression,
6232 it prints a warning message and returns zero.
6237 @section The concept of Frags
6239 This assembler works to optimize the size of certain addressing
6240 modes. (e.g. branch instructions) This means the size of many
6241 pieces of object code cannot be determined until after assembly
6242 is finished. (This means that the addresses of symbols cannot be
6243 determined until assembly is finished.) In order to do this,
6244 @code{_AS__} stores the output bytes as @dfn{frags}.
6246 Here is the definition of a frag (from @file{as.h})
6252 relax_stateT fr_type;
6253 relax_substateT fr_substate;
6254 unsigned long fr_address;
6256 struct symbol *fr_symbol;
6258 struct frag *fr_next;
6265 is the size of the fixed-size piece of the frag.
6268 is the maximum (?) size of the variable-sized piece of the frag.
6271 is the type of the frag.
6276 rs_machine_dependent
6279 This stores the type of machine-dependent frag this is. (what
6280 kind of addressing mode is being used, and what size is being
6284 @var{fr_address} is only valid after relaxation is finished.
6285 Before relaxation, the only way to store an address is (pointer
6286 to frag containing the address) plus (offset into the frag).
6289 This contains a number, whose meaning depends on the type of
6291 for machine_dependent frags, this contains the offset from
6292 fr_symbol that the frag wants to go to. Thus, for branch
6293 instructions it is usually zero. (unless the instruction was
6294 @samp{jba foo+12} or something like that.)
6297 for machine_dependent frags, this points to the symbol the frag
6301 This points to the location in the frag (or in a previous frag)
6302 of the opcode for the instruction that caused this to be a frag.
6303 @var{fr_opcode} is needed if the actual opcode must be changed
6304 in order to use a different form of the addressing mode.
6305 (For example, if a conditional branch only comes in size tiny,
6306 a large-size branch could be implemented by reversing the sense
6307 of the test, and turning it into a tiny branch over a large jump.
6308 This would require changing the opcode.)
6310 @var{fr_literal} is a variable-size array that contains the
6311 actual object bytes. A frag consists of a fixed size piece of
6312 object data, (which may be zero bytes long), followed by a
6313 piece of object data whose size may not have been determined
6314 yet. Other information includes the type of the frag (which
6315 controls how it is relaxed),
6318 This is the next frag in the singly-linked list. This is
6319 usually only needed by the machine-independent part of
6325 @node Copying, Index, _MACH_DEP__, Top
6326 @unnumbered GNU GENERAL PUBLIC LICENSE
6330 @cindex copying @code{_AS__}
6331 @center Version 2, June 1991
6334 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
6335 675 Mass Ave, Cambridge, MA 02139, USA
6337 Everyone is permitted to copy and distribute verbatim copies
6338 of this license document, but changing it is not allowed.
6341 @unnumberedsec Preamble
6343 The licenses for most software are designed to take away your
6344 freedom to share and change it. By contrast, the GNU General Public
6345 License is intended to guarantee your freedom to share and change free
6346 software---to make sure the software is free for all its users. This
6347 General Public License applies to most of the Free Software
6348 Foundation's software and to any other program whose authors commit to
6349 using it. (Some other Free Software Foundation software is covered by
6350 the GNU Library General Public License instead.) You can apply it to
6353 When we speak of free software, we are referring to freedom, not
6354 price. Our General Public Licenses are designed to make sure that you
6355 have the freedom to distribute copies of free software (and charge for
6356 this service if you wish), that you receive source code or can get it
6357 if you want it, that you can change the software or use pieces of it
6358 in new free programs; and that you know you can do these things.
6360 To protect your rights, we need to make restrictions that forbid
6361 anyone to deny you these rights or to ask you to surrender the rights.
6362 These restrictions translate to certain responsibilities for you if you
6363 distribute copies of the software, or if you modify it.
6365 For example, if you distribute copies of such a program, whether
6366 gratis or for a fee, you must give the recipients all the rights that
6367 you have. You must make sure that they, too, receive or can get the
6368 source code. And you must show them these terms so they know their
6371 We protect your rights with two steps: (1) copyright the software, and
6372 (2) offer you this license which gives you legal permission to copy,
6373 distribute and/or modify the software.
6375 Also, for each author's protection and ours, we want to make certain
6376 that everyone understands that there is no warranty for this free
6377 software. If the software is modified by someone else and passed on, we
6378 want its recipients to know that what they have is not the original, so
6379 that any problems introduced by others will not reflect on the original
6380 authors' reputations.
6382 Finally, any free program is threatened constantly by software
6383 patents. We wish to avoid the danger that redistributors of a free
6384 program will individually obtain patent licenses, in effect making the
6385 program proprietary. To prevent this, we have made it clear that any
6386 patent must be licensed for everyone's free use or not licensed at all.
6388 The precise terms and conditions for copying, distribution and
6389 modification follow.
6392 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6395 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6400 This License applies to any program or other work which contains
6401 a notice placed by the copyright holder saying it may be distributed
6402 under the terms of this General Public License. The ``Program'', below,
6403 refers to any such program or work, and a ``work based on the Program''
6404 means either the Program or any derivative work under copyright law:
6405 that is to say, a work containing the Program or a portion of it,
6406 either verbatim or with modifications and/or translated into another
6407 language. (Hereinafter, translation is included without limitation in
6408 the term ``modification''.) Each licensee is addressed as ``you''.
6410 Activities other than copying, distribution and modification are not
6411 covered by this License; they are outside its scope. The act of
6412 running the Program is not restricted, and the output from the Program
6413 is covered only if its contents constitute a work based on the
6414 Program (independent of having been made by running the Program).
6415 Whether that is true depends on what the Program does.
6418 You may copy and distribute verbatim copies of the Program's
6419 source code as you receive it, in any medium, provided that you
6420 conspicuously and appropriately publish on each copy an appropriate
6421 copyright notice and disclaimer of warranty; keep intact all the
6422 notices that refer to this License and to the absence of any warranty;
6423 and give any other recipients of the Program a copy of this License
6424 along with the Program.
6426 You may charge a fee for the physical act of transferring a copy, and
6427 you may at your option offer warranty protection in exchange for a fee.
6430 You may modify your copy or copies of the Program or any portion
6431 of it, thus forming a work based on the Program, and copy and
6432 distribute such modifications or work under the terms of Section 1
6433 above, provided that you also meet all of these conditions:
6437 You must cause the modified files to carry prominent notices
6438 stating that you changed the files and the date of any change.
6441 You must cause any work that you distribute or publish, that in
6442 whole or in part contains or is derived from the Program or any
6443 part thereof, to be licensed as a whole at no charge to all third
6444 parties under the terms of this License.
6447 If the modified program normally reads commands interactively
6448 when run, you must cause it, when started running for such
6449 interactive use in the most ordinary way, to print or display an
6450 announcement including an appropriate copyright notice and a
6451 notice that there is no warranty (or else, saying that you provide
6452 a warranty) and that users may redistribute the program under
6453 these conditions, and telling the user how to view a copy of this
6454 License. (Exception: if the Program itself is interactive but
6455 does not normally print such an announcement, your work based on
6456 the Program is not required to print an announcement.)
6459 These requirements apply to the modified work as a whole. If
6460 identifiable sections of that work are not derived from the Program,
6461 and can be reasonably considered independent and separate works in
6462 themselves, then this License, and its terms, do not apply to those
6463 sections when you distribute them as separate works. But when you
6464 distribute the same sections as part of a whole which is a work based
6465 on the Program, the distribution of the whole must be on the terms of
6466 this License, whose permissions for other licensees extend to the
6467 entire whole, and thus to each and every part regardless of who wrote it.
6469 Thus, it is not the intent of this section to claim rights or contest
6470 your rights to work written entirely by you; rather, the intent is to
6471 exercise the right to control the distribution of derivative or
6472 collective works based on the Program.
6474 In addition, mere aggregation of another work not based on the Program
6475 with the Program (or with a work based on the Program) on a volume of
6476 a storage or distribution medium does not bring the other work under
6477 the scope of this License.
6480 You may copy and distribute the Program (or a work based on it,
6481 under Section 2) in object code or executable form under the terms of
6482 Sections 1 and 2 above provided that you also do one of the following:
6486 Accompany it with the complete corresponding machine-readable
6487 source code, which must be distributed under the terms of Sections
6488 1 and 2 above on a medium customarily used for software interchange; or,
6491 Accompany it with a written offer, valid for at least three
6492 years, to give any third party, for a charge no more than your
6493 cost of physically performing source distribution, a complete
6494 machine-readable copy of the corresponding source code, to be
6495 distributed under the terms of Sections 1 and 2 above on a medium
6496 customarily used for software interchange; or,
6499 Accompany it with the information you received as to the offer
6500 to distribute corresponding source code. (This alternative is
6501 allowed only for noncommercial distribution and only if you
6502 received the program in object code or executable form with such
6503 an offer, in accord with Subsection b above.)
6506 The source code for a work means the preferred form of the work for
6507 making modifications to it. For an executable work, complete source
6508 code means all the source code for all modules it contains, plus any
6509 associated interface definition files, plus the scripts used to
6510 control compilation and installation of the executable. However, as a
6511 special exception, the source code distributed need not include
6512 anything that is normally distributed (in either source or binary
6513 form) with the major components (compiler, kernel, and so on) of the
6514 operating system on which the executable runs, unless that component
6515 itself accompanies the executable.
6517 If distribution of executable or object code is made by offering
6518 access to copy from a designated place, then offering equivalent
6519 access to copy the source code from the same place counts as
6520 distribution of the source code, even though third parties are not
6521 compelled to copy the source along with the object code.
6524 You may not copy, modify, sublicense, or distribute the Program
6525 except as expressly provided under this License. Any attempt
6526 otherwise to copy, modify, sublicense or distribute the Program is
6527 void, and will automatically terminate your rights under this License.
6528 However, parties who have received copies, or rights, from you under
6529 this License will not have their licenses terminated so long as such
6530 parties remain in full compliance.
6533 You are not required to accept this License, since you have not
6534 signed it. However, nothing else grants you permission to modify or
6535 distribute the Program or its derivative works. These actions are
6536 prohibited by law if you do not accept this License. Therefore, by
6537 modifying or distributing the Program (or any work based on the
6538 Program), you indicate your acceptance of this License to do so, and
6539 all its terms and conditions for copying, distributing or modifying
6540 the Program or works based on it.
6543 Each time you redistribute the Program (or any work based on the
6544 Program), the recipient automatically receives a license from the
6545 original licensor to copy, distribute or modify the Program subject to
6546 these terms and conditions. You may not impose any further
6547 restrictions on the recipients' exercise of the rights granted herein.
6548 You are not responsible for enforcing compliance by third parties to
6552 If, as a consequence of a court judgment or allegation of patent
6553 infringement or for any other reason (not limited to patent issues),
6554 conditions are imposed on you (whether by court order, agreement or
6555 otherwise) that contradict the conditions of this License, they do not
6556 excuse you from the conditions of this License. If you cannot
6557 distribute so as to satisfy simultaneously your obligations under this
6558 License and any other pertinent obligations, then as a consequence you
6559 may not distribute the Program at all. For example, if a patent
6560 license would not permit royalty-free redistribution of the Program by
6561 all those who receive copies directly or indirectly through you, then
6562 the only way you could satisfy both it and this License would be to
6563 refrain entirely from distribution of the Program.
6565 If any portion of this section is held invalid or unenforceable under
6566 any particular circumstance, the balance of the section is intended to
6567 apply and the section as a whole is intended to apply in other
6570 It is not the purpose of this section to induce you to infringe any
6571 patents or other property right claims or to contest validity of any
6572 such claims; this section has the sole purpose of protecting the
6573 integrity of the free software distribution system, which is
6574 implemented by public license practices. Many people have made
6575 generous contributions to the wide range of software distributed
6576 through that system in reliance on consistent application of that
6577 system; it is up to the author/donor to decide if he or she is willing
6578 to distribute software through any other system and a licensee cannot
6581 This section is intended to make thoroughly clear what is believed to
6582 be a consequence of the rest of this License.
6585 If the distribution and/or use of the Program is restricted in
6586 certain countries either by patents or by copyrighted interfaces, the
6587 original copyright holder who places the Program under this License
6588 may add an explicit geographical distribution limitation excluding
6589 those countries, so that distribution is permitted only in or among
6590 countries not thus excluded. In such case, this License incorporates
6591 the limitation as if written in the body of this License.
6594 The Free Software Foundation may publish revised and/or new versions
6595 of the General Public License from time to time. Such new versions will
6596 be similar in spirit to the present version, but may differ in detail to
6597 address new problems or concerns.
6599 Each version is given a distinguishing version number. If the Program
6600 specifies a version number of this License which applies to it and ``any
6601 later version'', you have the option of following the terms and conditions
6602 either of that version or of any later version published by the Free
6603 Software Foundation. If the Program does not specify a version number of
6604 this License, you may choose any version ever published by the Free Software
6608 If you wish to incorporate parts of the Program into other free
6609 programs whose distribution conditions are different, write to the author
6610 to ask for permission. For software which is copyrighted by the Free
6611 Software Foundation, write to the Free Software Foundation; we sometimes
6612 make exceptions for this. Our decision will be guided by the two goals
6613 of preserving the free status of all derivatives of our free software and
6614 of promoting the sharing and reuse of software generally.
6617 @heading NO WARRANTY
6624 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
6625 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
6626 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
6627 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
6628 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6629 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
6630 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
6631 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
6632 REPAIR OR CORRECTION.
6635 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
6636 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
6637 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
6638 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
6639 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
6640 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
6641 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
6642 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
6643 POSSIBILITY OF SUCH DAMAGES.
6647 @heading END OF TERMS AND CONDITIONS
6650 @center END OF TERMS AND CONDITIONS
6654 @unnumberedsec Applying These Terms to Your New Programs
6656 If you develop a new program, and you want it to be of the greatest
6657 possible use to the public, the best way to achieve this is to make it
6658 free software which everyone can redistribute and change under these terms.
6660 To do so, attach the following notices to the program. It is safest
6661 to attach them to the start of each source file to most effectively
6662 convey the exclusion of warranty; and each file should have at least
6663 the ``copyright'' line and a pointer to where the full notice is found.
6666 @var{one line to give the program's name and an idea of what it does.}
6667 Copyright (C) 19@var{yy} @var{name of author}
6669 This program is free software; you can redistribute it and/or
6670 modify it under the terms of the GNU General Public License
6671 as published by the Free Software Foundation; either version 2
6672 of the License, or (at your option) any later version.
6674 This program is distributed in the hope that it will be useful,
6675 but WITHOUT ANY WARRANTY; without even the implied warranty of
6676 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6677 GNU General Public License for more details.
6679 You should have received a copy of the GNU General Public License
6680 along with this program; if not, write to the
6681 Free Software Foundation, Inc., 675 Mass Ave,
6682 Cambridge, MA 02139, USA.
6685 Also add information on how to contact you by electronic and paper mail.
6687 If the program is interactive, make it output a short notice like this
6688 when it starts in an interactive mode:
6691 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
6692 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
6693 type `show w'. This is free software, and you are welcome
6694 to redistribute it under certain conditions; type `show c'
6698 The hypothetical commands @samp{show w} and @samp{show c} should show
6699 the appropriate parts of the General Public License. Of course, the
6700 commands you use may be called something other than @samp{show w} and
6701 @samp{show c}; they could even be mouse-clicks or menu items---whatever
6704 You should also get your employer (if you work as a programmer) or your
6705 school, if any, to sign a ``copyright disclaimer'' for the program, if
6706 necessary. Here is a sample; alter the names:
6709 Yoyodyne, Inc., hereby disclaims all copyright interest in
6710 the program `Gnomovision' (which makes passes at compilers)
6711 written by James Hacker.
6713 @var{signature of Ty Coon}, 1 April 1989
6714 Ty Coon, President of Vice
6717 This General Public License does not permit incorporating your program into
6718 proprietary programs. If your program is a subroutine library, you may
6719 consider it more useful to permit linking proprietary applications with the
6720 library. If this is what you want to do, use the GNU Library General
6721 Public License instead of this License.
6723 @node Index, , Copying, Top