6 _if__(_A29K__ && !_GENERIC__)
7 @setfilename as-29k.info
8 _fi__(_A29K__ && !_GENERIC__)
9 _if__(_I960__ && !_GENERIC__)
10 @setfilename as-960.info
11 _fi__(_I960__ && !_GENERIC__)
12 _if__(_M680X0__ && !_GENERIC__)
13 @setfilename as-m680x0.info
14 _fi__(_M680X0__ && !_GENERIC__)
17 NOTE: this manual is marked up for preprocessing with a collection
18 of m4 macros called "pretex.m4".
20 THIS IS THE FULL SOURCE. The full source needs to be run through m4
21 before either tex- or info- formatting: for example,
22 m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
23 will produce (assuming your path finds either GNU or SysV m4; Berkeley
24 won't do) a file suitable for formatting. See the text in "pretex.m4"
25 for a fuller explanation (and the macro definitions).
31 This file documents the GNU Assembler "_AS__".
33 Copyright (C) 1991 Free Software Foundation, Inc.
35 Permission is granted to make and distribute verbatim copies of
36 this manual provided the copyright notice and this permission notice
37 are preserved on all copies.
40 Permission is granted to process this file through Tex and print the
41 results, provided the printed document carries copying permission
42 notice identical to this one except for the removal of this paragraph
43 (this paragraph not being relevant to the printed manual).
46 Permission is granted to copy and distribute modified versions of this
47 manual under the conditions for verbatim copying, provided also that the
48 section entitled ``GNU General Public License'' is included exactly as
49 in the original, and provided that the entire resulting derived work is
50 distributed under the terms of a permission notice identical to this
53 Permission is granted to copy and distribute translations of this manual
54 into another language, under the above conditions for modified versions,
55 except that the section entitled ``GNU General Public License'' may be
56 included in a translation approved by the Free Software Foundation
57 instead of in the original English.
63 @setchapternewpage odd
68 @settitle Using _AS__ (_HOST__)
72 @subtitle The GNU Assembler
74 @subtitle for the _HOST__ family
80 The Free Software Foundation Inc. thanks The Nice Computer
81 Company of Australia for loaning Dean Elsner to write the
82 first (Vax) version of @code{as} for Project GNU.
83 The proprietors, management and staff of TNCCA thank FSF for
84 distracting the boss while they got some work
87 @author Dean Elsner, Jay Fenlason & friends
88 @c edited by: pesch@cygnus.com
91 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
92 \xdef\manvers{\$Revision$} % For use in headers, footers too
95 \hfill \TeX{}info \texinfoversion\par
97 %"boxit" macro for figures:
98 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
99 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
100 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
101 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
102 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
105 Edited by Roland Pesch for Cygnus Support.
107 @vskip 0pt plus 1filll
108 Copyright @copyright{} 1991 Free Software Foundation, Inc.
110 Permission is granted to make and distribute verbatim copies of
111 this manual provided the copyright notice and this permission notice
112 are preserved on all copies.
114 Permission is granted to copy and distribute modified versions of this
115 manual under the conditions for verbatim copying, provided also that the
116 section entitled ``GNU General Public License'' is included exactly as
117 in the original, and provided that the entire resulting derived work is
118 distributed under the terms of a permission notice identical to this
121 Permission is granted to copy and distribute translations of this manual
122 into another language, under the above conditions for modified versions,
123 except that the section entitled ``GNU General Public License'' may be
124 included in a translation approved by the Free Software Foundation
125 instead of in the original English.
128 @node Top, Overview, (dir), (dir)
130 This file is a user guide to the GNU assembler @code{_AS__}.
132 This version of the file describes @code{_AS__} configured to generate
133 code for _HOST__ architectures.
137 * Overview:: Overview
138 * Invoking:: Command-Line Options
140 * Segments:: Segments and Relocation
142 * Expressions:: Expressions
143 * Pseudo Ops:: Assembler Directives
144 * Machine Dependent:: Machine Dependent Features
145 * License:: GNU GENERAL PUBLIC LICENSE
148 @node Overview, Invoking, Top, Top
151 This manual is a user guide to the GNU assembler @code{_AS__}.
153 This version of the manual describes @code{_AS__} configured to generate
154 code for _HOST__ architectures.
158 @heading Invoking @code{_AS__}
160 Here is a brief summary of how to invoke @code{_AS__}. For details,
161 @pxref{Invoking,,Comand-Line Options}.
163 @c We don't use deffn and friends for the following because they seem
164 @c to be limited to one line for the header.
166 _AS__ [ -D ] [ -f ] [ -I @var{path} ] [ -k ] [ -L ]
167 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
169 @c am29k has no machine-dependent assembler options
172 @c see md_parse_option in i960.c
173 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
177 [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
179 [ -- | @var{files} @dots{} ]
185 This option is accepted only for script compatibility with calls to
186 other assemblers; it has no effect on @code{_AS__}.
189 ``fast''---skip preprocessing (assume source is compiler output)
192 Add @var{path} to the search list for @code{.include} directives
195 _if__((!_GENERIC__) && (_A29K__ || _I960__))
196 This option is accepted but has no effect on the _HOST__ family.
197 _fi__((!_GENERIC__) && (_A29K__ || _I960__))
199 Issue warnings when difference tables altered for long displacements.
203 Keep (in symbol table) local symbols, starting with @samp{L}
205 @item -o @var{objfile}
206 Name the object-file output from @code{_AS__}
209 Fold data segment into text segment
212 Announce @code{as} version
215 Suppress warning messages
218 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
219 Specify which variant of the 960 architecture is the target.
222 Add code to collect statistics about branches taken.
225 Do not alter compare-and-branch instructions for long displaements;
232 (When configured for Motorola 68000).
234 Shorten references to undefined symbols, to one word instead of two
236 @item -mc68000 | -mc68010 | -mc68020
238 (When configured for Motorola 68000).
240 Specify what processor in the 68000 family is the target (default 68020)
243 @item -- | @var{files} @dots{}
244 Source files to assemble, or standard input
248 * Manual:: Structure of this Manual
249 * GNU Assembler:: _AS__, the GNU Assembler
250 * Object Formats:: Object File Formats
251 * Command Line:: Command Line
252 * Input Files:: Input Files
253 * Object:: Output (Object) File
254 * Errors:: Error and Warning Messages
257 @node Manual, GNU Assembler, Overview, Overview
258 @section Structure of this Manual
259 This document is intended to describe what you need to know to use
260 @code{_AS__}. We cover the syntax expected in source files, including
261 notation for symbols, constants, and expressions; the directives that
262 @code{_AS__} understands; and of course how to invoke @code{_AS__}.
265 We also cover special features in the _HOST__
266 configuration of @code{_AS__}, including assembler directives.
269 This document also describes some of the machine-dependent features of
270 various flavors of the assembler.
273 This document also describes how the assembler works internally, and
274 provides some information that may be useful to people attempting to
275 port the assembler to another machine.
279 On the other hand, this manual is @emph{not} intended as an introduction
280 to programming in assembly language---let alone programming in general!
281 In a similar vein, we make no attempt to introduce the machine
282 architecture; we do @emph{not} describe the instruction set, standard
283 mnemonics, registers or addressing modes that are standard to a
284 particular architecture. You may want to consult the manufacturer's
285 machine architecture manual for this information.
288 @c I think this is premature---pesch@cygnus.com, 17jan1991
290 Throughout this document, we assume that you are running @dfn{GNU},
291 the portable operating system from the @dfn{Free Software
292 Foundation, Inc.}. This restricts our attention to certain kinds of
293 computer (in particular, the kinds of computers that GNU can run on);
294 once this assumption is granted examples and definitions need less
297 @code{_AS__} is part of a team of programs that turn a high-level
298 human-readable series of instructions into a low-level
299 computer-readable series of instructions. Different versions of
300 @code{_AS__} are used for different kinds of computer.
303 @c There used to be a section "Terminology" here, which defined
304 @c "contents", "byte", "word", and "long". Defining "word" to any
305 @c particular size is confusing when the .word directive may generate 16
306 @c bits on one machine and 32 bits on another; in general, for the user
307 @c version of this manual, none of these terms seem essential to define.
308 @c They were used very little even in the former draft of the manual;
309 @c this draft makes an effort to avoid them (except in names of
312 @node GNU Assembler, Object Formats, Manual, Overview
313 @section _AS__, the GNU Assembler
314 GNU @code{as} is really a family of assemblers.
316 This manual describes @samp{_AS__}, a member of that family which is
317 configured for the _HOST__ architectures.
319 If you use (or have used) the GNU assembler on one architecture, you
320 should find a fairly similar environment when you use it on another
321 architecture. Each version has much in common with the others,
322 including object file formats, most assembler directives (often called
323 @dfn{pseudo-ops)} and assembler syntax.@refill
325 @code{_AS__} is primarily intended to assemble the output of the GNU C
326 compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless,
327 we've tried to make @code{_AS__} assemble correctly everything that the native
330 Any exceptions are documented explicitly (@pxref{_MACH_DEP__}).
332 _if__(_GENERIC__||_M680X0__)
333 This doesn't mean @code{_AS__} always uses the same syntax as another
334 assembler for the same architecture; for example, we know of several
335 incompatible versions of 680x0 assembly language syntax.
336 _fi__(_GENERIC__||_M680X0__)
338 Unlike older assemblers, @code{_AS__} is designed to assemble a source
339 program in one pass of the source file. This has a subtle impact on the
340 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
342 @node Object Formats, Command Line, GNU Assembler, Overview
343 @section Object File Formats
344 The GNU assembler can be configured to produce several alternative
345 object file formats. For the most part, this does not affect how you
346 write assembly language programs; but directives for debugging symbols
347 are typically different in different file formats. @xref{Symbol
348 Attributes,,Symbol Attributes}.
351 On the _HOST__, @code{_AS__} is configured to produce @code{a.out} format object
355 On the _HOST__, @code{_AS__} can be configured to produce either @code{b.out} or COFF
360 @node Command Line, Input Files, Object Formats, Overview
361 @section Command Line
363 After the program name @code{_AS__}, the command line may contain
364 options and file names. Options may be in any order, and may be
365 before, after, or between file names. The order of file names is
368 @file{--} (two hyphens) by itself names the standard input file
369 explicitly, as one of the files for @code{_AS__} to assemble.
371 Except for @samp{--} any command line argument that begins with a
372 hyphen (@samp{-}) is an option. Each option changes the behavior of
373 @code{_AS__}. No option changes the way another option works. An
374 option is a @samp{-} followed by one or more letters; the case of
375 the letter is important. All options are optional.
377 Some options expect exactly one file name to follow them. The file
378 name may either immediately follow the option's letter (compatible
379 with older assemblers) or it may be the next command argument (GNU
380 standard). These two command lines are equivalent:
383 _AS__ -o my-object-file.o mumble.s
384 _AS__ -omy-object-file.o mumble.s
387 @node Input Files, Object, Command Line, Overview
390 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
391 describe the program input to one run of @code{_AS__}. The program may
392 be in one or more files; how the source is partitioned into files
393 doesn't change the meaning of the source.
395 @c I added "con" prefix to "catenation" just to prove I can overcome my
396 @c APL training... pesch@cygnus.com
397 The source program is a concatenation of the text in all the files, in the
400 Each time you run @code{_AS__} it assembles exactly one source
401 program. The source program is made up of one or more files.
402 (The standard input is also a file.)
404 You give @code{_AS__} a command line that has zero or more input file
405 names. The input files are read (from left file name to right). A
406 command line argument (in any position) that has no special meaning
407 is taken to be an input file name.
409 If @code{_AS__} is given no file names it attempts to read one input file
410 from the @code{_AS__} standard input, which is normally your terminal. You
411 may have to type @key{ctl-D} to tell @code{_AS__} there is no more program
414 Use @samp{--} if you need to explicitly name the standard input file
415 in your command line.
417 If the source is empty, @code{_AS__} will produce a small, empty object
420 @subheading Filenames and Line-numbers
421 There are two ways of locating a line in the input file (or files) and both
422 are used in reporting error messages. One way refers to a line
423 number in a physical file; the other refers to a line number in a
426 @dfn{Physical files} are those files named in the command line given
429 @dfn{Logical files} are simply names declared explicitly by assembler
430 directives; they bear no relation to physical files. Logical file names
431 help error messages reflect the original source file, when @code{_AS__}
432 source is itself synthesized from other files.
433 @xref{App-File,,@code{.app-file}}.
435 @node Object, Errors, Input Files, Overview
436 @section Output (Object) File
437 Every time you run @code{_AS__} it produces an output file, which is
438 your assembly language program translated into numbers. This file
439 is the object file, named @code{a.out} unless you tell @code{_AS__} to
440 give it another name by using the @code{-o} option. Conventionally,
441 object file names end with @file{.o}. The default name of
442 @file{a.out} is used for historical reasons: older assemblers were
443 capable of assembling self-contained programs directly into a
445 @c This may still work, but hasn't been tested.
447 The object file is meant for input to the linker @code{_LD__}. It contains
448 assembled program code, information to help @code{_LD__} integrate
449 the assembled program into a runnable file, and (optionally) symbolic
450 information for the debugger.
452 @comment link above to some info file(s) like the description of a.out.
453 @comment don't forget to describe GNU info as well as Unix lossage.
455 @node Errors, , Object, Overview
456 @section Error and Warning Messages
458 @code{_AS__} may write warnings and error messages to the standard error
459 file (usually your terminal). This should not happen when @code{_AS__} is
460 run automatically by a compiler. Warnings report an assumption made so
461 that @code{_AS__} could keep assembling a flawed program; errors report a
462 grave problem that stops the assembly.
464 Warning messages have the format
466 file_name:@b{NNN}:Warning Message Text
469 (where @b{NNN} is a line number). If a logical file name has
470 been given (@pxref{App-File,,@code{.app-file}}) it is used for the filename, otherwise the
471 name of the current input file is used. If a logical line number was
474 (@pxref{Line,,@code{.line}})
477 (@pxref{Ln,,@code{.ln}})
479 then it is used to calculate the number printed,
480 otherwise the actual line in the current source file is printed. The
481 message text is intended to be self explanatory (in the grand Unix
484 Error messages have the format
486 file_name:@b{NNN}:FATAL:Error Message Text
488 The file name and line number are derived as for warning
489 messages. The actual message text may be rather less explanatory
490 because many of them aren't supposed to happen.
492 @node Invoking, Syntax, Overview, Top
493 @chapter Command-Line Options
494 This section describes command-line options available in @emph{all}
495 versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific
500 to particular machine architectures.
503 @subsection @code{-D}
504 This option has no effect whatsoever, but it is accepted to make it more
505 likely that scripts written for other assemblers will also work with
508 @subsection Work Faster: @code{-f}
509 @samp{-f} should only be used when assembling programs written by a
510 (trusted) compiler. @samp{-f} stops the assembler from pre-processing
511 the input file(s) before assembling them.
513 @emph{Warning:} if the files actually need to be pre-processed (if they
514 contain comments, for example), @code{_AS__} will not work correctly if
518 @subsection @code{.include} search path: @code{-I} @var{path}
519 Use this option to add a @var{path} to the list of directories
520 @code{_AS__} will search for files specified in @code{.include}
521 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
522 many times as necessary to include a variety of paths. The current
523 working directory is always searched first; after that, @code{_AS__}
524 searches any @samp{-I} directories in the same order as they were
525 specified (left to right) on the command line.
527 @subsection Difference Tables: @code{-k}
528 _if__((!_GENERIC__) && (_A29K__ || _I960__))
529 On the _HOST__ family, this option is allowed, but has no effect. It is
530 permitted for compatibility with the GNU assembler on other platforms,
531 where it can be used to warn when the assembler alters the machine code
532 generated for @samp{.word} directives in difference tables. The _HOST__
533 family does not have the addressing limitations that sometimes lead to this
534 alteration on other platforms.
535 _fi__((!_GENERIC__) && (_A29K__ || _I960__))
537 _if__(_GENERIC__ || (! _A29K__ || _I960__ ))
538 @code{_AS__} sometimes alters the code emitted for directives of the form
539 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
540 You can use the @samp{-k} option if you want a warning issued when this
542 _fi__(_GENERIC__ || (! _A29K__ || _I960__ ))
544 @subsection Include Local Labels: @code{-L}
545 Labels beginning with @samp{L} (upper case only) are called @dfn{local
546 labels}. @xref{Symbol Names}. Normally you don't see such labels when
547 debugging, because they are intended for the use of programs (like
548 compilers) that compose assembler programs, not for your notice.
549 Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't
550 normally debug with them.
552 This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols
553 in the object file. Usually if you do this you also tell the linker
554 @code{_LD__} to preserve symbols whose names begin with @samp{L}.
556 @subsection Name the Object File: @code{-o}
557 There is always one object file output when you run @code{_AS__}. By
558 default it has the name @file{a.out}. You use this option (which
559 takes exactly one filename) to give the object file a different name.
561 Whatever the object file is called, @code{_AS__} will overwrite any
562 existing file of the same name.
564 @subsection Join Data and Text Segments: @code{-R}
565 @code{-R} tells @code{_AS__} to write the object file as if all
566 data-segment data lives in the text segment. This is only done at
567 the very last moment: your binary data are the same, but data
568 segment parts are relocated differently. The data segment part of
569 your object file is zero bytes long because all it bytes are
570 appended to the text segment. (@xref{Segments,,Segments and Relocation}.)
572 When you specify @code{-R} it would be possible to generate shorter
573 address displacements (because we don't have to cross between text and
574 data segment). We refrain from doing this simply for compatibility with
575 older versions of @code{_AS__}. In future, @code{-R} may work this way.
577 @subsection Announce Version: @code{-v}
578 You can find out what version of as is running by including the
579 option @samp{-v} (which you can also spell as @samp{-version}) on the
582 @subsection Suppress Warnings: @code{-W}
583 @code{_AS__} should never give a warning or error message when
584 assembling compiler output. But programs written by people often
585 cause @code{_AS__} to give a warning that a particular assumption was
586 made. All such warnings are directed to the standard error file.
587 If you use this option, no warnings are issued. This option only
588 affects the warning messages: it does not change any particular of how
589 @code{_AS__} assembles your file. Errors, which stop the assembly, are
592 @node Syntax, Segments, Invoking, Top
594 This chapter describes the machine-independent syntax allowed in a
595 source file. @code{_AS__} syntax is similar to what many other assemblers
596 use; it is inspired in BSD 4.2
601 assembler, except that @code{_AS__} does not assemble Vax bit-fields.
605 * Pre-processing:: Pre-processing
606 * Whitespace:: Whitespace
607 * Comments:: Comments
608 * Symbol Intro:: Symbols
609 * Statements:: Statements
610 * Constants:: Constants
613 @node Pre-processing, Whitespace, Syntax, Syntax
614 @section Pre-processing
619 adjusts and removes extra whitespace. It leaves one space or tab before
620 the keywords on a line, and turns any other whitespace on the line into
624 removes all comments, replacing them with a single space, or an
625 appropriate number of newlines.
628 converts character constants into the appropriate numeric values.
631 Excess whitespace, comments, and character constants
632 cannot be used in the portions of the input text that are not
635 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
636 option is given, the input file will not be pre-processed. Within such
637 an input file, parts of the file can be pre-processed by putting a line
638 that says @code{#APP} before the text that should be pre-processed, and
639 putting a line that says @code{#NO_APP} after them. This feature is
640 mainly intend to support @code{asm} statements in compilers whose output
641 normally does not need to be pre-processed.
643 @node Whitespace, Comments, Pre-processing, Syntax
645 @dfn{Whitespace} is one or more blanks or tabs, in any order.
646 Whitespace is used to separate symbols, and to make programs neater for
647 people to read. Unless within character constants
648 (@pxref{Characters,,Character Constants}), any whitespace means the same
649 as exactly one space.
651 @node Comments, Symbol Intro, Whitespace, Syntax
653 There are two ways of rendering comments to @code{_AS__}. In both
654 cases the comment is equivalent to one space.
656 Anything from @samp{/*} through the next @samp{*/} is a comment.
657 This means you may not nest these comments.
661 The only way to include a newline ('\n') in a comment
662 is to use this sort of comment.
665 /* This sort of comment does not nest. */
668 Anything from the @dfn{line comment} character to the next newline
669 is considered a comment and is ignored. The line comment character is
674 @samp{#} on the i960;
677 @samp{|} on the 680x0;
680 @samp{;} for the AMD 29K family;
682 @pxref{_MACH_DEP__}. @refill
683 @c FIXME: fill in SPARC line comment char
686 On some machines there are two different line comment characters. One
687 will only begin a comment if it is the first non-whitespace character on
688 a line, while the other will always begin a comment.
691 To be compatible with past assemblers a special interpretation is
692 given to lines that begin with @samp{#}. Following the @samp{#} an
693 absolute expression (@pxref{Expressions}) is expected: this will be
694 the logical line number of the @b{next} line. Then a string
695 (@xref{Strings}.) is allowed: if present it is a new logical file
696 name. The rest of the line, if any, should be whitespace.
698 If the first non-whitespace characters on the line are not numeric,
699 the line is ignored. (Just like a comment.)
701 # This is an ordinary comment.
702 # 42-6 "new_file_name" # New logical file name
703 # This is logical line # 36.
705 This feature is deprecated, and may disappear from future versions
708 @node Symbol Intro, Statements, Comments, Syntax
710 A @dfn{symbol} is one or more characters chosen from the set of all
711 letters (both upper and lower case), digits and the three characters
712 @samp{_.$}. No symbol may begin with a digit. Case is significant.
713 There is no length limit: all characters are significant. Symbols are
714 delimited by characters not in that set, or by the beginning of a file
715 (since the source program must end with a newline, the end of a file is
716 not a possible symbol delimiter). @xref{Symbols}.
718 @node Statements, Constants, Symbol Intro, Syntax
721 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
722 semicolon (@samp{;}). The newline or semicolon is considered part of
723 the preceding statement. Newlines and semicolons within character
724 constants are an exception: they don't end statements.
727 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
728 sign (@samp{@@}). The newline or at sign is considered part of the
729 preceding statement. Newlines and at signs within character constants
730 are an exception: they don't end statements.
733 It is an error to end any statement with end-of-file: the last
734 character of any input file should be a newline.@refill
736 You may write a statement on more than one line if you put a
737 backslash (@kbd{\}) immediately in front of any newlines within the
738 statement. When @code{_AS__} reads a backslashed newline both
739 characters are ignored. You can even put backslashed newlines in
740 the middle of symbol names without changing the meaning of your
743 An empty statement is allowed, and may include whitespace. It is ignored.
745 @c "key symbol" is not used elsewhere in the document; seems pedantic to
746 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
748 A statement begins with zero or more labels, optionally followed by a
749 key symbol which determines what kind of statement it is. The key
750 symbol determines the syntax of the rest of the statement. If the
751 symbol begins with a dot @samp{.} then the statement is an assembler
752 directive: typically valid for any computer. If the symbol begins with
753 a letter the statement is an assembly language @dfn{instruction}: it
754 will assemble into a machine language instruction.
756 Different versions of @code{_AS__} for different computers will
757 recognize different instructions. In fact, the same symbol may
758 represent a different instruction in a different computer's assembly
762 A label is a symbol immediately followed by a colon (@code{:}).
763 Whitespace before a label or after a colon is permitted, but you may not
764 have whitespace between a label's symbol and its colon. @xref{Labels}.
767 label: .directive followed by something
768 another$label: # This is an empty statement.
769 instruction operand_1, operand_2, @dots{}
772 @node Constants, , Statements, Syntax
774 A constant is a number, written so that its value is known by
775 inspection, without knowing any context. Like this:
777 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
778 .ascii "Ring the bell\7" # A string constant.
779 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
780 .float 0f-314159265358979323846264338327\
781 95028841971.693993751E-40 # - pi, a flonum.
785 * Characters:: Character Constants
786 * Numbers:: Number Constants
789 @node Characters, Numbers, Constants, Constants
790 @subsection Character Constants
791 There are two kinds of character constants. A @dfn{character} stands
792 for one character in one byte and its value may be used in
793 numeric expressions. String constants (properly called string
794 @emph{literals}) are potentially many bytes and their values may not be
795 used in arithmetic expressions.
802 @node Strings, Chars, Characters, Characters
803 @subsubsection Strings
804 A @dfn{string} is written between double-quotes. It may contain
805 double-quotes or null characters. The way to get special characters
806 into a string is to @dfn{escape} these characters: precede them with
807 a backslash @samp{\} character. For example @samp{\\} represents
808 one backslash: the first @code{\} is an escape which tells
809 @code{_AS__} to interpret the second character literally as a backslash
810 (which prevents @code{_AS__} from recognizing the second @code{\} as an
811 escape character). The complete list of escapes follows.
815 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
817 Mnemonic for backspace; for ASCII this is octal code 010.
819 @c Mnemonic for EOText; for ASCII this is octal code 004.
821 Mnemonic for FormFeed; for ASCII this is octal code 014.
823 Mnemonic for newline; for ASCII this is octal code 012.
825 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
827 Mnemonic for carriage-Return; for ASCII this is octal code 015.
829 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
832 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
834 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
835 @c @item \x @var{digit} @var{digit} @var{digit}
836 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
837 @item \ @var{digit} @var{digit} @var{digit}
838 An octal character code. The numeric code is 3 octal digits.
839 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
840 for example, @code{\008} has the value 010, and @code{\009} the value 011.
842 Represents one @samp{\} character.
844 @c Represents one @samp{'} (accent acute) character.
845 @c This is needed in single character literals
846 @c (@xref{Characters,,Character Constants}.) to represent
849 Represents one @samp{"} character. Needed in strings to represent
850 this character, because an unescaped @samp{"} would end the string.
851 @item \ @var{anything-else}
852 Any other character when escaped by @kbd{\} will give a warning, but
853 assemble as if the @samp{\} was not present. The idea is that if
854 you used an escape sequence you clearly didn't want the literal
855 interpretation of the following character. However @code{_AS__} has no
856 other interpretation, so @code{_AS__} knows it is giving you the wrong
857 code and warns you of the fact.
860 Which characters are escapable, and what those escapes represent,
861 varies widely among assemblers. The current set is what we think
862 the BSD 4.2 assembler recognizes, and is a subset of what most C
863 compilers recognize. If you are in doubt, don't use an escape
866 @node Chars, , Strings, Characters
867 @subsubsection Characters
868 A single character may be written as a single quote immediately
869 followed by that character. The same escapes apply to characters as
870 to strings. So if you want to write the character backslash, you
871 must write @kbd{'\\} where the first @code{\} escapes the second
872 @code{\}. As you can see, the quote is an acute accent, not a
873 grave accent. A newline
875 (or semicolon @samp{;})
878 (or at sign @samp{@@})
880 immediately following an acute accent is taken as a literal character
881 and does not count as the end of a statement. The value of a character
882 constant in a numeric expression is the machine's byte-wide code for
883 that character. @code{_AS__} assumes your character code is ASCII:
884 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
886 @node Numbers, , Characters, Constants
887 @subsection Number Constants
888 @code{_AS__} distinguishes three kinds of numbers according to how they
889 are stored in the target machine. @emph{Integers} are numbers that
890 would fit into an @code{int} in the C language. @emph{Bignums} are
891 integers, but they are stored in more than 32 bits. @emph{Flonums}
892 are floating point numbers, described below.
895 * Integers:: Integers
898 _if__(_I960__&&!_GENERIC__)
899 * Bit Fields:: Bit Fields
900 _fi__(_I960__&&!_GENERIC__)
903 @node Integers, Bignums, Numbers, Numbers
904 @subsubsection Integers
905 @c FIXME: are binary integers in vintage as?
906 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
907 the binary digits @samp{01}.
909 An octal integer is @samp{0} followed by zero or more of the octal
910 digits (@samp{01234567}).
912 A decimal integer starts with a non-zero digit followed by zero or
913 more digits (@samp{0123456789}).
915 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
916 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
918 Integers have the usual values. To denote a negative integer, use
919 the prefix operator @samp{-} discussed under expressions
920 (@pxref{Prefix Ops,,Prefix Operators}).
922 @node Bignums, Flonums, Integers, Numbers
923 @subsubsection Bignums
924 A @dfn{bignum} has the same syntax and semantics as an integer
925 except that the number (or its negative) takes more than 32 bits to
926 represent in binary. The distinction is made because in some places
927 integers are permitted while bignums are not.
929 _if__(_I960__&&!_GENERIC__)
930 @node Flonums, Bit Fields, Bignums, Numbers
931 _fi__(_I960__&&!_GENERIC__)
932 _if__(_GENERIC__||!_I960__)
933 @node Flonums, , Bignums, Numbers
934 _fi__(_GENERIC__||!_I960__)
935 @subsubsection Flonums
936 A @dfn{flonum} represents a floating point number. The translation is
937 complex: a decimal floating point number from the text is converted by
938 @code{_AS__} to a generic binary floating point number of more than
939 sufficient precision. This generic floating point number is converted
940 to a particular computer's floating point format (or formats) by a
941 portion of @code{_AS__} specialized to that computer.
943 A flonum is written by writing (in order)
949 A letter, to tell @code{_AS__} the rest of the number is a flonum. @kbd{e}
950 is recommended. Case is not important.
952 @c FIXME: verify if flonum syntax really this vague for most cases
953 (Any otherwise illegal letter
954 will work here, but that might be changed. Vax BSD 4.2 assembler seems
955 to allow any of @samp{defghDEFGH}.)
960 On the AMD 29K architecture, the letter must be:
962 One of the letters @samp{DFPRSX} (in upper or lower case), to tell
963 @code{_AS__} the rest of the number is a flonum.
967 On the Intel 960 architecture, the letter must be:
969 One of the letters @samp{DFT} (in upper or lower case), to tell
970 @code{_AS__} the rest of the number is a flonum.
973 An optional sign: either @samp{+} or @samp{-}.
975 An optional @dfn{integer part}: zero or more decimal digits.
977 An optional @dfn{fraction part}: @samp{.} followed by zero
978 or more decimal digits.
980 An optional exponent, consisting of:
983 An @samp{E} or @samp{e}.
984 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
985 @c principle this can perfectly well be different on different targets.
987 Optional sign: either @samp{+} or @samp{-}.
989 One or more decimal digits.
993 At least one of @var{integer part} or @var{fraction part} must be
994 present. The floating point number has the usual base-10 value.
996 @code{_AS__} does all processing using integers. Flonums are computed
997 independently of any floating point hardware in the computer running
1000 _if__(_I960__&&!_GENERIC__)
1001 @c Bit fields are written as a general facility but are also controlled
1002 @c by a conditional-compilation flag---which is as of now (21mar91)
1003 @c turned on only by the i960 config of GAS.
1004 @node Bit Fields, , Flonums, Numbers
1005 @subsubsection Bit Fields
1006 You can also define numeric constants as @dfn{bit fields}.
1007 specify two numbers separated by a colon---
1009 @var{mask}:@var{value}
1012 the first will act as a mask; @code{_AS__} will bitwise-and it with the
1015 The resulting number is then packed
1017 @c this conditional paren in case bit fields turned on elsewhere than 960
1018 (in host-dependent byte order)
1020 into a field whose width depends on which assembler directive has the
1021 bit-field as its argument. Overflow (a result from the bitwise and
1022 requiring more binary digits to represent) is not an error; instead,
1023 more constants are generated, of the specified width, beginning with the
1024 least significant digits.@refill
1026 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1027 @code{.short}, and @code{.word} accept bit-field arguments.
1028 _fi__(_I960__&&!_GENERIC__)
1030 @node Segments, Symbols, Syntax, Top
1031 @chapter Segments and Relocation
1034 * Segs Background:: Background
1035 * _LD__ Segments:: _LD__ Segments
1036 * _AS__ Segments:: _AS__ Internal Segments
1037 * Sub-Segments:: Sub-Segments
1041 @node Segs Background, _LD__ Segments, Segments, Segments
1043 Roughly, a segment is a range of addresses, with no gaps; all data
1044 ``in'' those addresses is treated the same for some particular purpose.
1045 For example there may be a ``read only'' segment.
1047 The linker @code{_LD__} reads many object files (partial programs) and
1048 combines their contents to form a runnable program. When @code{_AS__}
1049 emits an object file, the partial program is assumed to start at address
1050 0. @code{_LD__} will assign the final addresses the partial program
1051 occupies, so that different partial programs don't overlap. This is
1052 actually an over-simplification, but it will suffice to explain how
1053 @code{_AS__} uses segments.
1055 @code{_LD__} moves blocks of bytes of your program to their run-time
1056 addresses. These blocks slide to their run-time addresses as rigid
1057 units; their length does not change and neither does the order of bytes
1058 within them. Such a rigid unit is called a @emph{segment}. Assigning
1059 run-time addresses to segments is called @dfn{relocation}. It includes
1060 the task of adjusting mentions of object-file addresses so they refer to
1061 the proper run-time addresses.
1063 An object file written by @code{_AS__} has three segments, any of which may
1064 be empty. These are named @dfn{text}, @dfn{data} and @dfn{bss}
1070 @emph{Warning:} @code{_AS__} can only assign output to one of these
1071 three segments, even when configured for COFF output; the
1072 @code{.section} directive is not supported.
1076 Within the object file, the text segment starts at address @code{0}, the
1077 data segment follows, and the bss segment follows the data segment.
1079 To let @code{_LD__} know which data will change when the segments are
1080 relocated, and how to change that data, @code{_AS__} also writes to the
1081 object file details of the relocation needed. To perform relocation
1082 @code{_LD__} must know, each time an address in the object
1086 Where in the object file is the beginning of this reference to
1089 How long (in bytes) is this reference?
1091 Which segment does the address refer to? What is the numeric value of
1093 (@var{address}) @minus{} (@var{start-address of segment})?
1096 Is the reference to an address ``Program-Counter relative''?
1099 In fact, every address @code{_AS__} ever uses is expressed as
1101 (@var{segment}) + (@var{offset into segment})
1104 Further, every expression @code{_AS__} computes is of this segmented
1105 nature. @dfn{Absolute expression} means an expression with segment
1106 ``absolute'' (@pxref{_LD__ Segments}). A @dfn{pass1 expression} means
1107 an expression with segment ``pass1'' (@pxref{_AS__ Segments,,_AS__
1108 Internal Segments}). In this manual we use the notation @{@var{segname}
1109 @var{N}@} to mean ``offset @var{N} into segment @var{segname}''.
1111 Apart from text, data and bss segments you need to know about the
1112 @dfn{absolute} segment. When @code{_LD__} mixes partial programs,
1113 addresses in the absolute segment remain unchanged. That is, address
1114 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}.
1115 Although two partial programs' data segments will not overlap addresses
1116 after linking, @emph{by definition} their absolute segments will overlap.
1117 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1118 address when the program is running as address @code{@{absolute@ 239@}} in any
1119 other partial program.
1121 The idea of segments is extended to the @dfn{undefined} segment. Any
1122 address whose segment is unknown at assembly time is by definition
1123 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1124 Since numbers are always defined, the only way to generate an undefined
1125 address is to mention an undefined symbol. A reference to a named
1126 common block would be such a symbol: its value is unknown at assembly
1127 time so it has segment @emph{undefined}.
1129 By analogy the word @emph{segment} is used to describe groups of segments in
1130 the linked program. @code{_LD__} puts all partial programs' text
1131 segments in contiguous addresses in the linked program. It is
1132 customary to refer to the @emph{text segment} of a program, meaning all
1133 the addresses of all partial program's text segments. Likewise for
1134 data and bss segments.
1136 Some segments are manipulated by @code{_LD__}; others are invented for
1137 use of @code{_AS__} and have no meaning except during assembly.
1139 @node _LD__ Segments, _AS__ Segments, Segs Background, Segments
1140 @section _LD__ Segments
1141 @code{_LD__} deals with just five kinds of segments, summarized below.
1147 These segments hold your program. @code{_AS__} and @code{_LD__} treat them as
1148 separate but equal segments. Anything you can say of one segment is
1149 true of the other. When the program is running, however, it is
1150 customary for the text segment to be unalterable. The
1151 text segment is often shared among processes: it will contain
1152 instructions, constants and the like. The data segment of a running
1153 program is usually alterable: for example, C variables would be stored
1154 in the data segment.
1157 This segment contains zeroed bytes when your program begins running. It
1158 is used to hold unitialized variables or common storage. The length of
1159 each partial program's bss segment is important, but because it starts
1160 out containing zeroed bytes there is no need to store explicit zero
1161 bytes in the object file. The bss segment was invented to eliminate
1162 those explicit zeros from object files.
1164 @item absolute segment
1165 Address 0 of this segment is always ``relocated'' to runtime address 0.
1166 This is useful if you want to refer to an address that @code{_LD__} must
1167 not change when relocating. In this sense we speak of absolute
1168 addresses being ``unrelocatable'': they don't change during relocation.
1170 @item undefined segment
1171 This ``segment'' is a catch-all for address references to objects not in
1172 the preceding segments.
1173 @c FIXME: ref to some other doc on obj-file formats could go here.
1177 An idealized example of the three relocatable segments follows. Memory
1178 addresses are on the horizontal axis.
1182 @c END TEXI2ROFF-KILL
1185 partial program # 1: |ttttt|dddd|00|
1192 partial program # 2: |TTT|DDD|000|
1195 +--+---+-----+--+----+---+-----+~~
1196 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1197 +--+---+-----+--+----+---+-----+~~
1199 addresses: 0 @dots{}
1205 {\it Partial program \#1: }
1207 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1208 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1210 {\it Partial program \#2:}
1212 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1213 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1215 {\it linked program: }
1217 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1218 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1219 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1220 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1227 @c END TEXI2ROFF-KILL
1229 @node _AS__ Segments, Sub-Segments, _LD__ Segments, Segments
1230 @section _AS__ Internal Segments
1231 These segments are invented for the internal use of @code{_AS__}. They
1232 have no meaning at run-time. You don't need to know about these
1233 segments except that they might be mentioned in the @code{_AS__} warning
1234 messages. These segments are invented to permit the value of every
1235 expression in your assembly language program to be a segmented
1239 @item absent segment
1240 An expression was expected and none was
1244 An internal assembler logic error has been
1245 found. This means there is a bug in the assembler.
1248 A @dfn{grand number} is a bignum or a flonum, but not an integer. If a
1249 number can't be written as a C @code{int} constant, it is a grand
1250 number. @code{_AS__} has to remember that a flonum or a bignum does not
1251 fit into 32 bits, and cannot be an argument (@pxref{Arguments}) in an
1252 expression: this is done by making a flonum or bignum be in segment
1253 grand. This is purely for internal @code{_AS__} convenience; grand
1254 segment behaves similarly to absolute segment.
1257 The expression was impossible to evaluate in the first pass. The
1258 assembler will attempt a second pass (second reading of the source) to
1259 evaluate the expression. Your expression mentioned an undefined symbol
1260 in a way that defies the one-pass (segment + offset in segment) assembly
1261 process. No compiler need emit such an expression.
1264 @emph{Warning:} the second pass is currently not implemented. @code{_AS__}
1265 will abort with an error message if one is required.
1268 @item difference segment
1269 As an assist to the C compiler, expressions of the forms
1271 (@var{undefined symbol}) @minus{} (@var{expression})
1272 @var{something} @minus{} (@var{undefined symbol})
1273 (@var{undefined symbol}) @minus{} (@var{undefined symbol})
1275 are permitted, and belong to the difference segment. @code{_AS__}
1276 re-evaluates such expressions after the source file has been read and
1277 the symbol table built. If by that time there are no undefined symbols
1278 in the expression then the expression assumes a new segment. The
1279 intention is to permit statements like
1280 @samp{.word label - base_of_table}
1281 to be assembled in one pass where both @code{label} and
1282 @code{base_of_table} are undefined. This is useful for compiling C and
1283 Algol switch statements, Pascal case statements, FORTRAN computed goto
1284 statements and the like.
1287 @node Sub-Segments, bss, _AS__ Segments, Segments
1288 @section Sub-Segments
1289 Assembled bytes fall into two segments: text and data.
1290 Because you may have groups of text or data that you want to end up near
1291 to each other in the object file, @code{_AS__} allows you to use
1292 @dfn{subsegments}. Within each segment, there can be numbered
1293 subsegments with values from 0 to 8192. Objects assembled into the same
1294 subsegment will be grouped with other objects in the same subsegment
1295 when they are all put into the object file. For example, a compiler
1296 might want to store constants in the text segment, but might not want to
1297 have them interspersed with the program being assembled. In this case,
1298 the compiler could issue a @code{text 0} before each section of code
1299 being output, and a @code{text 1} before each group of constants being
1302 Subsegments are optional. If you don't use subsegments, everything
1303 will be stored in subsegment number zero.
1306 Each subsegment is zero-padded up to a multiple of four bytes.
1307 (Subsegments may be padded a different amount on different flavors
1311 @c Rich Pixley says padding here depends on target obj code format; that
1312 @c doesn't seem particularly useful to say without further elaboration,
1313 @c so for now I say nothing about it. If this is a generic BFD issue,
1314 @c these paragraphs might need to vanish from this manual, and be
1315 @c discussed in BFD chapter of binutils (or some such).
1318 On the AMD 29K family, no particular padding is added to segment sizes;
1319 _AS__ forces no alignment on this platform.
1321 Subsegments appear in your object file in numeric order, lowest numbered
1322 to highest. (All this to be compatible with other people's assemblers.)
1323 The object file contains no representation of subsegments; @code{_LD__} and
1324 other programs that manipulate object files will see no trace of them.
1325 They just see all your text subsegments as a text segment, and all your
1326 data subsegments as a data segment.
1328 To specify which subsegment you want subsequent statements assembled
1329 into, use a @samp{.text @var{expression}} or a @samp{.data
1330 @var{expression}} statement. @var{Expression} should be an absolute
1331 expression. (@xref{Expressions}.) If you just say @samp{.text}
1332 then @samp{.text 0} is assumed. Likewise @samp{.data} means
1333 @samp{.data 0}. Assembly begins in @code{text 0}.
1336 .text 0 # The default subsegment is text 0 anyway.
1337 .ascii "This lives in the first text subsegment. *"
1339 .ascii "But this lives in the second text subsegment."
1341 .ascii "This lives in the data segment,"
1342 .ascii "in the first data subsegment."
1344 .ascii "This lives in the first text segment,"
1345 .ascii "immediately following the asterisk (*)."
1348 Each segment has a @dfn{location counter} incremented by one for every
1349 byte assembled into that segment. Because subsegments are merely a
1350 convenience restricted to @code{_AS__} there is no concept of a subsegment
1351 location counter. There is no way to directly manipulate a location
1352 counter---but the @code{.align} directive will change it, and any label
1353 definition will capture its current value. The location counter of the
1354 segment that statements are being assembled into is said to be the
1355 @dfn{active} location counter.
1357 @node bss, , Sub-Segments, Segments
1358 @section bss Segment
1359 The bss segment is used for local common variable storage.
1360 You may allocate address space in the bss segment, but you may
1361 not dictate data to load into it before your program executes. When
1362 your program starts running, all the contents of the bss
1363 segment are zeroed bytes.
1365 Addresses in the bss segment are allocated with special directives; you
1366 may not assemble anything directly into the bss segment. Hence there
1367 are no bss subsegments. @xref{Comm,,@code{.comm}},
1368 @pxref{Lcomm,,@code{.lcomm}}.
1370 @node Symbols, Expressions, Segments, Top
1372 Symbols are a central concept: the programmer uses symbols to name
1373 things, the linker uses symbols to link, and the debugger uses symbols
1377 @emph{Warning:} @code{_AS__} does not place symbols in the object file in
1378 the same order they were declared. This may break some debuggers.
1383 * Setting Symbols:: Giving Symbols Other Values
1384 * Symbol Names:: Symbol Names
1385 * Dot:: The Special Dot Symbol
1386 * Symbol Attributes:: Symbol Attributes
1389 @node Labels, Setting Symbols, Symbols, Symbols
1391 A @dfn{label} is written as a symbol immediately followed by a colon
1392 @samp{:}. The symbol then represents the current value of the
1393 active location counter, and is, for example, a suitable instruction
1394 operand. You are warned if you use the same symbol to represent two
1395 different locations: the first definition overrides any other
1398 @node Setting Symbols, Symbol Names, Labels, Symbols
1399 @section Giving Symbols Other Values
1400 A symbol can be given an arbitrary value by writing a symbol, followed
1401 by an equals sign @samp{=}, followed by an expression
1402 (@pxref{Expressions}). This is equivalent to using the @code{.set}
1403 directive. @xref{Set,,@code{.set}}.
1405 @node Symbol Names, Dot, Setting Symbols, Symbols
1406 @section Symbol Names
1407 Symbol names begin with a letter or with one of @samp{$._}. That
1408 character may be followed by any string of digits, letters,
1409 underscores and dollar signs. Case of letters is significant:
1410 @code{foo} is a different symbol name than @code{Foo}.
1413 For the AMD 29K family, @samp{?} is also allowed in the
1414 body of a symbol name, though not at its beginning.
1417 Each symbol has exactly one name. Each name in an assembly language
1418 program refers to exactly one symbol. You may use that symbol name any
1419 number of times in a program.
1421 @subheading Local Symbol Names
1423 Local symbols help compilers and programmers use names temporarily.
1424 There are ten local symbol names, which are re-used throughout the
1425 program. You may refer to them using the names @samp{0} @samp{1}
1426 @dots{} @samp{9}. To define a local symbol, write a label of the form
1427 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
1428 recent previous definition of that symbol write @samp{@b{N}b}, using the
1429 same digit as when you defined the label. To refer to the next
1430 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
1431 a choice of 10 forward references. The @samp{b} stands for
1432 ``backwards'' and the @samp{f} stands for ``forwards''.
1434 Local symbols are not emitted by the current GNU C compiler.
1436 There is no restriction on how you can use these labels, but
1437 remember that at any point in the assembly you can refer to at most
1438 10 prior local labels and to at most 10 forward local labels.
1440 Local symbol names are only a notation device. They are immediately
1441 transformed into more conventional symbol names before the assembler
1442 uses them. The symbol names stored in the symbol table, appearing in
1443 error messages and optionally emitted to the object file have these
1448 All local labels begin with @samp{L}. Normally both @code{_AS__} and
1449 @code{_LD__} forget symbols that start with @samp{L}. These labels are
1450 used for symbols you are never intended to see. If you give the
1451 @samp{-L} option then @code{_AS__} will retain these symbols in the
1452 object file. If you also instruct @code{_LD__} to retain these symbols,
1453 you may use them in debugging.
1456 If the label is written @samp{0:} then the digit is @samp{0}.
1457 If the label is written @samp{1:} then the digit is @samp{1}.
1458 And so on up through @samp{9:}.
1461 This unusual character is included so you don't accidentally invent
1462 a symbol of the same name. The character has ASCII value
1465 @item @emph{ordinal number}
1466 This is a serial number to keep the labels distinct. The first
1467 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
1468 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
1472 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
1473 @code{3:} is named @code{L3@ctrl{A}44}.
1475 @node Dot, Symbol Attributes, Symbol Names, Symbols
1476 @section The Special Dot Symbol
1478 The special symbol @samp{.} refers to the current address that
1479 @code{_AS__} is assembling into. Thus, the expression @samp{melvin:
1480 .long .} will cause @code{melvin} to contain its own address.
1481 Assigning a value to @code{.} is treated the same as a @code{.org}
1482 directive. Thus, the expression @samp{.=.+4} is the same as saying
1490 @node Symbol Attributes, , Dot, Symbols
1491 @section Symbol Attributes
1492 Every symbol has, as well as its name, the attributes ``Value'' and
1493 ``Type''. Depending on output format, symbols also have auxiliary attributes.
1495 The detailed definitions are in _0__<a.out.h>_1__.
1498 If you use a symbol without defining it, @code{_AS__} assumes zero for
1499 all these attributes, and probably won't warn you. This makes the
1500 symbol an externally defined symbol, which is generally what you
1504 * Symbol Value:: Value
1505 * Symbol Type:: Type
1506 _if__(_GENERIC__||!_BOUT__)
1507 * a.out Symbols:: Symbol Attributes: @code{a.out}
1508 _fi__(_GENERIC__||!_BOUT__)
1509 _if__(_BOUT__&&!_GENERIC__)
1510 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
1511 _fi__(_BOUT__&&!_GENERIC__)
1513 * COFF Symbols:: Symbol Attributes for COFF
1517 @node Symbol Value, Symbol Type, Symbol Attributes, Symbol Attributes
1519 The value of a symbol is (usually) 32 bits, the size of one GNU C
1520 @code{int}. For a symbol which labels a location in the text, data, bss
1521 or absolute segments the value is the number of addresses from the start
1522 of that segment to the label. Naturally for text, data and bss segments
1523 the value of a symbol changes as @code{_LD__} changes segment base
1524 addresses during linking. Absolute symbols' values do not change during
1525 linking: that is why they are called absolute.
1527 The value of an undefined symbol is treated in a special way. If it is
1528 0 then the symbol is not defined in this assembler source program, and
1529 @code{_LD__} will try to determine its value from other programs it is
1530 linked with. You make this kind of symbol simply by mentioning a symbol
1531 name without defining it. A non-zero value represents a @code{.comm}
1532 common declaration. The value is how much common storage to reserve, in
1533 bytes (addresses). The symbol refers to the first address of the
1536 @node Symbol Type, a.out Symbols, Symbol Value, Symbol Attributes
1538 The type attribute of a symbol contains relocation (segment)
1539 information, any flag settings indicating that a symbol is external, and
1540 (optionally), other information for linkers and debuggers. The exact
1541 format depends on the object-code output format in use.
1543 _if__(_AOUT__||_BOUT__)
1545 * Symbol Desc:: Descriptor
1546 * Symbol Other:: Other
1550 @node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes
1553 @node a.out Symbols, , Symbol Type, Symbol Attributes
1555 _if__(_BOUT__&&!_GENERIC__)
1556 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
1557 These symbol attributes appear only when @code{_AS__} is configured for
1558 one of the Berkeley-descended object output formats.
1559 _fi__(_BOUT__&&!_GENERIC__)
1560 _if__(_GENERIC__||!_BOUT__)
1561 @subsection Symbol Attributes: @code{a.out}
1562 _fi__(_GENERIC__||!_BOUT__)
1565 * Symbol Desc:: Descriptor
1566 * Symbol Other:: Other
1569 @node Symbol Desc, Symbol Other, a.out Symbols, a.out Symbols
1570 @subsubsection Descriptor
1571 This is an arbitrary 16-bit value. You may establish a symbol's
1572 descriptor value by using a @code{.desc} statement
1573 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
1576 @node Symbol Other, , Symbol Desc, a.out Symbols
1577 @subsubsection Other
1578 This is an arbitrary 8-bit value. It means nothing to @code{_AS__}.
1579 _fi__(_AOUT__||_BOUT__)
1582 @node COFF Symbols, , a.out Symbols, Symbol Attributes
1583 @subsection Symbol Attributes for COFF
1584 The COFF format supports a multitude of auxiliary symbol attributes;
1585 like the primary symbol attributes, they are set between @code{.def} and
1586 @code{.endef} directives.
1588 @subsubsection Primary Attributes
1589 The symbol name is set with @code{.def}; the value and type,
1590 respectively, with @code{.val} and @code{.type}.
1592 @subsubsection Auxiliary Attributes
1593 The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl},
1594 @code{.size}, and @code{.tag} can generate auxiliary symbol table
1595 information for COFF.
1598 @node Expressions, Pseudo Ops, Symbols, Top
1599 @chapter Expressions
1600 An @dfn{expression} specifies an address or numeric value.
1601 Whitespace may precede and/or follow an expression.
1604 * Empty Exprs:: Empty Expressions
1605 * Integer Exprs:: Integer Expressions
1608 @node Empty Exprs, Integer Exprs, Expressions, Expressions
1609 @section Empty Expressions
1610 An empty expression has no value: it is just whitespace or null.
1611 Wherever an absolute expression is required, you may omit the
1612 expression and @code{_AS__} will assume a value of (absolute) 0. This
1613 is compatible with other assemblers.
1615 @node Integer Exprs, , Empty Exprs, Expressions
1616 @section Integer Expressions
1617 An @dfn{integer expression} is one or more @emph{arguments} delimited
1618 by @emph{operators}.
1621 * Arguments:: Arguments
1622 * Operators:: Operators
1623 * Prefix Ops:: Prefix Operators
1624 * Infix Ops:: Infix Operators
1627 @node Arguments, Operators, Integer Exprs, Integer Exprs
1628 @subsection Arguments
1630 @dfn{Arguments} are symbols, numbers or subexpressions. In other
1631 contexts arguments are sometimes called ``arithmetic operands''. In
1632 this manual, to avoid confusing them with the ``instruction operands'' of
1633 the machine language, we use the term ``argument'' to refer to parts of
1634 expressions only, reserving the word ``operand'' to refer only to machine
1635 instruction operands.
1637 Symbols are evaluated to yield @{@var{segment} @var{NNN}@} where
1638 @var{segment} is one of text, data, bss, absolute,
1639 or undefined. @var{NNN} is a signed, 2's complement 32 bit
1642 Numbers are usually integers.
1644 A number can be a flonum or bignum. In this case, you are warned
1645 that only the low order 32 bits are used, and @code{_AS__} pretends
1646 these 32 bits are an integer. You may write integer-manipulating
1647 instructions that act on exotic constants, compatible with other
1650 Subexpressions are a left parenthesis @samp{(} followed by an integer
1651 expression, followed by a right parenthesis @samp{)}; or a prefix
1652 operator followed by an argument.
1654 @node Operators, Prefix Ops, Arguments, Integer Exprs
1655 @subsection Operators
1656 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
1657 operators are followed by an argument. Infix operators appear
1658 between their arguments. Operators may be preceded and/or followed by
1661 @node Prefix Ops, Infix Ops, Operators, Integer Exprs
1662 @subsection Prefix Operators
1663 @code{_AS__} has the following @dfn{prefix operators}. They each take
1664 one argument, which must be absolute.
1666 @c the tex/end tex stuff surrounding this small table is meant to make
1667 @c it align, on the printed page, with the similar table in the next
1668 @c section (which is inside an enumerate).
1670 \global\advance\leftskip by \itemindent
1675 @dfn{Negation}. Two's complement negation.
1677 @dfn{Complementation}. Bitwise not.
1681 \global\advance\leftskip by -\itemindent
1684 @node Infix Ops, , Prefix Ops, Integer Exprs
1685 @subsection Infix Operators
1687 @dfn{Infix operators} take two arguments, one on either side. Operators
1688 have precedence, but operations with equal precedence are performed left
1689 to right. Apart from @code{+} or @code{-}, both arguments must be
1690 absolute, and the result is absolute.
1698 @dfn{Multiplication}.
1700 @dfn{Division}. Truncation is the same as the C operator @samp{/}
1705 @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__}
1708 @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__}
1712 Intermediate precedence
1715 @dfn{Bitwise Inclusive Or}.
1719 @dfn{Bitwise Exclusive Or}.
1721 @dfn{Bitwise Or Not}.
1728 @dfn{Addition}. If either argument is absolute, the result
1729 has the segment of the other argument.
1730 If either argument is pass1 or undefined, the result is pass1.
1731 Otherwise @code{+} is illegal.
1733 @dfn{Subtraction}. If the right argument is absolute, the
1734 result has the segment of the left argument.
1735 If either argument is pass1 the result is pass1.
1736 If either argument is undefined the result is difference segment.
1737 If both arguments are in the same segment, the result is absolute---provided
1738 that segment is one of text, data or bss.
1739 Otherwise subtraction is illegal.
1743 The sense of the rule for addition is that it's only meaningful to add
1744 the @emph{offsets} in an address; you can only have a defined segment in
1745 one of the two arguments.
1747 Similarly, you can't subtract quantities from two different segments.
1749 @node Pseudo Ops, _MACH_DEP__, Expressions, Top
1750 @chapter Assembler Directives
1752 All assembler directives have names that begin with a period (@samp{.}).
1753 The rest of the name is letters: their case does not matter.
1755 This chapter discusses directives present regardless of the target
1756 machine configuration for the GNU assembler; @pxref{_MACH_DEP__} for
1757 additional directives.
1760 * Abort:: @code{.abort}
1762 * coff-ABORT:: @code{.ABORT}
1764 _if__(_BOUT__&&!_COFF__)
1765 * bout-ABORT:: @code{.ABORT}
1766 _fi__(_BOUT__&&!_COFF__)
1767 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
1768 * App-File:: @code{.app-file @var{string}}
1769 * Ascii:: @code{.ascii "@var{string}"}@dots{}
1770 * Asciz:: @code{.asciz "@var{string}"}@dots{}
1771 * Byte:: @code{.byte @var{expressions}}
1772 * Comm:: @code{.comm @var{symbol} , @var{length} }
1773 * Data:: @code{.data @var{subsegment}}
1774 _if__(_COFF__||_BOUT__)
1775 * Def:: @code{.def @var{name}}
1776 _fi__(_COFF__||_BOUT__)
1777 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
1778 _if__(_COFF__||_BOUT__)
1780 _fi__(_COFF__||_BOUT__)
1781 * Double:: @code{.double @var{flonums}}
1782 * Else:: @code{.else}
1783 _if__(_COFF__||_BOUT__)
1784 * Endef:: @code{.endef}
1785 _fi__(_COFF__||_BOUT__)
1786 * Endif:: @code{.endif}
1787 * Equ:: @code{.equ @var{symbol}, @var{expression}}
1788 * Extern:: @code{.extern}
1789 _if__(_GENERIC__||!_A29K__)
1790 * File:: @code{.app-file @var{string}}
1791 _fi__(_GENERIC__||!_A29K__)
1792 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
1793 * Float:: @code{.float @var{flonums}}
1794 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
1795 * hword:: @code{.hword @var{expressions}}
1796 * Ident:: @code{.ident}
1797 * If:: @code{.if @var{absolute expression}}
1798 * Include:: @code{.include "@var{file}"}
1799 * Int:: @code{.int @var{expressions}}
1800 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
1801 _if__(_GENERIC__||!_A29K__)
1802 * Line:: @code{.line @var{line-number}}
1803 _fi__(_GENERIC__||!_A29K__)
1804 * Ln:: @code{.ln @var{line-number}}
1805 * List:: @code{.list} and related directives
1806 * Long:: @code{.long @var{expressions}}
1807 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
1808 * Octa:: @code{.octa @var{bignums}}
1809 * Org:: @code{.org @var{new-lc} , @var{fill}}
1810 * Quad:: @code{.quad @var{bignums}}
1811 _if__(_COFF__||_BOUT__)
1812 * Scl:: @code{.scl @var{class}}
1813 _fi__(_COFF__||_BOUT__)
1814 * Set:: @code{.set @var{symbol}, @var{expression}}
1815 * Short:: @code{.short @var{expressions}}
1816 * Single:: @code{.single @var{flonums}}
1817 _if__(_COFF__||_BOUT__)
1818 * Size:: @code{.size}
1819 _fi__(_COFF__||_BOUT__)
1820 * Space:: @code{.space @var{size} , @var{fill}}
1821 * Stab:: @code{.stabd, .stabn, .stabs}
1822 _if__(_COFF__||_BOUT__)
1823 * Tag:: @code{.tag @var{structname}}
1824 _fi__(_COFF__||_BOUT__)
1825 * Text:: @code{.text @var{subsegment}}
1826 _if__(_COFF__||_BOUT__)
1827 * Type:: @code{.type @var{int}}
1828 * Val:: @code{.val @var{addr}}
1829 _fi__(_COFF__||_BOUT__)
1830 * Word:: @code{.word @var{expressions}}
1831 * Deprecated:: Deprecated Directives
1835 @node Abort, coff-ABORT, Pseudo Ops, Pseudo Ops
1837 _if__((!_COFF__) && _BOUT__)
1838 @node Abort, bout-ABORT, Pseudo Ops, Pseudo Ops
1839 _fi__((!_COFF__) && _BOUT__)
1840 _if__(! (_BOUT__ || _COFF__) )
1841 @node Abort, Align, Pseudo Ops, Pseudo Ops
1842 _fi__(! (_BOUT__ || _COFF__) )
1843 @section @code{.abort}
1844 This directive stops the assembly immediately. It is for
1845 compatibility with other assemblers. The original idea was that the
1846 assembly language source would be piped into the assembler. If the sender
1847 of the source quit, it could use this directive tells @code{_AS__} to
1848 quit also. One day @code{.abort} will not be supported.
1851 @node coff-ABORT, Align, Abort, Pseudo Ops
1852 @section @code{.ABORT}
1853 When producing COFF output, @code{_AS__} accepts this directive as a
1854 synonym for @samp{.abort}.
1859 @node bout-ABORT, Align, Abort, Pseudo Ops
1860 @section @code{.ABORT}
1863 When producing @code{b.out} output, @code{_AS__} accepts this directive,
1867 _if__( ! (_COFF__ || _BOUT__) )
1868 @node Align, App-File, Abort, Pseudo Ops
1869 _fi__( ! (_COFF__ || _BOUT__) )
1871 @node Align, App-File, coff-ABORT, Pseudo Ops
1873 _if__( _BOUT__ && (! _COFF__))
1874 @node Align, App-File, bout-ABORT, Pseudo Ops
1875 _fi__( _BOUT__ && (! _COFF__))
1876 @section @code{.align @var{abs-expr} , @var{abs-expr}}
1877 Pad the location counter (in the current subsegment) to a particular
1878 storage boundary. The first expression (which must be absolute) is the
1879 number of low-order zero bits the location counter will have after
1880 advancement. For example @samp{.align 3} will advance the location
1881 counter until it a multiple of 8. If the location counter is already a
1882 multiple of 8, no change is needed.
1884 The second expression (also absolute) gives the value to be stored in
1885 the padding bytes. It (and the comma) may be omitted. If it is
1886 omitted, the padding bytes are zero.
1888 @node App-File, Ascii, Align, Pseudo Ops
1889 @section @code{.app-file @var{string}}
1892 (which may also be spelled @samp{.file})
1894 tells @code{_AS__} that we are about to start a new
1895 logical file. @var{string} is the new file name. In general, the
1896 filename is recognized whether or not it is surrounded by quotes @samp{"};
1897 but if you wish to specify an empty file name is permitted,
1898 you must give the quotes--@code{""}. This statement may go away in
1899 future: it is only recognized to be compatible with old @code{_AS__}
1902 @node Ascii, Asciz, App-File, Pseudo Ops
1903 @section @code{.ascii "@var{string}"}@dots{}
1904 @code{.ascii} expects zero or more string literals (@pxref{Strings})
1905 separated by commas. It assembles each string (with no automatic
1906 trailing zero byte) into consecutive addresses.
1908 @node Asciz, Byte, Ascii, Pseudo Ops
1909 @section @code{.asciz "@var{string}"}@dots{}
1910 @code{.asciz} is just like @code{.ascii}, but each string is followed by
1911 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
1913 @node Byte, Comm, Asciz, Pseudo Ops
1914 @section @code{.byte @var{expressions}}
1916 @code{.byte} expects zero or more expressions, separated by commas.
1917 Each expression is assembled into the next byte.
1919 @node Comm, Data, Byte, Pseudo Ops
1920 @section @code{.comm @var{symbol} , @var{length} }
1921 @code{.comm} declares a named common area in the bss segment. Normally
1922 @code{_LD__} reserves memory addresses for it during linking, so no partial
1923 program defines the location of the symbol. Use @code{.comm} to tell
1924 @code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__}
1925 will allocate space for each @code{.comm} symbol that is at least as
1926 long as the longest @code{.comm} request in any of the partial programs
1927 linked. @var{length} is an absolute expression.
1929 _if__(_COFF__ || _BOUT__)
1930 @node Data, Def, Comm, Pseudo Ops
1931 _fi__(_COFF__ || _BOUT__)
1932 _if__(!(_COFF__ || _BOUT__) && _AOUT__)
1933 @node Data, Desc, Comm, Pseudo Ops
1934 _fi__(!(_COFF__ || _BOUT__) && _AOUT__)
1935 _if__(! (_COFF__ || _BOUT__ || _AOUT__) )
1936 @c Well, this *might* happen...
1937 @node Data, Double, Comm, Pseudo Ops
1938 _fi__(! (_COFF__ || _BOUT__ || _AOUT__) )
1939 @section @code{.data @var{subsegment}}
1940 @code{.data} tells @code{_AS__} to assemble the following statements onto the
1941 end of the data subsegment numbered @var{subsegment} (which is an
1942 absolute expression). If @var{subsegment} is omitted, it defaults
1945 _if__(_COFF__ || _BOUT__)
1946 _if__(_AOUT__ || _BOUT__)
1947 @node Def, Desc, Data, Pseudo Ops
1948 _fi__(_AOUT__ || _BOUT__)
1949 _if__(!(_AOUT__ || _BOUT__))
1950 @node Def, Dim, Data, Pseudo Ops
1951 _fi__(!(_AOUT__ || _BOUT__))
1952 @section @code{.def @var{name}}
1953 Begin defining debugging information for a symbol @var{name}; the
1954 definition extends until the @code{.endef} directive is encountered.
1957 This directive is only observed when @code{_AS__} is configured for COFF
1958 format output; when producing @code{b.out}, @samp{.def} is recognized,
1961 _fi__(_COFF__ || _BOUT__)
1963 _if__(_AOUT__||_BOUT__)
1964 _if__(_COFF__||_BOUT__)
1965 @node Desc, Dim, Def, Pseudo Ops
1966 _fi__(_COFF__||_BOUT__)
1967 _if__(!(_COFF__||_BOUT__))
1968 @node Desc, Double, Data, Pseudo Ops
1969 _fi__(!(_COFF__||_BOUT__))
1970 @section @code{.desc @var{symbol}, @var{abs-expression}}
1971 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
1972 to the low 16 bits of an absolute expression.
1975 The @samp{.desc} directive is not available when @code{_AS__} is
1976 configured for COFF output; it is only for @code{a.out} or @code{b.out}
1977 object format. For the sake of compatibility, @code{_AS__} will accept
1978 it, but produce no output, when configured for COFF.
1980 _fi__(_AOUT__||_BOUT__)
1982 _if__(_COFF__ || _BOUT__)
1983 _if__(_AOUT__ || _BOUT__)
1984 @node Dim, Double, Desc, Pseudo Ops
1985 _fi__(_AOUT__ || _BOUT__)
1986 _if__(!(_AOUT__ || _BOUT__))
1987 @node Dim, Double, Def, Pseudo Ops
1988 _fi__(!(_AOUT__ || _BOUT__))
1989 @section @code{.dim}
1990 This directive is generated by compilers to include auxiliary debugging
1991 information in the symbol table. It is only permitted inside
1992 @code{.def}/@code{.endef} pairs.
1995 @samp{.dim} is only meaningful when generating COFF format output; when
1996 @code{_AS__} is generating @code{b.out}, it accepts this directive but
1999 _fi__(_COFF__ || _BOUT__)
2001 _if__(_COFF__||_BOUT__)
2002 @node Double, Else, Dim, Pseudo Ops
2003 _fi__(_COFF__||_BOUT__)
2004 _if__(!(_COFF__||_BOUT__))
2005 @node Double, Else, Desc, Pseudo Ops
2006 _fi__(!(_COFF__||_BOUT__))
2007 @section @code{.double @var{flonums}}
2008 @code{.double} expects zero or more flonums, separated by commas. It
2009 assembles floating point numbers.
2011 The exact kind of floating point numbers emitted depends on how
2012 @code{_AS__} is configured. @xref{_MACH_DEP__}.
2014 _if__((!_GENERIC__) && (_A29K__ || _I960__))
2015 On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers
2017 _fi__((!_GENERIC__) && (_A29K__ || _I960__))
2019 _if__(_COFF__||_BOUT__)
2020 @node Else, Endef, Double, Pseudo Ops
2021 _fi__(_COFF__||_BOUT__)
2022 _if__(!(_COFF__||_BOUT__))
2023 @node Else, Endif, Double, Pseudo Ops
2024 _fi__(!(_COFF__||_BOUT__))
2025 @section @code{.else}
2026 @code{.else} is part of the @code{_AS__} support for conditional
2027 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2028 of code to be assembled if the condition for the preceding @code{.if}
2032 @node End, Endef, Else, Pseudo Ops
2033 @section @code{.end}
2034 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2035 meant to do something eventually (which is why it isn't documented here
2036 as "for compatibility with blah").
2039 _if__(_COFF__||_BOUT__)
2040 @node Endef, Endif, Else, Pseudo Ops
2041 @section @code{.endef}
2042 This directive flags the end of a symbol definition begun with
2046 @samp{.endef} is only meaningful when generating COFF format output; if
2047 @code{_AS__} is configured to generate @code{b.out}, it accepts this
2048 directive but ignores it.
2050 _fi__(_COFF__||_BOUT__)
2052 _if__(_COFF__||_BOUT__)
2053 @node Endif, Equ, Endef, Pseudo Ops
2054 _fi__(_COFF__||_BOUT__)
2055 _if__(!(_COFF__||_BOUT__))
2056 @node Endif, Equ, Else, Pseudo Ops
2057 _fi__(!(_COFF__||_BOUT__))
2058 @section @code{.endif}
2059 @code{.endif} is part of the @code{_AS__} support for conditional assembly;
2060 it marks the end of a block of code that is only assembled
2061 conditionally. @xref{If,,@code{.if}}.
2063 @node Equ, Extern, Endif, Pseudo Ops
2064 @section @code{.equ @var{symbol}, @var{expression}}
2066 This directive sets the value of @var{symbol} to @var{expression}.
2067 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2069 _if__(_GENERIC__||!_A29K__)
2070 @node Extern, File, Equ, Pseudo Ops
2071 _fi__(_GENERIC__||!_A29K__)
2072 _if__(_A29K__&&!_GENERIC__)
2073 @node Extern, Fill, Equ, Pseudo Ops
2074 _fi__(_A29K__&&!_GENERIC__)
2075 @section @code{.extern}
2076 @code{.extern} is accepted in the source program---for compatibility
2077 with other assemblers---but it is ignored. @code{_AS__} treats
2078 all undefined symbols as external.
2080 _if__(_GENERIC__||!_A29K__)
2081 @node File, Fill, Extern, Pseudo Ops
2082 @section @code{.app-file @var{string}}
2083 @code{.file} (which may also be spelled @samp{.app-file}) tells
2084 @code{_AS__} that we are about to start a new logical file.
2085 @var{string} is the new file name. In general, the filename is
2086 recognized whether or not it is surrounded by quotes @samp{"}; but if
2087 you wish to specify an empty file name, you must give the
2088 quotes--@code{""}. This statement may go away in future: it is only
2089 recognized to be compatible with old @code{_AS__} programs.
2091 In some configurations of @code{_AS__}, @code{.file} has already been
2092 removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}.
2094 _fi__(_GENERIC__||!_A29K__)
2096 _if__(_GENERIC__||!_A29K__)
2097 @node Fill, Float, File, Pseudo Ops
2098 _fi__(_GENERIC__||!_A29K__)
2099 _if__(_A29K__&&!_GENERIC__)
2100 @node Fill, Float, Extern, Pseudo Ops
2101 _fi__(_A29K__&&!_GENERIC__)
2102 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2103 @var{result}, @var{size} and @var{value} are absolute expressions.
2104 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2105 may be zero or more. @var{Size} may be zero or more, but if it is
2106 more than 8, then it is deemed to have the value 8, compatible with
2107 other people's assemblers. The contents of each @var{repeat} bytes
2108 is taken from an 8-byte number. The highest order 4 bytes are
2109 zero. The lowest order 4 bytes are @var{value} rendered in the
2110 byte-order of an integer on the computer @code{_AS__} is assembling for.
2111 Each @var{size} bytes in a repetition is taken from the lowest order
2112 @var{size} bytes of this number. Again, this bizarre behavior is
2113 compatible with other people's assemblers.
2115 @var{size} and @var{value} are optional.
2116 If the second comma and @var{value} are absent, @var{value} is
2117 assumed zero. If the first comma and following tokens are absent,
2118 @var{size} is assumed to be 1.
2120 @node Float, Global, Fill, Pseudo Ops
2121 @section @code{.float @var{flonums}}
2122 This directive assembles zero or more flonums, separated by commas. It
2123 has the same effect as @code{.single}.
2125 The exact kind of floating point numbers emitted depends on how
2126 @code{_AS__} is configured.
2129 _if__((!_GENERIC__) && (_A29K__ || _I960__))
2130 On the _HOST__ family, @code{.float} emits 32-bit floating point numbers
2132 _fi__((!_GENERIC__) && (_A29K__ || _I960__))
2134 @node Global, hword, Float, Pseudo Ops
2135 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2136 @code{.global} makes the symbol visible to @code{_LD__}. If you define
2137 @var{symbol} in your partial program, its value is made available to
2138 other partial programs that are linked with it. Otherwise,
2139 @var{symbol} will take its attributes from a symbol of the same name
2140 from another partial program it is linked with.
2143 @c FIXME BFD implications; this is different in COFF.
2144 This is done by setting the @code{N_EXT} bit of that symbol's type byte
2145 to 1. @xref{Symbol Attributes}.
2148 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2149 compatibility with other assemblers.
2151 _if__(_AOUT__||_BOUT__||_COFF__)
2152 @node hword, Ident, Global, Pseudo Ops
2153 _fi__(_AOUT__||_BOUT__||_COFF__)
2154 _if__(!(_AOUT__||_BOUT__||_COFF__))
2155 @node hword, If, Global, Pseudo Ops
2156 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2157 @section @code{.hword @var{expressions}}
2158 This expects zero or more @var{expressions}, and emits
2159 a 16 bit number for each.
2162 This directive is a synonym for @samp{.short}; depending on the target
2163 architecture, it may also be a synonym for @samp{.word}.
2165 _if__( (_A29K__ || _I960__) && !_GENERIC__ )
2166 This directive is a synonym for @samp{.short}.
2167 _fi__( (_A29K__ || _I960__) && !_GENERIC__ )
2169 _if__(_AOUT__||_BOUT__||_COFF__)
2170 @node Ident, If, hword, Pseudo Ops
2171 @section @code{.ident}
2172 This directive is used by some assemblers to place tags in object files.
2173 @code{_AS__} simply accepts the directive for source-file
2174 compatibility with such assemblers, but does not actually emit anything
2176 _fi__(_AOUT__||_BOUT__||_COFF__)
2178 _if__(_AOUT__||_BOUT__||_COFF__)
2179 @node If, Include, Ident, Pseudo Ops
2180 _fi__(_AOUT__||_BOUT__||_COFF__)
2181 _if__(!(_AOUT__||_BOUT__||_COFF__))
2182 @node If, Include, hword, Pseudo Ops
2183 _fi__(!(_AOUT__||_BOUT__||_COFF__))
2184 @section @code{.if @var{absolute expression}}
2185 @code{.if} marks the beginning of a section of code which is only
2186 considered part of the source program being assembled if the argument
2187 (which must be an @var{absolute expression}) is non-zero. The end of
2188 the conditional section of code must be marked by @code{.endif}
2189 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
2190 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
2192 The following variants of @code{.if} are also supported:
2194 @item ifdef @var{symbol}
2195 Assembles the following section of code if the specified @var{symbol}
2200 Not yet implemented.
2203 @item ifndef @var{symbol}
2204 @itemx ifnotdef @var{symbol}
2205 Assembles the following section of code if the specified @var{symbol}
2206 has not been defined. Both spelling variants are equivalent.
2210 Not yet implemented.
2214 @node Include, Int, If, Pseudo Ops
2215 @section @code{.include "@var{file}"}
2216 This directive provides a way to include supporting files at specified
2217 points in your source program. The code from @var{file} is assembled as
2218 if it followed the point of the @code{.include}; when the end of the
2219 included file is reached, assembly of the original file continues. You
2220 can control the search paths used with the @samp{-I} command-line option
2221 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
2224 @node Int, Lcomm, Include, Pseudo Ops
2225 @section @code{.int @var{expressions}}
2226 Expect zero or more @var{expressions}, of any segment, separated by
2227 commas. For each expression, emit a 32-bit number that will, at run
2228 time, be the value of that expression. The byte order of the
2229 expression depends on what kind of computer will run the program.
2231 _if__(_GENERIC__||(!_A29K__))
2232 @node Lcomm, Line, Int, Pseudo Ops
2233 _fi__(_GENERIC__||(!_A29K__))
2234 _if__((!_GENERIC__)&& _A29K__)
2235 @node Lcomm, Ln, Int, Pseudo Ops
2236 _fi__((!_GENERIC__)&& _A29K__)
2237 @section @code{.lcomm @var{symbol} , @var{length}}
2238 Reserve @var{length} (an absolute expression) bytes for a local common
2239 denoted by @var{symbol}. The segment and value of @var{symbol} are
2240 those of the new local common. The addresses are allocated in the bss
2241 segment, so at run-time the bytes will start off zeroed. @var{Symbol}
2242 is not declared global (@pxref{Global,,@code{.global}}), so is normally
2243 not visible to @code{_LD__}.
2245 _if__(_GENERIC__ || !_A29K__)
2246 @node Line, Ln, Lcomm, Pseudo Ops
2247 @section @code{.line @var{line-number}}
2248 _fi__(_GENERIC__ || (!_A29K__))
2249 _if__(_A29K__ && (!_GENERIC__))
2250 @node Ln, List, Lcomm, Pseudo Ops
2251 @section @code{.ln @var{line-number}}
2252 _fi__(_A29K__ && (!_GENERIC__))
2253 _if__(_AOUT__||_BOUT__)
2254 Tell @code{_AS__} to change the logical line number. @var{line-number} must be
2255 an absolute expression. The next line will have that logical line
2256 number. So any other statements on the current line (after a statement
2258 _if__(_A29K__&&(!_GENERIC__))
2260 _fi__(_A29K__&&(!_GENERIC__))
2261 _if__(_GENERIC__ || (!_A29K__))
2263 _fi__(_GENERIC__ || (!_A29K__))
2264 will be reported as on logical line number
2265 @var{line-number} @minus{} 1.
2266 One day this directive will be unsupported: it is used only
2267 for compatibility with existing assembler programs. @refill
2269 _if__(_GENERIC__ && _A29K__)
2270 @emph{Warning:} In the AMD29K configuration of _AS__, this command is
2271 only available with the name @code{.ln}, rather than as either
2272 @code{.line} or @code{.ln}. (Also, in that configuration the line
2273 separator character is @samp{@@}).
2274 _fi__(_GENERIC__ && _A29K__)
2275 _fi__(_AOUT__||_BOUT__)
2278 Even though this is a directive associated with the @code{a.out} or
2279 @code{b.out} object-code formats, @code{_AS__} will still recognize it
2280 when producing COFF output, and will treat @samp{.line} as though it
2281 were the COFF @samp{.ln} @emph{if} it is found outside a
2282 @code{.def}/@code{.endef} pair.
2284 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
2285 used by compilers to generate auxiliary symbol information for
2289 _if__(_AOUT__&&(_GENERIC__||!_A29K__))
2290 @node Ln, List, Line, Pseudo Ops
2291 @section @code{.ln @var{line-number}}
2292 @samp{.ln} is a synonym for @samp{.line}.
2293 _fi__(_AOUT__&&(_GENERIC__||!_A29K__))
2294 _if__(_COFF__&&!_AOUT__)
2295 @node Ln, List, Line, Pseudo Ops
2296 @section @code{.ln @var{line-number}}
2297 Tell @code{_AS__} to change the logical line number. @var{line-number}
2298 must be an absolute expression. The next line will have that logical
2299 line number, so any other statements on the current line (after a
2300 statement separator character @code{;}) will be reported as on logical
2301 line number @var{line-number} @minus{} 1.
2304 This directive is accepted, but ignored, when @code{_AS__} is configured for
2305 @code{b.out}; its effect is only associated with COFF output format.
2307 _fi__(_COFF__&&!_AOUT__)
2309 @node List, Long, Ln, Pseudo Ops
2310 @section @code{.list} and related directives
2311 @code{_AS__} ignores the directives @code{.list}, @code{.nolist},
2312 @code{.eject}, @code{.lflags}, @code{.title}, @code{.sbttl}; however,
2313 they're accepted for compatibility with assemblers that use them.
2315 @node Long, Lsym, List, Pseudo Ops
2316 @section @code{.long @var{expressions}}
2317 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
2319 @node Lsym, Octa, Long, Pseudo Ops
2320 @section @code{.lsym @var{symbol}, @var{expression}}
2321 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
2322 the hash table, ensuring it cannot be referenced by name during the
2323 rest of the assembly. This sets the attributes of the symbol to be
2324 the same as the expression value:
2326 @var{other} = @var{descriptor} = 0
2327 @var{type} = @r{(segment of @var{expression})}
2328 @var{value} = @var{expression}
2331 The new symbol is not flagged as external.
2333 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
2334 @node Octa, Org, Lsym, Pseudo Ops
2335 @section @code{.octa @var{bignums}}
2336 This directive expects zero or more bignums, separated by commas. For each
2337 bignum, it emits a 16-byte integer.
2339 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
2340 hence @emph{octa}-word for 16 bytes.
2342 @node Org, Quad, Octa, Pseudo Ops
2343 @section @code{.org @var{new-lc} , @var{fill}}
2345 @code{.org} will advance the location counter of the current segment to
2346 @var{new-lc}. @var{new-lc} is either an absolute expression or an
2347 expression with the same segment as the current subsegment. That is,
2348 you can't use @code{.org} to cross segments: if @var{new-lc} has the
2349 wrong segment, the @code{.org} directive is ignored. To be compatible
2350 with former assemblers, if the segment of @var{new-lc} is absolute,
2351 @code{_AS__} will issue a warning, then pretend the segment of @var{new-lc}
2352 is the same as the current subsegment.
2354 @code{.org} may only increase the location counter, or leave it
2355 unchanged; you cannot use @code{.org} to move the location counter
2358 @c double negative used below "not undefined" because this is a specific
2359 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
2360 @c segment. pesch@cygnus.com 18feb91
2361 Because @code{_AS__} tries to assemble programs in one pass @var{new-lc}
2362 may not be undefined. If you really detest this restriction we eagerly await
2363 a chance to share your improved assembler.
2365 Beware that the origin is relative to the start of the segment, not
2366 to the start of the subsegment. This is compatible with other
2367 people's assemblers.
2369 When the location counter (of the current subsegment) is advanced, the
2370 intervening bytes are filled with @var{fill} which should be an
2371 absolute expression. If the comma and @var{fill} are omitted,
2372 @var{fill} defaults to zero.
2374 _if__(_COFF__||_BOUT__)
2375 @node Quad, Scl, Org, Pseudo Ops
2376 _fi__(_COFF__||_BOUT__)
2377 _if__(!(_COFF__||_BOUT__))
2378 @node Quad, Set, Org, Pseudo Ops
2379 _fi__(!(_COFF__||_BOUT__))
2380 @section @code{.quad @var{bignums}}
2381 @code{.quad} expects zero or more bignums, separated by commas. For
2382 each bignum, it emits
2383 _if__(_GENERIC__||(!_I960__))
2384 an 8-byte integer. If the bignum won't fit in 8
2385 bytes, it prints a warning message; and just takes the lowest order 8
2386 bytes of the bignum.@refill
2388 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
2389 hence @emph{quad}-word for 8 bytes.
2390 _fi__(_GENERIC__||(!_I960__))
2391 _if__(_I960__&&(!_GENERIC__))
2392 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
2393 warning message; and just takes the lowest order 16 bytes of the
2395 _fi__(_I960__&&(!_GENERIC__))
2397 _if__(_COFF__||_BOUT__)
2398 @node Scl, Set, Quad, Pseudo Ops
2399 @section @code{.scl @var{class}}
2400 Set the storage-class value for a symbol. This directive may only be
2401 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
2402 whether a symbol is static or external, or it may record further
2403 symbolic debugging information.
2406 The @samp{.scl} directive is primarily associated with COFF output; when
2407 configured to generate @code{b.out} output format, @code{_AS__} will
2408 accept this directive but ignore it.
2410 _fi__(_COFF__||_BOUT__)
2413 _if__(_COFF__||_BOUT__)
2414 @node Set, Short, Scl, Pseudo Ops
2415 _fi__(_COFF__||_BOUT__)
2416 _if__(!(_COFF__||_BOUT__))
2417 @node Set, Short, Quad, Pseudo Ops
2418 _fi__(!(_COFF__||_BOUT__))
2419 @section @code{.set @var{symbol}, @var{expression}}
2421 This directive sets the value of @var{symbol} to @var{expression}. This
2422 will change @var{symbol}'s value and type to conform to
2423 @var{expression}. If @var{symbol} was flagged as external, it remains
2424 flagged. (@xref{Symbol Attributes}.)
2426 You may @code{.set} a symbol many times in the same assembly.
2427 If the expression's segment is unknowable during pass 1, a second
2428 pass over the source program will be forced. The second pass is
2429 currently not implemented. @code{_AS__} will abort with an error
2430 message if one is required.
2432 If you @code{.set} a global symbol, the value stored in the object
2433 file is the last value stored into it.
2435 @node Short, Single, Set, Pseudo Ops
2436 @section @code{.short @var{expressions}}
2437 _if__(_GENERIC__ || !(_SPARC__ || _A29K__ || _I960__))
2438 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
2439 _if__(_SPARC__ || _A29K__ || _I960__)
2440 In some configurations, however, @code{.short} and @code{.word} generate
2441 numbers of different lengths; @pxref{_MACH_DEP__}.
2442 _fi__(_SPARC__ || _A29K__ || _I960__)
2443 _fi__(_GENERIC__|| !(_SPARC__ || _A29K__ || _I960__))
2444 _if__((!_GENERIC__) && (_SPARC__ || _A29K__ || _I960__))
2445 This expects zero or more @var{expressions}, and emits
2446 a 16 bit number for each.
2447 _fi__((!_GENERIC__) && (_SPARC__ || _A29K__ || _I960__))
2448 _if__(_COFF__||_BOUT__)
2449 @node Single, Size, Short, Pseudo Ops
2450 _fi__(_COFF__||_BOUT__)
2451 _if__(!(_COFF__||_BOUT__))
2452 @node Single, Space, Short, Pseudo Ops
2453 _fi__(!(_COFF__||_BOUT__))
2454 @section @code{.single @var{flonums}}
2455 This directive assembles zero or more flonums, separated by commas. It
2456 has the same effect as @code{.float}.
2458 The exact kind of floating point numbers emitted depends on how
2459 @code{_AS__} is configured. @xref{_MACH_DEP__}.
2461 _if__((!_GENERIC__) && (_A29K__ || _I960__ || _SPARC__))
2462 On the _HOST__ family, @code{.single} emits 32-bit floating point
2463 numbers in IEEE format.
2464 _fi__((!_GENERIC__) && (_A29K__ || _I960__ || _SPARC__))
2466 _if__(_COFF__||_BOUT__)
2467 @node Size, Space, Single, Pseudo Ops
2468 @section @code{.size}
2469 This directive is generated by compilers to include auxiliary debugging
2470 information in the symbol table. It is only permitted inside
2471 @code{.def}/@code{.endef} pairs.
2474 @samp{.size} is only meaningful when generating COFF format output; when
2475 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2478 _fi__(_COFF__||_BOUT__)
2480 _if__(_COFF__||_BOUT__)
2481 @node Space, Stab, Size, Pseudo Ops
2482 _fi__(_COFF__||_BOUT__)
2483 _if__(!(_COFF__||_BOUT__))
2484 @node Space, Stab, Single, Pseudo Ops
2485 _fi__(!(_COFF__||_BOUT__))
2486 _if__(_GENERIC__ || !_A29K__)
2487 @section @code{.space @var{size} , @var{fill}}
2488 This directive emits @var{size} bytes, each of value @var{fill}. Both
2489 @var{size} and @var{fill} are absolute expressions. If the comma
2490 and @var{fill} are omitted, @var{fill} is assumed to be zero.
2491 _fi__(_GENERIC__ || !_A29K__)
2494 On the AMD 29K, this directive is ignored; it is accepted for
2495 compatibility with other AMD 29K assemblers.
2498 @emph{Warning:} In other versions of the GNU assembler, the directive
2499 @code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}.
2503 _if__(_AOUT__||_BOUT__||_COFF__)
2504 _if__(_COFF__||_BOUT__)
2505 @node Stab, Tag, Space, Pseudo Ops
2506 _fi__(_COFF__||_BOUT__)
2507 _if__(!(_COFF__||_BOUT__))
2508 @node Stab, Text, Space, Pseudo Ops
2509 _fi__(!(_COFF__||_BOUT__))
2510 @section @code{.stabd, .stabn, .stabs}
2511 There are three directives that begin @samp{.stab}.
2512 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
2513 The symbols are not entered in the @code{_AS__} hash table: they
2514 cannot be referenced elsewhere in the source file.
2515 Up to five fields are required:
2518 This is the symbol's name. It may contain any character except @samp{\000},
2519 so is more general than ordinary symbol names. Some debuggers used to
2520 code arbitrarily complex structures into symbol names using this field.
2522 An absolute expression. The symbol's type is set to the low 8
2523 bits of this expression.
2524 Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on
2527 An absolute expression.
2528 The symbol's ``other'' attribute is set to the low 8 bits of this expression.
2530 An absolute expression.
2531 The symbol's descriptor is set to the low 16 bits of this expression.
2533 An absolute expression which becomes the symbol's value.
2536 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
2537 or @code{.stabs} statement, the symbol has probably already been created
2538 and you will get a half-formed symbol in your object file. This is
2539 compatible with earlier assemblers!
2542 @item .stabd @var{type} , @var{other} , @var{desc}
2544 The ``name'' of the symbol generated is not even an empty string.
2545 It is a null pointer, for compatibility. Older assemblers used a
2546 null pointer so they didn't waste space in object files with empty
2549 The symbol's value is set to the location counter,
2550 relocatably. When your program is linked, the value of this symbol
2551 will be where the location counter was when the @code{.stabd} was
2554 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
2556 The name of the symbol is set to the empty string @code{""}.
2558 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
2560 All five fields are specified.
2562 _fi__(_AOUT__||_BOUT__||_COFF__)
2564 _if__(_COFF__||_BOUT__)
2565 @node Tag, Text, Stab, Pseudo Ops
2566 @section @code{.tag @var{structname}}
2567 This directive is generated by compilers to include auxiliary debugging
2568 information in the symbol table. It is only permitted inside
2569 @code{.def}/@code{.endef} pairs. Tags are used to link structure
2570 definitions in the symbol table with instances of those structures.
2573 @samp{.tag} is only used when generating COFF format output; when
2574 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2577 _fi__(_COFF__||_BOUT__)
2579 _if__(_COFF__||_BOUT__)
2580 @node Text, Type, Tag, Pseudo Ops
2581 _fi__(_COFF__||_BOUT__)
2582 _if__(!(_COFF__||_BOUT__))
2583 @node Text, Word, Stab, Pseudo Ops
2584 _fi__(!(_COFF__||_BOUT__))
2585 @section @code{.text @var{subsegment}}
2586 Tells @code{_AS__} to assemble the following statements onto the end of
2587 the text subsegment numbered @var{subsegment}, which is an absolute
2588 expression. If @var{subsegment} is omitted, subsegment number zero
2591 _if__(_COFF__||_BOUT__)
2592 @node Type, Val, Text, Pseudo Ops
2593 @section @code{.type @var{int}}
2594 This directive, permitted only within @code{.def}/@code{.endef} pairs,
2595 records the integer @var{int} as the type attribute of a symbol table entry.
2598 @samp{.type} is associated only with COFF format output; when
2599 @code{_AS__} is configured for @code{b.out} output, it accepts this
2600 directive but ignores it.
2602 _fi__(_COFF__||_BOUT__)
2604 _if__(_COFF__||_BOUT__)
2605 @node Val, Word, Type, Pseudo Ops
2606 @section @code{.val @var{addr}}
2607 This directive, permitted only within @code{.def}/@code{.endef} pairs,
2608 records the address @var{addr} as the value attribute of a symbol table
2612 @samp{.val} is used only for COFF output; when @code{_AS__} is
2613 configured for @code{b.out}, it accepts this directive but ignores it.
2615 _fi__(_COFF__||_BOUT__)
2617 _if__(_COFF__||_BOUT__)
2618 @node Word, Deprecated, Val, Pseudo Ops
2619 _fi__(_COFF__||_BOUT__)
2620 _if__(!(_COFF__||_BOUT__))
2621 @node Word, Deprecated, Text, Pseudo Ops
2622 _fi__(!(_COFF__||_BOUT__))
2623 @section @code{.word @var{expressions}}
2624 This directive expects zero or more @var{expressions}, of any segment,
2625 separated by commas.
2626 _if__((!_GENERIC__) && (_SPARC__ || _A29K__ || _I960__))
2627 For each expression, @code{_AS__} emits a 32-bit number.
2628 _fi__((!_GENERIC__) && (_SPARC__ || _A29K__ || _I960__))
2629 _if__((!_GENERIC__) && (! (_SPARC__ || _A29K__ || _I960__) ))
2630 For each expression, @code{_AS__} emits a 16-bit number.
2631 _fi__((!_GENERIC__) && (! (_SPARC__ || _A29K__ || _I960__) ))
2634 The size of the number emitted, and its byte order,
2635 depends on what kind of computer will run the program.
2638 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
2639 @c happen---32-bit addressability, period; no long/short jumps.
2640 _if__(_GENERIC__ || (! (_A29K__ || _I960__) ))
2642 @emph{Warning: Special Treatment to support Compilers}
2646 Machines that do less than 32-bit addressing require the following
2647 special treatment. If the machine of interest to you does 32-bit
2648 addressing (@pxref{_MACH_DEP__}), you can ignore this issue.
2651 In order to assemble compiler output into something that will work,
2652 @code{_AS__} will occasionlly do strange things to @samp{.word} directives.
2653 Directives of the form @samp{.word sym1-sym2} are often emitted by
2654 compilers as part of jump tables. Therefore, when @code{_AS__} assembles a
2655 directive of the form @samp{.word sym1-sym2}, and the difference between
2656 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will
2657 create a @dfn{secondary jump table}, immediately before the next label.
2658 This @var{secondary jump table} will be preceded by a short-jump to the
2659 first byte after the secondary table. This short-jump prevents the flow
2660 of control from accidentally falling into the new table. Inside the
2661 table will be a long-jump to @code{sym2}. The original @samp{.word}
2662 will contain @code{sym1} minus the address of the long-jump to
2665 If there were several occurrences of @samp{.word sym1-sym2} before the
2666 secondary jump table, all of them will be adjusted. If there was a
2667 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
2668 long-jump to @code{sym4} will be included in the secondary jump table,
2669 and the @code{.word} directives will be adjusted to contain @code{sym3}
2670 minus the address of the long-jump to @code{sym4}; and so on, for as many
2671 entries in the original jump table as necessary.
2674 @emph{This feature may be disabled by compiling @code{_AS__} with the
2675 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
2676 assembly language programmers.
2678 _fi__(_GENERIC__ || (! (_A29K__ || _I960__) ))
2680 @node Deprecated, , Word, Pseudo Ops
2681 @section Deprecated Directives
2682 One day these directives won't work.
2683 They are included for compatibility with older assemblers.
2690 @node _MACH_DEP__, License, Pseudo Ops, Top
2692 @chapter Machine Dependent Features
2695 * Vax-Dependent:: VAX Dependent Features
2698 * AMD29K-Dependent:: AMD 29K Dependent Features
2701 * i960-Dependent:: Intel 80960 Dependent Features
2704 * M68K-Dependent:: M680x0 Dependent Features
2707 * Sparc-Dependent:: SPARC Dependent Features
2710 * i386-Dependent:: 80386 Dependent Features
2717 @node Vax-Dependent, AMD29K-Dependent, Machine Dependent, Machine Dependent
2719 _CHAPSEC__(0+_GENERIC__) VAX Dependent Features
2721 * Vax-Opts:: VAX Command-Line Options
2722 * VAX-float:: VAX Floating Point
2723 * VAX-directives:: Vax Machine Directives
2724 * VAX-opcodes:: VAX Opcodes
2725 * VAX-branch:: VAX Branch Improvement
2726 * VAX-operands:: VAX Operands
2727 * VAX-no:: Not Supported on VAX
2730 @node Vax-Opts, VAX-float, Vax-Dependent, Vax-Dependent
2731 _CHAPSEC__(1+_GENERIC__) VAX Command-Line Options
2733 The Vax version of @code{_AS__} accepts any of the following options,
2734 gives a warning message that the option was ignored and proceeds.
2735 These options are for compatibility with scripts designed for other
2736 people's assemblers.
2739 @item @kbd{-D} (Debug)
2740 @itemx @kbd{-S} (Symbol Table)
2741 @itemx @kbd{-T} (Token Trace)
2742 These are obsolete options used to debug old assemblers.
2744 @item @kbd{-d} (Displacement size for JUMPs)
2745 This option expects a number following the @kbd{-d}. Like options
2746 that expect filenames, the number may immediately follow the
2747 @kbd{-d} (old standard) or constitute the whole of the command line
2748 argument that follows @kbd{-d} (GNU standard).
2750 @item @kbd{-V} (Virtualize Interpass Temporary File)
2751 Some other assemblers use a temporary file. This option
2752 commanded them to keep the information in active memory rather
2753 than in a disk file. @code{_AS__} always does this, so this
2754 option is redundant.
2756 @item @kbd{-J} (JUMPify Longer Branches)
2757 Many 32-bit computers permit a variety of branch instructions
2758 to do the same job. Some of these instructions are short (and
2759 fast) but have a limited range; others are long (and slow) but
2760 can branch anywhere in virtual memory. Often there are 3
2761 flavors of branch: short, medium and long. Some other
2762 assemblers would emit short and medium branches, unless told by
2763 this option to emit short and long branches.
2765 @item @kbd{-t} (Temporary File Directory)
2766 Some other assemblers may use a temporary file, and this option
2767 takes a filename being the directory to site the temporary
2768 file. @code{_AS__} does not use a temporary disk file, so this
2769 option makes no difference. @kbd{-t} needs exactly one
2773 The Vax version of the assembler accepts two options when
2774 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
2775 @kbd{-h} option prevents @code{_AS__} from modifying the
2776 symbol-table entries for symbols that contain lowercase
2777 characters (I think). The @kbd{-+} option causes @code{_AS__} to
2778 print warning messages if the FILENAME part of the object file,
2779 or any symbol name is larger than 31 characters. The @kbd{-+}
2780 option also insertes some code following the @samp{_main}
2781 symbol so that the object file will be compatible with Vax-11
2784 @node VAX-float, VAX-directives, Vax-Opts, Vax-Dependent
2785 _CHAPSEC__(1+_GENERIC__) VAX Floating Point
2786 Conversion of flonums to floating point is correct, and
2787 compatible with previous assemblers. Rounding is
2788 towards zero if the remainder is exactly half the least significant bit.
2790 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
2793 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
2794 are rendered correctly. Again, rounding is towards zero in the
2797 The @code{.float} directive produces @code{f} format numbers.
2798 The @code{.double} directive produces @code{d} format numbers.
2800 @node VAX-directives, VAX-opcodes, VAX-float, Vax-Dependent
2801 _CHAPSEC__(1+_GENERIC__) Vax Machine Directives
2802 The Vax version of the assembler supports four directives for
2803 generating Vax floating point constants. They are described in the
2808 This expects zero or more flonums, separated by commas, and
2809 assembles Vax @code{d} format 64-bit floating point constants.
2812 This expects zero or more flonums, separated by commas, and
2813 assembles Vax @code{f} format 32-bit floating point constants.
2816 This expects zero or more flonums, separated by commas, and
2817 assembles Vax @code{g} format 64-bit floating point constants.
2820 This expects zero or more flonums, separated by commas, and
2821 assembles Vax @code{h} format 128-bit floating point constants.
2825 @node VAX-opcodes, VAX-branch, VAX-directives, Vax-Dependent
2826 _CHAPSEC__(1+_GENERIC__) VAX Opcodes
2827 All DEC mnemonics are supported. Beware that @code{case@dots{}}
2828 instructions have exactly 3 operands. The dispatch table that
2829 follows the @code{case@dots{}} instruction should be made with
2830 @code{.word} statements. This is compatible with all unix
2831 assemblers we know of.
2833 @node VAX-branch, VAX-operands, VAX-opcodes, Vax-Dependent
2834 _CHAPSEC__(1+_GENERIC__) VAX Branch Improvement
2835 Certain pseudo opcodes are permitted. They are for branch
2836 instructions. They expand to the shortest branch instruction that
2837 will reach the target. Generally these mnemonics are made by
2838 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
2839 This feature is included both for compatibility and to help
2840 compilers. If you don't need this feature, don't use these
2841 opcodes. Here are the mnemonics, and the code they can expand into.
2845 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
2847 @item (byte displacement)
2849 @item (word displacement)
2851 @item (long displacement)
2856 Unconditional branch.
2858 @item (byte displacement)
2860 @item (word displacement)
2862 @item (long displacement)
2866 @var{COND} may be any one of the conditional branches
2867 @code{neq nequ eql eqlu gtr geq lss gtru lequ vc vs gequ cc lssu cs}.
2868 @var{COND} may also be one of the bit tests
2869 @code{bs bc bss bcs bsc bcc bssi bcci lbs lbc}.
2870 @var{NOTCOND} is the opposite condition to @var{COND}.
2872 @item (byte displacement)
2873 @kbd{b@var{COND} @dots{}}
2874 @item (word displacement)
2875 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
2876 @item (long displacement)
2877 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
2880 @var{X} may be one of @code{b d f g h l w}.
2882 @item (word displacement)
2883 @kbd{@var{OPCODE} @dots{}}
2884 @item (long displacement)
2886 @var{OPCODE} @dots{}, foo ;
2893 @var{YYY} may be one of @code{lss leq}.
2895 @var{ZZZ} may be one of @code{geq gtr}.
2897 @item (byte displacement)
2898 @kbd{@var{OPCODE} @dots{}}
2899 @item (word displacement)
2901 @var{OPCODE} @dots{}, foo ;
2903 foo: brw @var{destination} ;
2906 @item (long displacement)
2908 @var{OPCODE} @dots{}, foo ;
2910 foo: jmp @var{destination} ;
2919 @item (byte displacement)
2920 @kbd{@var{OPCODE} @dots{}}
2921 @item (word displacement)
2923 @var{OPCODE} @dots{}, foo ;
2925 foo: brw @var{destination} ;
2928 @item (long displacement)
2930 @var{OPCODE} @dots{}, foo ;
2932 foo: jmp @var{destination} ;
2938 @node VAX-operands, VAX-no, VAX-branch, Vax-Dependent
2939 _CHAPSEC__(1+_GENERIC__) VAX Operands
2940 The immediate character is @samp{$} for Unix compatibility, not
2941 @samp{#} as DEC writes it.
2943 The indirect character is @samp{*} for Unix compatibility, not
2944 @samp{@@} as DEC writes it.
2946 The displacement sizing character is @samp{`} (an accent grave) for
2947 Unix compatibility, not @samp{^} as DEC writes it. The letter
2948 preceding @samp{`} may have either case. @samp{G} is not
2949 understood, but all other letters (@code{b i l s w}) are understood.
2951 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
2952 pc}. Any case of letters will do.
2959 Any expression is permitted in an operand. Operands are comma
2962 @c There is some bug to do with recognizing expressions
2963 @c in operands, but I forget what it is. It is
2964 @c a syntax clash because () is used as an address mode
2965 @c and to encapsulate sub-expressions.
2967 @node VAX-no, , VAX-operands, Vax-Dependent
2968 _CHAPSEC__(1+_GENERIC__) Not Supported on VAX
2969 Vax bit fields can not be assembled with @code{_AS__}. Someone
2970 can add the required code if they really need it.
2975 @node AMD29K-Dependent, i960-Dependent, Vax-Dependent, Machine Dependent
2977 _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features
2979 * AMD29K Options:: Options
2980 * AMD29K Syntax:: Syntax
2981 * AMD29K Floating Point:: Floating Point
2982 * AMD29K Directives:: AMD 29K Machine Directives
2983 * AMD29K Opcodes:: Opcodes
2986 @node AMD29K Options, AMD29K Syntax, AMD29K-Dependent, AMD29K-Dependent
2987 _CHAPSEC__(1+_GENERIC__) Options
2988 @code{_AS__} has no additional command-line options for the AMD
2991 @node AMD29K Syntax, AMD29K Floating Point, AMD29K Options, AMD29K-Dependent
2992 _CHAPSEC__(1+_GENERIC__) Syntax
2994 * AMD29K-Chars:: Special Characters
2995 * AMD29K-Regs:: Register Names
2998 @node AMD29K-Chars, AMD29K-Regs, AMD29K Syntax, AMD29K Syntax
2999 _CHAPSEC__(2+_GENERIC__) Special Characters
3000 @samp{;} is the line comment character.
3002 @samp{@@} can be used instead of a newline to separate statements.
3004 The character @samp{?} is permitted in identifiers (but may not begin
3007 @node AMD29K-Regs, , AMD29K-Chars, AMD29K Syntax
3008 _CHAPSEC__(2+_GENERIC__) Register Names
3009 General-purpose registers are represented by predefined symbols of the
3010 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
3011 (for local registers), where @var{nnn} represents a number between
3012 @code{0} and @code{127}, written with no leading zeros. The leading
3013 letters may be in either upper or lower case; for example, @samp{gr13}
3014 and @samp{LR7} are both valid register names.
3016 You may also refer to general-purpose registers by specifying the
3017 register number as the result of an expression (prefixed with @samp{%%}
3018 to flag the expression as a register number):
3023 ---where @var{expression} must be an absolute expression evaluating to a
3024 number between @code{0} and @code{255}. The range [0, 127] refers to
3025 global registers, and the range [128, 255] to local registers.
3027 In addition, @code{_AS__} understands the following protected
3028 special-purpose register names for the AMD 29K family:
3038 These unprotected special-purpose register names are also recognized:
3046 @node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, AMD29K-Dependent
3047 _CHAPSEC__(1+_GENERIC__) Floating Point
3048 The AMD 29K family uses IEEE floating-point numbers.
3050 @node AMD29K Directives, AMD29K Opcodes, AMD29K Floating Point, AMD29K-Dependent
3051 _CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives
3054 @item .block @var{size} , @var{fill}
3055 This directive emits @var{size} bytes, each of value @var{fill}. Both
3056 @var{size} and @var{fill} are absolute expressions. If the comma
3057 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3059 In other versions of the GNU assembler, this directive is called
3065 This directive is ignored; it is accepted for compatibility with other
3069 This directive is ignored; it is accepted for compatibility with other
3073 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
3074 used for the directive called @code{.app-file} in the AMD 29K support.
3078 This directive is ignored; it is accepted for compatibility with other
3081 @item .reg @var{symbol}, @var{expression}
3082 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
3085 This directive is ignored; it is accepted for compatibility with other
3088 @item .use @var{segment name}
3089 Establishes the segment and subsegment for the following code;
3090 @var{segment name} may be one of @code{.text}, @code{.data},
3091 @code{.data1}, or @code{.lit}. With one of the first three @var{segment
3092 name} options, @samp{.use} is equivalent to the machine directive
3093 @var{segment name}; the remaining case, @samp{.use .lit}, is the same as
3097 @node AMD29K Opcodes, , AMD29K Directives, AMD29K-Dependent
3098 _CHAPSEC__(1+_GENERIC__) Opcodes
3099 @code{_AS__} implements all the standard AMD 29K opcodes. No
3100 additional pseudo-instructions are needed on this family.
3102 For information on the 29K machine instruction set, see @cite{Am29000
3103 User's Manual}, Advanced Micro Devices, Inc.
3108 @node i960-Dependent, M68K-Dependent, AMD29K-Dependent, Machine Dependent
3110 _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features
3112 * Options-i960:: i960 Command-line Options
3113 * Floating Point-i960:: Floating Point
3114 * Directives-i960:: i960 Machine Directives
3115 * Opcodes for i960:: i960 Opcodes
3118 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
3119 @c long as they're not turned on for other machines than 960.
3120 @node Options-i960, Floating Point-i960, i960-Dependent, i960-Dependent
3121 _CHAPSEC__(1+_GENERIC__) i960 Command-line Options
3124 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
3125 Select the 80960 architecture. Instructions or features not supported
3126 by the selected architecture cause fatal errors.
3128 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
3129 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
3131 If none of these options is specified, @code{_AS__} will generate code for any
3132 instruction or feature that is supported by @emph{some} version of the
3133 960 (even if this means mixing architectures!). In principle,
3134 @code{_AS__} will attempt to deduce the minimal sufficient processor
3135 type if none is specified; depending on the object code format, the
3136 processor type may be recorded in the object file. If it is critical
3137 that the @code{_AS__} output match a specific architecture, specify that
3138 architecture explicitly.
3142 Add code to collect information about conditional branches taken, for
3143 later optimization using branch prediction bits. (The conditional branch
3144 instructions have branch prediction bits in the CA, CB, and CC
3145 architectures.) If @var{BR} represents a conditional branch instruction,
3146 the following represents the code generated by the assembler when
3147 @samp{-b} is specified:
3150 call @var{increment routine}
3151 .word 0 # pre-counter
3153 call @var{increment routine}
3154 .word 0 # post-counter
3157 The counter following a branch records the number of times that branch
3158 was @emph{not} taken; the differenc between the two counters is the
3159 number of times the branch @emph{was} taken.
3161 A table of all such @code{Label}s is also generated, so that the
3162 external postprocessor @samp{gbr960} (supplied by Intel) can locate all
3163 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
3164 this is a local symbol to permit collecting statistics for many separate
3165 object files. The table is word aligned, and begins with a two-word
3166 header. The first word, initialized to 0, is used in maintaining linked
3167 lists of branch tables. The second word is a count of the number of
3168 entries in the table, which follow immediately: each is a word, pointing
3169 to one of the labels illustrated above.
3173 @c END TEXI2ROFF-KILL
3175 +------------+------------+------------+ ... +------------+
3177 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
3179 +------------+------------+------------+ ... +------------+
3181 __BRANCH_TABLE__ layout
3187 \line{\leftskip=0pt\hskip\tableindent
3188 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
3189 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
3190 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
3192 @c END TEXI2ROFF-KILL
3194 The first word of the header is used to locate multiple branch tables,
3195 since each object file may contain one. Normally the links are
3196 maintained with a call to an initialization routine, placed at the
3197 beginning of each function in the file. The GNU C compiler will
3198 generate these calls automatically when you give it a @samp{-b} option.
3199 For further details, see the documentation of @samp{gbr960}.
3202 Normally, Compare-and-Branch instructions with targets that require
3203 displacements greater than 13 bits (or that have external targets) are
3204 replaced with the corresponding compare (or @samp{chkbit}) and branch
3205 instructions. You can use the @samp{-norelax} option to specify that
3206 @code{_AS__} should generate errors instead, if the target displacement
3207 is larger than 13 bits.
3209 This option does not affect the Compare-and-Jump instructions; the code
3210 emitted for them is @emph{always} adjusted when necessary (depending on
3211 displacement size), regardless of whether you use @samp{-norelax}.
3214 @node Floating Point-i960, Directives-i960, Options-i960, i960-Dependent
3215 _CHAPSEC__(1+_GENERIC__) Floating Point
3216 @code{_AS__} generates IEEE floating-point numbers for the directives
3217 @samp{.float}, @samp{.double}, @samp{extended}, and @samp{.single}.
3219 @node Directives-i960, Opcodes for i960, Floating Point-i960, i960-Dependent
3220 _CHAPSEC__(1+_GENERIC__) i960 Machine Directives
3223 @item .bss @var{symbol}, @var{length}, @var{align}
3224 Reserve @var{length} bytes in the bss segment for a local @var{symbol},
3225 aligned to the power of two specified by @var{align}. @var{length} and
3226 @var{align} must be positive absolute expressions. This directive
3227 differs from @samp{.lcomm} only in that it permits you to specify
3228 an alignment. @xref{Lcomm,,@code{.lcomm}}.
3232 @item .extended @var{flonums}
3233 @code{.extended} expects zero or more flonums, separated by commas; for
3234 each flonum, @samp{.extended} emits an IEEE extended-format (80-bit)
3235 floating-point number.
3237 @item .leafproc @var{call-lab}, @var{bal-lab}
3238 You can use the @samp{.leafproc} directive in conjunction with the
3239 optimized @code{callj} instruction to enable faster calls of leaf
3240 procedures. If a procedure is known to call no other procedures, you
3241 may define an entry point that skips procedure prolog code (and that does
3242 not depend on system-supplied saved context), and declare it as the
3243 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
3244 entry point that goes through the normal prolog, you can specify that
3245 entry point as @var{call-lab}.
3247 A @samp{.leafproc} declaration is meant for use in conjunction with the
3248 optimized call instruction @samp{callj}; the directive records the data
3249 needed later to choose between converting the @samp{callj} into a
3250 @code{bal} or a @code{call}.
3252 @var{call-lab} is optional; if only one argument is present, or if the
3253 two arguments are identical, the single argument is assumed to be the
3254 @code{bal} entry point.
3256 @item .sysproc @var{name}, @var{index}
3257 The @samp{.sysproc} directive defines a name for a system procedure.
3258 After you define it using @samp{.sysproc}, you can use @var{name} to
3259 refer to the system procedure identified by @var{index} when calling
3260 procedures with the optimized call instruction @samp{callj}.
3262 Both arguments are required; @var{index} must be between 0 and 31
3266 @node Opcodes for i960, , Directives-i960, i960-Dependent
3267 _CHAPSEC__(1+_GENERIC__) i960 Opcodes
3268 All Intel 960 machine instructions are supported;
3269 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
3270 selecting the instruction subset for a particular 960
3271 architecture.@refill
3273 Some opcodes are processed beyond simply emitting a single corresponding
3274 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
3275 instructions with target displacements larger than 13 bits.
3278 * callj-i960:: @code{callj}
3279 * Compare-and-branch-i960:: Compare-and-Branch
3282 @node callj-i960, Compare-and-branch-i960, Opcodes for i960, Opcodes for i960
3283 _CHAPSEC__(2+_GENERIC__) @code{callj}
3284 You can write @code{callj} to have the assembler or the linker determine
3285 the most appropriate form of subroutine call: @samp{call},
3286 @samp{bal}, or @samp{calls}. If the assembly source contains
3287 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
3288 defining the operand---then @code{_AS__} will translate the
3289 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
3290 for the linker to resolve.
3292 @node Compare-and-branch-i960, , callj-i960, Opcodes for i960
3293 _CHAPSEC__(2+_GENERIC__) Compare-and-Branch
3295 The 960 architectures provide combined Compare-and-Branch instructions
3296 that permit you to store the branch target in the lower 13 bits of the
3297 instruction word itself. However, if you specify a branch target far
3298 enough away that its address won't fit in 13 bits, the assembler can
3299 either issue an error, or convert your Compare-and-Branch instruction
3300 into separate instructions to do the compare and the branch.
3302 Whether @code{_AS__} gives an error or expands the instruction depends
3303 on two choices you can make: whether you use the @samp{-norelax} option,
3304 and whether you use a ``Compare and Branch'' instruction or a ``Compare
3305 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
3306 expanded if necessary; the ``Branch'' instructions are expanded when
3307 necessary @emph{unless} you specify @code{-norelax}---in which case
3308 @code{_AS__} gives an error instead.
3310 These are the Compare-and-Branch instructions, their ``Jump'' variants,
3311 and the instruction pairs they may expand into:
3315 @c END TEXI2ROFF-KILL
3318 Branch Jump Expanded to
3319 ------ ------ ------------
3322 cmpibe cmpije cmpi; be
3323 cmpibg cmpijg cmpi; bg
3324 cmpibge cmpijge cmpi; bge
3325 cmpibl cmpijl cmpi; bl
3326 cmpible cmpijle cmpi; ble
3327 cmpibno cmpijno cmpi; bno
3328 cmpibne cmpijne cmpi; bne
3329 cmpibo cmpijo cmpi; bo
3330 cmpobe cmpoje cmpo; be
3331 cmpobg cmpojg cmpo; bg
3332 cmpobge cmpojge cmpo; bge
3333 cmpobl cmpojl cmpo; bl
3334 cmpoble cmpojle cmpo; ble
3335 cmpobne cmpojne cmpo; bne
3341 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
3342 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
3343 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
3344 bbc& & chkbit; bno\cr
3345 bbs& & chkbit; bo\cr
3346 cmpibe& cmpije& cmpi; be\cr
3347 cmpibg& cmpijg& cmpi; bg\cr
3348 cmpibge& cmpijge& cmpi; bge\cr
3349 cmpibl& cmpijl& cmpi; bl\cr
3350 cmpible& cmpijle& cmpi; ble\cr
3351 cmpibno& cmpijno& cmpi; bno\cr
3352 cmpibne& cmpijne& cmpi; bne\cr
3353 cmpibo& cmpijo& cmpi; bo\cr
3354 cmpobe& cmpoje& cmpo; be\cr
3355 cmpobg& cmpojg& cmpo; bg\cr
3356 cmpobge& cmpojge& cmpo; bge\cr
3357 cmpobl& cmpojl& cmpo; bl\cr
3358 cmpoble& cmpojle& cmpo; ble\cr
3359 cmpobne& cmpojne& cmpo; bne\cr}
3361 @c END TEXI2ROFF-KILL
3366 @c FIXME! node conds are only sufficient for m68k alone, all, and vintage
3368 @node M68K-Dependent, Sparc-Dependent, i960-Dependent, Machine Dependent
3371 @node M68K-Dependent, Sparc-Dependent, Machine Dependent, Machine Dependent
3373 _CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features
3376 * M68K-Opts:: M680x0 Options
3377 * M68K-Syntax:: Syntax
3378 * M68K-Float:: Floating Point
3379 * M68K-Directives:: 680x0 Machine Directives
3380 * M68K-opcodes:: Opcodes
3383 @node M68K-Opts, M68K-Syntax, M68K-Dependent, M68K-Dependent
3384 _CHAPSEC__(1+_GENERIC__) M680x0 Options
3385 The Motorola 680x0 version of @code{_AS__} has two machine dependent options.
3386 One shortens undefined references from 32 to 16 bits, while the
3387 other is used to tell @code{_AS__} what kind of machine it is
3390 You can use the @kbd{-l} option to shorten the size of references to
3391 undefined symbols. If the @kbd{-l} option is not given, references to
3392 undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__}
3393 cannot know where these symbols will end up, @code{_AS__} can only allocate
3394 space for the linker to fill in later. Since @code{_AS__} doesn't know how
3395 far away these symbols will be, it allocates as much space as it can.)
3396 If this option is given, the references will only be one word wide (16
3397 bits). This may be useful if you want the object file to be as small as
3398 possible, and you know that the relevant symbols will be less than 17
3401 The 680x0 version of @code{_AS__} is most frequently used to assemble
3402 programs for the Motorola MC68020 microprocessor. Occasionally it is
3403 used to assemble programs for the mostly similar, but slightly different
3404 MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options
3405 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
3406 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
3409 @node M68K-Syntax, M68K-Float, M68K-Opts, M68K-Dependent
3410 _CHAPSEC__(1+_GENERIC__) Syntax
3412 The 680x0 version of @code{_AS__} uses syntax similar to the Sun assembler.
3413 Size modifiers are appended directly to the end of the opcode without an
3414 intervening period. For example, write @samp{movl} rather than
3418 If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow
3419 Sun-style local labels of the form @samp{1$} through @samp{$9}.
3422 In the following table @dfn{apc} stands for any of the address
3423 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
3424 Program Counter (@samp{pc}), or the zero-address relative to the
3425 program counter (@samp{zpc}).
3427 The following addressing modes are understood:
3430 @samp{#@var{digits}}
3433 @samp{d0} through @samp{d7}
3435 @item Address Register
3436 @samp{a0} through @samp{a7}
3438 @item Address Register Indirect
3439 @samp{a0@@} through @samp{a7@@}
3441 @item Address Register Postincrement
3442 @samp{a0@@+} through @samp{a7@@+}
3444 @item Address Register Predecrement
3445 @samp{a0@@-} through @samp{a7@@-}
3447 @item Indirect Plus Offset
3448 @samp{@var{apc}@@(@var{digits})}
3451 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
3453 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
3456 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
3458 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
3461 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
3463 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
3465 @item Memory Indirect
3466 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
3469 @samp{@var{symbol}}, or @samp{@var{digits}}
3471 @c pesch@cygnus.com: gnu, rich concur the following needs careful
3472 @c research before documenting.
3473 , or either of the above followed
3474 by @samp{:b}, @samp{:w}, or @samp{:l}.
3478 @node M68K-Float, M68K-Directives, M68K-Syntax, M68K-Dependent
3479 _CHAPSEC__(1+_GENERIC__) Floating Point
3480 The floating point code is not too well tested, and may have
3483 Packed decimal (P) format floating literals are not supported.
3484 Feel free to add the code!
3486 The floating point formats generated by directives are these.
3489 @code{Single} precision floating point constants.
3491 @code{Double} precision floating point constants.
3494 There is no directive to produce regions of memory holding
3495 extended precision numbers, however they can be used as
3496 immediate operands to floating-point instructions. Adding a
3497 directive to create extended precision numbers would not be
3498 hard, but it has not yet seemed necessary.
3500 @node M68K-Directives, M68K-opcodes, M68K-Float, M68K-Dependent
3501 _CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives
3502 In order to be compatible with the Sun assembler the 680x0 assembler
3503 understands the following directives.
3506 This directive is identical to a @code{.data 1} directive.
3508 This directive is identical to a @code{.data 2} directive.
3510 This directive is identical to a @code{.align 1} directive.
3511 @c Is this true? does it work???
3513 This directive is identical to a @code{.space} directive.
3516 @node M68K-opcodes, , M68K-Directives, M68K-Dependent
3517 _CHAPSEC__(1+_GENERIC__) Opcodes
3518 @c pesch@cygnus.com: I don't see any point in the following
3519 @c paragraph. Bugs are bugs; how does saying this
3522 Danger: Several bugs have been found in the opcode table (and
3523 fixed). More bugs may exist. Be careful when using obscure
3528 * M68K-Branch:: Branch Improvement
3529 * M68K-Chars:: Special Characters
3532 @node M68K-Branch, M68K-Chars, M68K-opcodes, M68K-opcodes
3533 _CHAPSEC__(2+_GENERIC__) Branch Improvement
3535 Certain pseudo opcodes are permitted for branch instructions.
3536 They expand to the shortest branch instruction that will reach the
3537 target. Generally these mnemonics are made by substituting @samp{j} for
3538 @samp{b} at the start of a Motorola mnemonic.
3540 The following table summarizes the pseudo-operations. A @code{*} flags
3541 cases that are more fully described after the table:
3545 +---------------------------------------------------------
3547 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
3548 +---------------------------------------------------------
3549 jbsr |bsrs bsr bsrl jsr jsr
3550 jra |bras bra bral jmp jmp
3551 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
3552 * dbXX |dbXX dbXX dbXX; bra; jmpl
3553 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
3556 NX: negative of condition XX
3559 @center @code{*}---see full description below
3564 These are the simplest jump pseudo-operations; they always map to one
3565 particular machine instruction, depending on the displacement to the
3569 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
3570 where @var{XX} is a conditional branch or condition-code test. The full
3571 list of pseudo-ops in this family is:
3573 jhi jls jcc jcs jne jeq jvc
3574 jvs jpl jmi jge jlt jgt jle
3577 For the cases of non-PC relative displacements and long displacements on
3578 the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of
3579 @var{NX}, the opposite condition to @var{XX}:
3591 The full family of pseudo-operations covered here is
3593 dbhi dbls dbcc dbcs dbne dbeq dbvc
3594 dbvs dbpl dbmi dbge dblt dbgt dble
3598 Other than for word and byte displacements, when the source reads
3599 @samp{db@var{XX} foo}, @code{_AS__} will emit
3608 This family includes
3610 fjne fjeq fjge fjlt fjgt fjle fjf
3611 fjt fjgl fjgle fjnge fjngl fjngle fjngt
3612 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
3613 fjor fjseq fjsf fjsne fjst fjueq fjuge
3614 fjugt fjule fjult fjun
3617 For branch targets that are not PC relative, @code{_AS__} emits
3623 when it encounters @samp{fj@var{XX} foo}.
3627 @node M68K-Chars, , M68K-Branch, M68K-opcodes
3628 _CHAPSEC__(2+_GENERIC__) Special Characters
3629 The immediate character is @samp{#} for Sun compatibility. The
3630 line-comment character is @samp{|}. If a @samp{#} appears at the
3631 beginning of a line, it is treated as a comment unless it looks like
3632 @samp{# line file}, in which case it is treated normally.
3636 @c pesch@cygnus.com: conditionalize on something other than 0 when filled in.
3639 The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to
3640 specify thiat it is compiling for a 32032 processor, or a
3641 @kbd{-m32532} to specify that it is compiling for a 32532 option.
3642 The default (if neither is specified) is chosen when the assembler
3646 I don't know anything about the 32x32 syntax assembled by
3647 @code{_AS__}. Someone who undersands the processor (I've never seen
3648 one) and the possible syntaxes should write this section.
3650 @subsection Floating Point
3651 The 32x32 uses IEEE floating point numbers, but @code{_AS__} will only
3652 create single or double precision values. I don't know if the 32x32
3653 understands extended precision numbers.
3655 @subsection 32x32 Machine Directives
3656 The 32x32 has no machine dependent directives.
3661 _if__(_I80386__&&_M680X0__)
3662 @node Sparc-Dependent, i386-Dependent, M68K-Dependent, Machine Dependent
3663 _fi__(_I80386__&&_M680X0__)
3664 _if__(_I80386__&&_I960__&&!_M680X0__)
3665 @node Sparc-Dependent, i386-Dependent, i960-Dependent, Machine Dependent
3666 _fi__(_I80386__&&_I960__&&!_M680X0__)
3667 _if__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
3668 @node Sparc-Dependent, i386-Dependent, AMD29K-Dependent, Machine Dependent
3669 _fi__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__)
3670 _if__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3671 @node Sparc-Dependent, i386-Dependent, Vax-Dependent, Machine Dependent
3672 _fi__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3673 _if__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3674 @node Sparc-Dependent, i386-Dependent, Machine Dependent, Machine Dependent
3675 _fi__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3676 _if__((!_I80386__)&&_M680X0__)
3677 @node Sparc-Dependent, , M68K-Dependent, Machine Dependent
3678 _fi__((!_I80386__)&&_M680X0__)
3679 _if__((!_I80386__)&&_I960__&&!_M680X0__)
3680 @node Sparc-Dependent, , i960-Dependent, Machine Dependent
3681 _fi__((!_I80386__)&&_I960__&&!_M680X0__)
3682 _if__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
3683 @node Sparc-Dependent, , AMD29K-Dependent, Machine Dependent
3684 _fi__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__)
3685 _if__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3686 @node Sparc-Dependent, , Vax-Dependent, Machine Dependent
3687 _fi__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3688 _if__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3689 @node Sparc-Dependent, , Machine Dependent, Machine Dependent
3690 _fi__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__)
3692 _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features
3694 * Sparc-Opts:: Options
3695 * Sparc-Float:: Floating Point
3696 * Sparc-Directives:: Sparc Machine Directives
3699 @node Sparc-Opts, Sparc-Float, Sparc-Dependent, Sparc-Dependent
3700 _CHAPSEC__(1+_GENERIC__) Options
3701 The Sparc has no machine dependent options.
3704 @c FIXME: (sparc) Fill in "syntax" section!
3705 @c subsection syntax
3706 I don't know anything about Sparc syntax. Someone who does
3707 will have to write this section.
3710 @node Sparc-Float, Sparc-Directives, Sparc-Opts, Sparc-Dependent
3711 _CHAPSEC__(1+_GENERIC__) Floating Point
3712 The Sparc uses @sc{ieee} floating-point numbers.
3714 @node Sparc-Directives, , Sparc-Float, Sparc-Dependent
3715 _CHAPSEC__(1+_GENERIC__) Sparc Machine Directives
3716 The Sparc version of @code{_AS__} supports the following additional
3721 This must be followed by a symbol name, a positive number, and
3722 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
3723 syntax is different.
3726 This is functionally identical to @code{.globl}.
3727 @c FIXME: is this still really SPARC specific? (vintage/devo)
3730 This is functionally identical to @code{.short}.
3733 This directive is ignored. Any text following it on the same
3734 line is also ignored.
3737 This must be followed by a symbol name, a positive number, and
3738 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
3739 syntax is different.
3742 This must be followed by @code{"text"}, @code{"data"}, or
3743 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
3747 This is functionally identical to the @code{.space} directive.
3750 On the Sparc, the .word directive produces 32 bit values,
3751 instead of the 16 bit values it produces on many other machines.
3758 @c FIXME! Conditionalize for all combinations in this section
3759 @node i386-Dependent, , Sparc-Dependent, Machine Dependent
3761 _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features
3764 * i386-Options:: Options
3765 * i386-Syntax:: AT&T Syntax versus Intel Syntax
3766 * i386-Opcodes:: Opcode Naming
3767 * i386-Regs:: Register Naming
3768 * i386-prefixes:: Opcode Prefixes
3769 * i386-Memory:: Memory References
3770 * i386-jumps:: Handling of Jump Instructions
3771 * i386-Float:: Floating Point
3772 * i386-Notes:: Notes
3775 @node i386-Options, i386-Syntax, i386-Dependent, i386-Dependent
3776 _CHAPSEC__(1+_GENERIC__) Options
3777 The 80386 has no machine dependent options.
3779 @node i386-Syntax, i386-Opcodes, i386-Options, i386-Dependent
3780 _CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax
3781 In order to maintain compatibility with the output of @code{_GCC__},
3782 @code{_AS__} supports AT&T System V/386 assembler syntax. This is quite
3783 different from Intel syntax. We mention these differences because
3784 almost all 80386 documents used only Intel syntax. Notable differences
3785 between the two syntaxes are:
3788 AT&T immediate operands are preceded by @samp{$}; Intel immediate
3789 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
3790 AT&T register operands are preceded by @samp{%}; Intel register operands
3791 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
3792 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
3795 AT&T and Intel syntax use the opposite order for source and destination
3796 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
3797 @samp{source, dest} convention is maintained for compatibility with
3798 previous Unix assemblers.
3801 In AT&T syntax the size of memory operands is determined from the last
3802 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
3803 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
3804 memory references. Intel syntax accomplishes this by prefixes memory
3805 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
3806 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
3807 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
3810 Immediate form long jumps and calls are
3811 @samp{lcall/ljmp $@var{segment}, $@var{offset}} in AT&T syntax; the
3813 @samp{call/jmp far @var{segment}:@var{offset}}. Also, the far return
3815 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
3816 @samp{ret far @var{stack-adjust}}.
3819 The AT&T assembler does not provide support for multiple segment
3820 programs. Unix style systems expect all programs to be single segments.
3823 @node i386-Opcodes, i386-Regs, i386-Syntax, i386-Dependent
3824 _CHAPSEC__(1+_GENERIC__) Opcode Naming
3825 Opcode names are suffixed with one character modifiers which specify the
3826 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
3827 byte, word, and long operands. If no suffix is specified by an
3828 instruction and it contains no memory operands then @code{_AS__} tries to
3829 fill in the missing suffix based on the destination register operand
3830 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
3831 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
3832 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
3833 assembler which assumes that a missing opcode suffix implies long
3834 operand size. (This incompatibility does not affect compiler output
3835 since compilers always explicitly specify the opcode suffix.)
3837 Almost all opcodes have the same names in AT&T and Intel format. There
3838 are a few exceptions. The sign extend and zero extend instructions need
3839 two sizes to specify them. They need a size to sign/zero extend
3840 @emph{from} and a size to zero extend @emph{to}. This is accomplished
3841 by using two opcode suffixes in AT&T syntax. Base names for sign extend
3842 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
3843 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
3844 suffixes are tacked on to this base name, the @emph{from} suffix before
3845 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
3846 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
3847 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
3848 and @samp{wl} (from word to long).
3850 The Intel syntax conversion instructions
3853 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
3855 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
3857 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
3859 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
3861 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
3862 AT&T naming. @code{_AS__} accepts either naming for these instructions.
3864 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
3865 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
3868 @node i386-Regs, i386-prefixes, i386-Opcodes, i386-Dependent
3869 _CHAPSEC__(1+_GENERIC__) Register Naming
3870 Register operands are always prefixes with @samp{%}. The 80386 registers
3874 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
3875 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
3876 frame pointer), and @samp{%esp} (the stack pointer).
3879 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
3880 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
3883 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
3884 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
3885 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
3886 @samp{%cx}, and @samp{%dx})
3889 the 6 segment registers @samp{%cs} (code segment), @samp{%ds}
3890 (data segment), @samp{%ss} (stack segment), @samp{%es}, @samp{%fs},
3894 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
3898 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
3899 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
3902 the 2 test registers @samp{%tr6} and @samp{%tr7}.
3905 the 8 floating point register stack @samp{%st} or equivalently
3906 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
3907 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
3910 @node i386-prefixes, i386-Memory, i386-Regs, i386-Dependent
3911 _CHAPSEC__(1+_GENERIC__) Opcode Prefixes
3912 Opcode prefixes are used to modify the following opcode. They are used
3913 to repeat string instructions, to provide segment overrides, to perform
3914 bus lock operations, and to give operand and address size (16-bit
3915 operands are specified in an instruction by prefixing what would
3916 normally be 32-bit operands with a ``operand size'' opcode prefix).
3917 Opcode prefixes are usually given as single-line instructions with no
3918 operands, and must directly precede the instruction they act upon. For
3919 example, the @samp{scas} (scan string) instruction is repeated with:
3925 Here is a list of opcode prefixes:
3928 Segment override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
3929 @samp{fs}, @samp{gs}. These are automatically added by specifying
3930 using the @var{segment}:@var{memory-operand} form for memory references.
3933 Operand/Address size prefixes @samp{data16} and @samp{addr16}
3934 change 32-bit operands/addresses into 16-bit operands/addresses. Note
3935 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
3936 are not supported (yet).
3939 The bus lock prefix @samp{lock} inhibits interrupts during
3940 execution of the instruction it precedes. (This is only valid with
3941 certain instructions; see a 80386 manual for details).
3944 The wait for coprocessor prefix @samp{wait} waits for the
3945 coprocessor to complete the current instruction. This should never be
3946 needed for the 80386/80387 combination.
3949 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
3950 to string instructions to make them repeat @samp{%ecx} times.
3953 @node i386-Memory, i386-jumps, i386-prefixes, i386-Dependent
3954 _CHAPSEC__(1+_GENERIC__) Memory References
3955 An Intel syntax indirect memory reference of the form
3957 @var{segment}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
3959 is translated into the AT&T syntax
3961 @var{segment}:@var{disp}(@var{base}, @var{index}, @var{scale})
3963 where @var{base} and @var{index} are the optional 32-bit base and
3964 index registers, @var{disp} is the optional displacement, and
3965 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
3966 to calculate the address of the operand. If no @var{scale} is
3967 specified, @var{scale} is taken to be 1. @var{segment} specifies the
3968 optional segment register for the memory operand, and may override the
3969 default segment register (see a 80386 manual for segment register
3970 defaults). Note that segment overrides in AT&T syntax @emph{must} have
3971 be preceded by a @samp{%}. If you specify a segment override which
3972 coincides with the default segment register, @code{_AS__} will @emph{not}
3973 output any segment register override prefixes to assemble the given
3974 instruction. Thus, segment overrides can be specified to emphasize which
3975 segment register is used for a given memory operand.
3977 Here are some examples of Intel and AT&T style memory references:
3980 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
3981 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{segment} is
3982 missing, and the default segment is used (@samp{%ss} for addressing with
3983 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
3985 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
3986 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
3987 @samp{foo}. All other fields are missing. The segment register here
3988 defaults to @samp{%ds}.
3990 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
3991 This uses the value pointed to by @samp{foo} as a memory operand.
3992 Note that @var{base} and @var{index} are both missing, but there is only
3993 @emph{one} @samp{,}. This is a syntactic exception.
3995 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
3996 This selects the contents of the variable @samp{foo} with segment
3997 register @var{segment} being @samp{%gs}.
4001 Absolute (as opposed to PC relative) call and jump operands must be
4002 prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will
4003 always choose PC relative addressing for jump/call labels.
4005 Any instruction that has a memory operand @emph{must} specify its size (byte,
4006 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
4009 @node i386-jumps, i386-Float, i386-Memory, i386-Dependent
4010 _CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions
4011 Jump instructions are always optimized to use the smallest possible
4012 displacements. This is accomplished by using byte (8-bit) displacement
4013 jumps whenever the target is sufficiently close. If a byte displacement
4014 is insufficient a long (32-bit) displacement is used. We do not support
4015 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
4016 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
4017 @samp{%eip} to 16 bits after the word displacement is added.
4019 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
4020 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
4021 byte displacements, so that it is possible that use of these
4022 instructions (@code{_GCC__} does not use them) will cause the assembler to
4023 print an error message (and generate incorrect code). The AT&T 80386
4024 assembler tries to get around this problem by expanding @samp{jcxz foo} to
4032 @node i386-Float, i386-Notes, i386-jumps, i386-Dependent
4033 _CHAPSEC__(1+_GENERIC__) Floating Point
4034 All 80387 floating point types except packed BCD are supported.
4035 (BCD support may be added without much difficulty). These data
4036 types are 16-, 32-, and 64- bit integers, and single (32-bit),
4037 double (64-bit), and extended (80-bit) precision floating point.
4038 Each supported type has an opcode suffix and a constructor
4039 associated with it. Opcode suffixes specify operand's data
4040 types. Constructors build these data types into memory.
4044 Floating point constructors are @samp{.float} or @samp{.single},
4045 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
4046 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
4047 @samp{t} stands for temporary real, and that the 80387 only supports
4048 this format via the @samp{fldt} (load temporary real to stack top) and
4049 @samp{fstpt} (store temporary real and pop stack) instructions.
4052 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
4053 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
4054 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
4055 (quad). As with the temporary real format the 64-bit @samp{q} format is
4056 only present in the @samp{fildq} (load quad integer to stack top) and
4057 @samp{fistpq} (store quad integer and pop stack) instructions.
4060 Register to register operations do not require opcode suffixes,
4061 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
4063 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
4064 instructions are almost never needed (this is not the case for the
4065 80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses
4066 the @samp{fwait} instruction whenever it is implicitly selected by one
4067 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
4068 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
4069 instructions are made equivalent to @samp{f@dots{}} instructions. If
4070 @samp{fwait} is desired it must be explicitly coded.
4072 @node i386-Notes, , i386-Float, i386-Dependent
4073 _CHAPSEC__(1+_GENERIC__) Notes
4074 There is some trickery concerning the @samp{mul} and @samp{imul}
4075 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
4076 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
4077 for @samp{imul}) can be output only in the one operand form. Thus,
4078 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
4079 the expanding multiply would clobber the @samp{%edx} register, and this
4080 would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the
4081 64-bit product in @samp{%edx:%eax}.
4083 We have added a two operand form of @samp{imul} when the first operand
4084 is an immediate mode expression and the second operand is a register.
4085 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
4086 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
4091 @c pesch@cygnus.com: we ignore the following chapters, since internals are
4092 @c changing rapidly. These may need to be moved to another
4093 @c book anyhow, if we adopt the model of user/modifier
4095 @node Maintenance, Retargeting, _MACH_DEP__, Top
4096 @chapter Maintaining the Assembler
4097 [[this chapter is still being built]]
4100 We had these goals, in descending priority:
4103 For every program composed by a compiler, @code{_AS__} should emit
4104 ``correct'' code. This leaves some latitude in choosing addressing
4105 modes, order of @code{relocation_info} structures in the object
4108 @item Speed, for usual case.
4109 By far the most common use of @code{_AS__} will be assembling compiler
4112 @item Upward compatibility for existing assembler code.
4113 Well @dots{} we don't support Vax bit fields but everything else
4114 seems to be upward compatible.
4117 The code should be maintainable with few surprises. (JF: ha!)
4121 We assumed that disk I/O was slow and expensive while memory was
4122 fast and access to memory was cheap. We expect the in-memory data
4123 structures to be less than 10 times the size of the emitted object
4124 file. (Contrast this with the C compiler where in-memory structures
4125 might be 100 times object file size!)
4129 Try to read the source file from disk only one time. For other
4130 reasons, we keep large chunks of the source file in memory during
4131 assembly so this is not a problem. Also the assembly algorithm
4132 should only scan the source text once if the compiler composed the
4133 text according to a few simple rules.
4135 Emit the object code bytes only once. Don't store values and then
4138 Build the object file in memory and do direct writes to disk of
4142 RMS suggested a one-pass algorithm which seems to work well. By not
4143 parsing text during a second pass considerable time is saved on
4144 large programs (@emph{e.g.} the sort of C program @code{yacc} would
4147 It happened that the data structures needed to emit relocation
4148 information to the object file were neatly subsumed into the data
4149 structures that do backpatching of addresses after pass 1.
4151 Many of the functions began life as re-usable modules, loosely
4152 connected. RMS changed this to gain speed. For example, input
4153 parsing routines which used to work on pre-sanitized strings now
4154 must parse raw data. Hence they have to import knowledge of the
4155 assemblers' comment conventions @emph{etc}.
4157 @section Deprecated Feature(?)s
4158 We have stopped supporting some features:
4161 @code{.org} statements must have @b{defined} expressions.
4163 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
4166 It might be a good idea to not support these features in a future release:
4169 @kbd{#} should begin a comment, even in column 1.
4171 Why support the logical line & file concept any more?
4173 Subsegments are a good candidate for flushing.
4174 Depends on which compilers need them I guess.
4177 @section Bugs, Ideas, Further Work
4178 Clearly the major improvement is DON'T USE A TEXT-READING
4179 ASSEMBLER for the back end of a compiler. It is much faster to
4180 interpret binary gobbledygook from a compiler's tables than to
4181 ask the compiler to write out human-readable code just so the
4182 assembler can parse it back to binary.
4184 Assuming you use @code{_AS__} for human written programs: here are
4188 Document (here) @code{APP}.
4190 Take advantage of knowing no spaces except after opcode
4191 to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces:
4192 only keep space/tabs at begin of line or between 2
4195 Put pointers in this documentation to @file{a.out} documentation.
4197 Split the assembler into parts so it can gobble direct binary
4198 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
4199 just so @code{_AS__} can parse it back to binary.
4201 Rewrite hash functions: I want a more modular, faster library.
4203 Clean up LOTS of code.
4205 Include all the non-@file{.c} files in the maintenance chapter.
4209 Implement flonum short literals.
4211 Change all talk of expression operands to expression quantities,
4212 or perhaps to expression arguments.
4216 Whenever a @code{.text} or @code{.data} statement is seen, we close
4217 of the current frag with an imaginary @code{.fill 0}. This is
4218 because we only have one obstack for frags, and we can't grow new
4219 frags for a new subsegment, then go back to the old subsegment and
4220 append bytes to the old frag. All this nonsense goes away if we
4221 give each subsegment its own obstack. It makes code simpler in
4222 about 10 places, but nobody has bothered to do it because C compiler
4223 output rarely changes subsegments (compared to ending frags with
4224 relaxable addresses, which is common).
4228 @c The following files in the @file{_AS__} directory
4229 @c are symbolic links to other files, of
4230 @c the same name, in a different directory.
4233 @c @file{atof_generic.c}
4235 @c @file{atof_vax.c}
4237 @c @file{flonum_const.c}
4239 @c @file{flonum_copy.c}
4241 @c @file{flonum_get.c}
4243 @c @file{flonum_multip.c}
4245 @c @file{flonum_normal.c}
4247 @c @file{flonum_print.c}
4250 Here is a list of the source files in the @file{_AS__} directory.
4254 This contains the pre-processing phase, which deletes comments,
4255 handles whitespace, etc. This was recently re-written, since app
4256 used to be a separate program, but RMS wanted it to be inline.
4259 This is a subroutine to append a string to another string returning a
4260 pointer just after the last @code{char} appended. (JF: All these
4261 little routines should probably all be put in one file.)
4264 Here you will find the main program of the assembler @code{_AS__}.
4267 This is a branch office of @file{read.c}. This understands
4268 expressions, arguments. Inside @code{_AS__}, arguments are called
4269 (expression) @emph{operands}. This is confusing, because we also talk
4270 (elsewhere) about instruction @emph{operands}. Also, expression
4271 operands are called @emph{quantities} explicitly to avoid confusion
4272 with instruction operands. What a mess.
4275 This implements the @b{frag} concept. Without frags, finding the
4276 right size for branch instructions would be a lot harder.
4279 This contains the symbol table, opcode table @emph{etc.} hashing
4283 This is a table of values of digits, for use in atoi() type
4284 functions. Could probably be flushed by using calls to strtol(), or
4288 This contains Operating system dependent source file reading
4289 routines. Since error messages often say where we are in reading
4290 the source file, they live here too. Since @code{_AS__} is intended to
4291 run under GNU and Unix only, this might be worth flushing. Anyway,
4292 almost all C compilers support stdio.
4295 This deals with calling the pre-processor (if needed) and feeding the
4296 chunks back to the rest of the assembler the right way.
4299 This contains operating system independent parts of fatal and
4300 warning message reporting. See @file{append.c} above.
4303 This contains operating system dependent functions that write an
4304 object file for @code{_AS__}. See @file{input-file.c} above.
4307 This implements all the directives of @code{_AS__}. This also deals
4308 with passing input lines to the machine dependent part of the
4312 This is a C library function that isn't in most C libraries yet.
4313 See @file{append.c} above.
4316 This implements subsegments.
4319 This implements symbols.
4322 This contains the code to perform relaxation, and to write out
4323 the object file. It is mostly operating system independent, but
4324 different OSes have different object file formats in any case.
4327 This implements @code{malloc()} or bust. See @file{append.c} above.
4330 This implements @code{realloc()} or bust. See @file{append.c} above.
4332 @item atof-generic.c
4333 The following files were taken from a machine-independent subroutine
4334 library for manipulating floating point numbers and very large
4337 @file{atof-generic.c} turns a string into a flonum internal format
4338 floating-point number.
4340 @item flonum-const.c
4341 This contains some potentially useful floating point numbers in
4345 This copies a flonum.
4347 @item flonum-multip.c
4348 This multiplies two flonums together.
4351 This copies a bignum.
4355 Here is a table of all the machine-specific files (this includes
4356 both source and header files). Typically, there is a
4357 @var{machine}.c file, a @var{machine}-opcode.h file, and an
4358 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
4359 be identical to the one used by GDB (which uses it for disassembly.)
4364 This contains code to turn a flonum into a ieee literal constant.
4365 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}.
4368 This is the opcode-table for the i386 version of the assembler.
4371 This contains all the code for the i386 version of the assembler.
4374 This defines constants and macros used by the i386 version of the assembler.
4377 generic 68020 header file. To be linked to m68k.h on a
4378 non-sun3, non-hpux system.
4381 68010 header file for Sun2 workstations. Not well tested. To be linked
4382 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
4386 68020 header file for Sun3 workstations. To be linked to m68k.h before
4387 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
4391 68020 header file for a HPUX (system 5?) box. Which box, which
4392 version of HPUX, etc? I don't know.
4395 A hard- or symbolic- link to one of @file{m-generic.h},
4396 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
4397 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
4401 Opcode table for 68020. This is now a link to the opcode table
4402 in the @code{GDB} source directory.
4405 All the mc680x0 code, in one huge, slow-to-compile file.
4408 This contains the code for the ns32032/ns32532 version of the
4411 @item ns32k-opcode.h
4412 This contains the opcode table for the ns32032/ns32532 version
4416 Vax specific file for describing Vax operands and other Vax-ish things.
4422 Vax specific parts of @code{_AS__}. Also includes the former files
4423 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
4426 Turns a flonum into a Vax constant.
4429 This file contains the special code needed to put out a VMS
4430 style object file for the Vax.
4434 Here is a list of the header files in the source directory.
4435 (Warning: This section may not be very accurate. I didn't
4436 write the header files; I just report them.) Also note that I
4437 think many of these header files could be cleaned up or
4443 This describes the structures used to create the binary header data
4444 inside the object file. Perhaps we should use the one in
4445 @file{/usr/include}?
4448 This defines all the globally useful things, and pulls in _0__<stdio.h>_1__
4449 and _0__<assert.h>_1__.
4452 This defines macros useful for dealing with bignums.
4455 Structure and macros for dealing with expression()
4458 This defines the structure for dealing with floating point
4459 numbers. It #includes @file{bignum.h}.
4462 This contains macro for appending a byte to the current frag.
4465 Structures and function definitions for the hashing functions.
4468 Function headers for the input-file.c functions.
4471 structures and function headers for things defined in the
4472 machine dependent part of the assembler.
4475 This is the GNU systemwide include file for manipulating obstacks.
4476 Since nobody is running under real GNU yet, we include this file.
4479 Macros and function headers for reading in source files.
4481 @item struct-symbol.h
4482 Structure definition and macros for dealing with the _AS__
4483 internal form of a symbol.
4486 structure definition for dealing with the numbered subsegments
4487 of the text and data segments.
4490 Macros and function headers for dealing with symbols.
4493 Structure for doing segment fixups.
4496 @comment ~subsection Test Directory
4497 @comment (Note: The test directory seems to have disappeared somewhere
4498 @comment along the line. If you want it, you'll probably have to find a
4499 @comment REALLY OLD dump tape~dots{})
4501 @comment The ~file{test/} directory is used for regression testing.
4502 @comment After you modify ~@code{_AS__}, you can get a quick go/nogo
4503 @comment confidence test by running the new ~@code{_AS__} over the source
4504 @comment files in this directory. You use a shell script ~file{test/do}.
4506 @comment The tests in this suite are evolving. They are not comprehensive.
4507 @comment They have, however, caught hundreds of bugs early in the debugging
4508 @comment cycle of ~@code{_AS__}. Most test statements in this suite were naturally
4509 @comment selected: they were used to demonstrate actual ~@code{_AS__} bugs rather
4510 @comment than being written ~i{a prioi}.
4512 @comment Another testing suggestion: over 30 bugs have been found simply by
4513 @comment running examples from this manual through ~@code{_AS__}.
4514 @comment Some examples in this manual are selected
4515 @comment to distinguish boundary conditions; they are good for testing ~@code{_AS__}.
4517 @comment ~subsubsection Regression Testing
4518 @comment Each regression test involves assembling a file and comparing the
4519 @comment actual output of ~@code{_AS__} to ``known good'' output files. Both
4520 @comment the object file and the error/warning message file (stderr) are
4521 @comment inspected. Optionally the ~@code{_AS__} exit status may be checked.
4522 @comment Discrepencies are reported. Each discrepency means either that
4523 @comment you broke some part of ~@code{_AS__} or that the ``known good'' files
4524 @comment are now out of date and should be changed to reflect the new
4525 @comment definition of ``good''.
4527 @comment Each regression test lives in its own directory, in a tree
4528 @comment rooted in the directory ~file{test/}. Each such directory
4529 @comment has a name ending in ~file{.ret}, where `ret' stands for
4530 @comment REgression Test. The ~file{.ret} ending allows ~code{find
4531 @comment (1)} to find all regression tests in the tree, without
4532 @comment needing to list them explicitly.
4534 @comment Any ~file{.ret} directory must contain a file called
4535 @comment ~file{input} which is the source file to assemble. During
4536 @comment testing an object file ~file{output} is created, as well as
4537 @comment a file ~file{stdouterr} which contains the output to both
4538 @comment stderr and stderr. If there is a file ~file{output.good} in
4539 @comment the directory, and if ~file{output} contains exactly the
4540 @comment same data as ~file{output.good}, the file ~file{output} is
4541 @comment deleted. Likewise ~file{stdouterr} is removed if it exactly
4542 @comment matches a file ~file{stdouterr.good}. If file
4543 @comment ~file{status.good} is present, containing a decimal number
4544 @comment before a newline, the exit status of ~@code{_AS__} is compared
4545 @comment to this number. If the status numbers are not equal, a file
4546 @comment ~file{status} is written to the directory, containing the
4547 @comment actual status as a decimal number followed by newline.
4549 @comment Should any of the ~file{*.good} files fail to match their corresponding
4550 @comment actual files, this is noted by a 1-line message on the screen during
4551 @comment the regression test, and you can use ~@code{find (1)} to find any
4552 @comment files named ~file{status}, ~file {output} or ~file{stdouterr}.
4554 @node Retargeting, License, Maintenance, Top
4555 @chapter Teaching the Assembler about a New Machine
4557 This chapter describes the steps required in order to make the
4558 assembler work with another machine's assembly language. This
4559 chapter is not complete, and only describes the steps in the
4560 broadest terms. You should look at the source for the
4561 currently supported machine in order to discover some of the
4562 details that aren't mentioned here.
4564 You should create a new file called @file{@var{machine}.c}, and
4565 add the appropriate lines to the file @file{Makefile} so that
4566 you can compile your new version of the assembler. This should
4567 be straighforward; simply add lines similar to the ones there
4568 for the four current versions of the assembler.
4570 If you want to be compatible with GDB, (and the current
4571 machine-dependent versions of the assembler), you should create
4572 a file called @file{@var{machine}-opcode.h} which should
4573 contain all the information about the names of the machine
4574 instructions, their opcodes, and what addressing modes they
4575 support. If you do this right, the assembler and GDB can share
4576 this file, and you'll only have to write it once. Note that
4577 while you're writing @code{_AS__}, you may want to use an
4578 independent program (if you have access to one), to make sure
4579 that @code{_AS__} is emitting the correct bytes. Since @code{_AS__}
4580 and @code{GDB} share the opcode table, an incorrect opcode
4581 table entry may make invalid bytes look OK when you disassemble
4582 them with @code{GDB}.
4584 @section Functions You will Have to Write
4586 Your file @file{@var{machine}.c} should contain definitions for
4587 the following functions and variables. It will need to include
4588 some header files in order to use some of the structures
4589 defined in the machine-independent part of the assembler. The
4590 needed header files are mentioned in the descriptions of the
4591 functions that will need them.
4596 This long integer holds the value to place at the beginning of
4597 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
4598 machines that store additional information in the magic-number.
4600 @item char comment_chars[];
4601 This character array holds the values of the characters that
4602 start a comment anywhere in a line. Comments are stripped off
4603 automatically by the machine independent part of the
4604 assembler. Note that the @samp{/*} will always start a
4605 comment, and that only @samp{*/} will end a comment started by
4608 @item char line_comment_chars[];
4609 This character array holds the values of the chars that start a
4610 comment only if they are the first (non-whitespace) character
4611 on a line. If the character @samp{#} does not appear in this
4612 list, you may get unexpected results. (Various
4613 machine-independent parts of the assembler treat the comments
4614 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
4615 that start with @samp{#} are comments.)
4617 @item char EXP_CHARS[];
4618 This character array holds the letters that can separate the
4619 mantissa and the exponent of a floating point number. Typical
4620 values are @samp{e} and @samp{E}.
4622 @item char FLT_CHARS[];
4623 This character array holds the letters that--when they appear
4624 immediately after a leading zero--indicate that a number is a
4625 floating-point number. (Sort of how 0x indicates that a
4626 hexadecimal number follows.)
4628 @item pseudo_typeS md_pseudo_table[];
4629 (@var{pseudo_typeS} is defined in @file{md.h})
4630 This array contains a list of the machine_dependent directives
4631 the assembler must support. It contains the name of each
4632 pseudo op (Without the leading @samp{.}), a pointer to a
4633 function to be called when that directive is encountered, and
4634 an integer argument to be passed to that function.
4636 @item void md_begin(void)
4637 This function is called as part of the assembler's
4638 initialization. It should do any initialization required by
4639 any of your other routines.
4641 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
4642 This routine is called once for each option on the command line
4643 that the machine-independent part of @code{_AS__} does not
4644 understand. This function should return non-zero if the option
4645 pointed to by @var{optionPTR} is a valid option. If it is not
4646 a valid option, this routine should return zero. The variables
4647 @var{argcPTR} and @var{argvPTR} are provided in case the option
4648 requires a filename or something similar as an argument. If
4649 the option is multi-character, @var{optionPTR} should be
4650 advanced past the end of the option, otherwise every letter in
4651 the option will be treated as a separate single-character
4654 @item void md_assemble(char *string)
4655 This routine is called for every machine-dependent
4656 non-directive line in the source file. It does all the real
4657 work involved in reading the opcode, parsing the operands,
4658 etc. @var{string} is a pointer to a null-terminated string,
4659 that comprises the input line, with all excess whitespace and
4662 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
4663 This routine is called to turn a C long int, short int, or char
4664 into the series of bytes that represents that number on the
4665 target machine. @var{outputPTR} points to an array where the
4666 result should be stored; @var{value} is the value to store; and
4667 @var{nbytes} is the number of bytes in 'value' that should be
4670 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
4671 This routine is called to turn a C long int, short int, or char
4672 into the series of bytes that represent an immediate value on
4673 the target machine. It is identical to the function @code{md_number_to_chars},
4674 except on NS32K machines.@refill
4676 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
4677 This routine is called to turn a C long int, short int, or char
4678 into the series of bytes that represent an displacement value on
4679 the target machine. It is identical to the function @code{md_number_to_chars},
4680 except on NS32K machines.@refill
4682 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
4683 This routine is identical to @code{md_number_to_chars},
4684 except on NS32K machines.
4686 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
4687 (@code{struct relocation_info} is defined in @file{a.out.h})
4688 This routine emits the relocation info in @var{ri}
4689 in the appropriate bit-pattern for the target machine.
4690 The result should be stored in the location pointed
4691 to by @var{riPTR}. This routine may be a no-op unless you are
4692 attempting to do cross-assembly.
4694 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
4695 This routine turns a series of digits into the appropriate
4696 internal representation for a floating-point number.
4697 @var{type} is a character from @var{FLT_CHARS[]} that describes
4698 what kind of floating point number is wanted; @var{outputPTR}
4699 is a pointer to an array that the result should be stored in;
4700 and @var{sizePTR} is a pointer to an integer where the size (in
4701 bytes) of the result should be stored. This routine should
4702 return an error message, or an empty string (not (char *)0) for
4705 @item int md_short_jump_size;
4706 This variable holds the (maximum) size in bytes of a short (16
4707 bit or so) jump created by @code{md_create_short_jump()}. This
4708 variable is used as part of the broken-word feature, and isn't
4709 needed if the assembler is compiled with
4710 @samp{-DWORKING_DOT_WORD}.
4712 @item int md_long_jump_size;
4713 This variable holds the (maximum) size in bytes of a long (32
4714 bit or so) jump created by @code{md_create_long_jump()}. This
4715 variable is used as part of the broken-word feature, and isn't
4716 needed if the assembler is compiled with
4717 @samp{-DWORKING_DOT_WORD}.
4719 @item void md_create_short_jump(char *resultPTR,long from_addr,
4720 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
4721 This function emits a jump from @var{from_addr} to @var{to_addr} in
4722 the array of bytes pointed to by @var{resultPTR}. If this creates a
4723 type of jump that must be relocated, this function should call
4724 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
4725 emitted by this function may be smaller than @var{md_short_jump_size},
4726 but it must never create a larger one.
4727 (If it creates a smaller jump, the extra bytes of memory will not be
4728 used.) This function is used as part of the broken-word feature,
4729 and isn't needed if the assembler is compiled with
4730 @samp{-DWORKING_DOT_WORD}.@refill
4732 @item void md_create_long_jump(char *ptr,long from_addr,
4733 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
4734 This function is similar to the previous function,
4735 @code{md_create_short_jump()}, except that it creates a long
4736 jump instead of a short one. This function is used as part of
4737 the broken-word feature, and isn't needed if the assembler is
4738 compiled with @samp{-DWORKING_DOT_WORD}.
4740 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
4741 This function does the initial setting up for relaxation. This
4742 includes forcing references to still-undefined symbols to the
4743 appropriate addressing modes.
4745 @item relax_typeS md_relax_table[];
4746 (relax_typeS is defined in md.h)
4747 This array describes the various machine dependent states a
4748 frag may be in before relaxation. You will need one group of
4749 entries for each type of addressing mode you intend to relax.
4751 @item void md_convert_frag(fragS *fragPTR)
4752 (@var{fragS} is defined in @file{as.h})
4753 This routine does the required cleanup after relaxation.
4754 Relaxation has changed the type of the frag to a type that can
4755 reach its destination. This function should adjust the opcode
4756 of the frag to use the appropriate addressing mode.
4757 @var{fragPTR} points to the frag to clean up.
4759 @item void md_end(void)
4760 This function is called just before the assembler exits. It
4761 need not free up memory unless the operating system doesn't do
4762 it automatically on exit. (In which case you'll also have to
4763 track down all the other places where the assembler allocates
4764 space but never frees it.)
4768 @section External Variables You will Need to Use
4770 You will need to refer to or change the following external variables
4771 from within the machine-dependent part of the assembler.
4774 @item extern char flagseen[];
4775 This array holds non-zero values in locations corresponding to
4776 the options that were on the command line. Thus, if the
4777 assembler was called with @samp{-W}, @var{flagseen['W']} would
4780 @item extern fragS *frag_now;
4781 This pointer points to the current frag--the frag that bytes
4782 are currently being added to. If nothing else, you will need
4783 to pass it as an argument to various machine-independent
4784 functions. It is maintained automatically by the
4785 frag-manipulating functions; you should never have to change it
4788 @item extern LITTLENUM_TYPE generic_bignum[];
4789 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
4790 This is where @dfn{bignums}--numbers larger than 32 bits--are
4791 returned when they are encountered in an expression. You will
4792 need to use this if you need to implement directives (or
4793 anything else) that must deal with these large numbers.
4794 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
4795 @file{as.h}, and have a positive @code{X_add_number}. The
4796 @code{X_add_number} of a @code{bignum} is the number of
4797 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
4800 @item extern FLONUM_TYPE generic_floating_point_number;
4801 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
4802 The is where @dfn{flonums}--floating-point numbers within
4803 expressions--are returned. @code{Flonums} are of @code{segT}
4804 @code{SEG_BIG}, and have a negative @code{X_add_number}.
4805 @code{Flonums} are returned in a generic format. You will have
4806 to write a routine to turn this generic format into the
4807 appropriate floating-point format for your machine.
4809 @item extern int need_pass_2;
4810 If this variable is non-zero, the assembler has encountered an
4811 expression that cannot be assembled in a single pass. Since
4812 the second pass isn't implemented, this flag means that the
4813 assembler is punting, and is only looking for additional syntax
4814 errors. (Or something like that.)
4816 @item extern segT now_seg;
4817 This variable holds the value of the segment the assembler is
4818 currently assembling into.
4822 @section External functions will you need
4824 You will find the following external functions useful (or
4825 indispensable) when you're writing the machine-dependent part
4830 @item char *frag_more(int bytes)
4831 This function allocates @var{bytes} more bytes in the current
4832 frag (or starts a new frag, if it can't expand the current frag
4833 any more.) for you to store some object-file bytes in. It
4834 returns a pointer to the bytes, ready for you to store data in.
4836 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
4837 This function stores a relocation fixup to be acted on later.
4838 @var{frag} points to the frag the relocation belongs in;
4839 @var{where} is the location within the frag where the relocation begins;
4840 @var{size} is the size of the relocation, and is usually 1 (a single byte),
4841 2 (sixteen bits), or 4 (a longword).
4842 The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
4843 at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the
4844 location is subtracted from the result. A relocation entry is also added
4845 to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
4846 @var{offset} may be NULL.@refill
4848 @item char *frag_var(relax_stateT type, int max_chars, int var,
4849 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
4850 This function creates a machine-dependent frag of type @var{type}
4851 (usually @code{rs_machine_dependent}).
4852 @var{max_chars} is the maximum size in bytes that the frag may grow by;
4853 @var{var} is the current size of the variable end of the frag;
4854 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
4855 @var{md_relax_table[]} during @code{relaxation}.
4856 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
4857 @var{opcode} points into a byte whose value may have to be modified if the
4858 addressing mode used by this frag changes. It typically points into the
4859 @var{fr_literal[]} of the previous frag, and is used to point to a location
4860 that @code{md_convert_frag()}, may have to change.@refill
4862 @item void frag_wane(fragS *fragPTR)
4863 This function is useful from within @code{md_convert_frag}. It
4864 changes a frag to type rs_fill, and sets the variable-sized
4865 piece of the frag to zero. The frag will never change in size
4868 @item segT expression(expressionS *retval)
4869 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
4870 This function parses the string pointed to by the external char
4871 pointer @var{input_line_pointer}, and returns the segment-type
4872 of the expression. It also stores the results in the
4873 @var{expressionS} pointed to by @var{retval}.
4874 @var{input_line_pointer} is advanced to point past the end of
4875 the expression. (@var{input_line_pointer} is used by other
4876 parts of the assembler. If you modify it, be sure to restore
4877 it to its original value.)
4879 @item as_warn(char *message,@dots{})
4880 If warning messages are disabled, this function does nothing.
4881 Otherwise, it prints out the current file name, and the current
4882 line number, then uses @code{fprintf} to print the
4883 @var{message} and any arguments it was passed.
4885 @item as_bad(char *message,@dots{})
4886 This function should be called when @code{_AS__} encounters
4887 conditions that are bad enough that @code{_AS__} should not
4888 produce an object file, but should continue reading input and
4889 printing warning and bad error messages.
4891 @item as_fatal(char *message,@dots{})
4892 This function prints out the current file name and line number,
4893 prints the word @samp{FATAL:}, then uses @code{fprintf} to
4894 print the @var{message} and any arguments it was passed. Then
4895 the assembler exits. This function should only be used for
4896 serious, unrecoverable errors.
4898 @item void float_const(int float_type)
4899 This function reads floating-point constants from the current
4900 input line, and calls @code{md_atof} to assemble them. It is
4901 useful as the function to call for the directives
4902 @samp{.single}, @samp{.double}, @samp{.float}, etc.
4903 @var{float_type} must be a character from @var{FLT_CHARS}.
4905 @item void demand_empty_rest_of_line(void);
4906 This function can be used by machine-dependent directives to
4907 make sure the rest of the input line is empty. It prints a
4908 warning message if there are additional characters on the line.
4910 @item long int get_absolute_expression(void)
4911 This function can be used by machine-dependent directives to
4912 read an absolute number from the current input line. It
4913 returns the result. If it isn't given an absolute expression,
4914 it prints a warning message and returns zero.
4919 @section The concept of Frags
4921 This assembler works to optimize the size of certain addressing
4922 modes. (e.g. branch instructions) This means the size of many
4923 pieces of object code cannot be determined until after assembly
4924 is finished. (This means that the addresses of symbols cannot be
4925 determined until assembly is finished.) In order to do this,
4926 @code{_AS__} stores the output bytes as @dfn{frags}.
4928 Here is the definition of a frag (from @file{as.h})
4934 relax_stateT fr_type;
4935 relax_substateT fr_substate;
4936 unsigned long fr_address;
4938 struct symbol *fr_symbol;
4940 struct frag *fr_next;
4947 is the size of the fixed-size piece of the frag.
4950 is the maximum (?) size of the variable-sized piece of the frag.
4953 is the type of the frag.
4958 rs_machine_dependent
4961 This stores the type of machine-dependent frag this is. (what
4962 kind of addressing mode is being used, and what size is being
4966 @var{fr_address} is only valid after relaxation is finished.
4967 Before relaxation, the only way to store an address is (pointer
4968 to frag containing the address) plus (offset into the frag).
4971 This contains a number, whose meaning depends on the type of
4973 for machine_dependent frags, this contains the offset from
4974 fr_symbol that the frag wants to go to. Thus, for branch
4975 instructions it is usually zero. (unless the instruction was
4976 @samp{jba foo+12} or something like that.)
4979 for machine_dependent frags, this points to the symbol the frag
4983 This points to the location in the frag (or in a previous frag)
4984 of the opcode for the instruction that caused this to be a frag.
4985 @var{fr_opcode} is needed if the actual opcode must be changed
4986 in order to use a different form of the addressing mode.
4987 (For example, if a conditional branch only comes in size tiny,
4988 a large-size branch could be implemented by reversing the sense
4989 of the test, and turning it into a tiny branch over a large jump.
4990 This would require changing the opcode.)
4992 @var{fr_literal} is a variable-size array that contains the
4993 actual object bytes. A frag consists of a fixed size piece of
4994 object data, (which may be zero bytes long), followed by a
4995 piece of object data whose size may not have been determined
4996 yet. Other information includes the type of the frag (which
4997 controls how it is relaxed),
5000 This is the next frag in the singly-linked list. This is
5001 usually only needed by the machine-independent part of
5007 @node License, , Machine Dependent, Top
5008 @unnumbered GNU GENERAL PUBLIC LICENSE
5009 @center Version 1, February 1989
5012 Copyright @copyright{} 1989 Free Software Foundation, Inc.
5013 675 Mass Ave, Cambridge, MA 02139, USA
5015 Everyone is permitted to copy and distribute verbatim copies
5016 of this license document, but changing it is not allowed.
5019 @unnumberedsec Preamble
5021 The license agreements of most software companies try to keep users
5022 at the mercy of those companies. By contrast, our General Public
5023 License is intended to guarantee your freedom to share and change free
5024 software---to make sure the software is free for all its users. The
5025 General Public License applies to the Free Software Foundation's
5026 software and to any other program whose authors commit to using it.
5027 You can use it for your programs, too.
5029 When we speak of free software, we are referring to freedom, not
5030 price. Specifically, the General Public License is designed to make
5031 sure that you have the freedom to give away or sell copies of free
5032 software, that you receive source code or can get it if you want it,
5033 that you can change the software or use pieces of it in new free
5034 programs; and that you know you can do these things.
5036 To protect your rights, we need to make restrictions that forbid
5037 anyone to deny you these rights or to ask you to surrender the rights.
5038 These restrictions translate to certain responsibilities for you if you
5039 distribute copies of the software, or if you modify it.
5041 For example, if you distribute copies of a such a program, whether
5042 gratis or for a fee, you must give the recipients all the rights that
5043 you have. You must make sure that they, too, receive or can get the
5044 source code. And you must tell them their rights.
5046 We protect your rights with two steps: (1) copyright the software, and
5047 (2) offer you this license which gives you legal permission to copy,
5048 distribute and/or modify the software.
5050 Also, for each author's protection and ours, we want to make certain
5051 that everyone understands that there is no warranty for this free
5052 software. If the software is modified by someone else and passed on, we
5053 want its recipients to know that what they have is not the original, so
5054 that any problems introduced by others will not reflect on the original
5055 authors' reputations.
5057 The precise terms and conditions for copying, distribution and
5058 modification follow.
5061 @unnumberedsec TERMS AND CONDITIONS
5064 @center TERMS AND CONDITIONS
5069 This License Agreement applies to any program or other work which
5070 contains a notice placed by the copyright holder saying it may be
5071 distributed under the terms of this General Public License. The
5072 ``Program'', below, refers to any such program or work, and a ``work based
5073 on the Program'' means either the Program or any work containing the
5074 Program or a portion of it, either verbatim or with modifications. Each
5075 licensee is addressed as ``you''.
5078 You may copy and distribute verbatim copies of the Program's source
5079 code as you receive it, in any medium, provided that you conspicuously and
5080 appropriately publish on each copy an appropriate copyright notice and
5081 disclaimer of warranty; keep intact all the notices that refer to this
5082 General Public License and to the absence of any warranty; and give any
5083 other recipients of the Program a copy of this General Public License
5084 along with the Program. You may charge a fee for the physical act of
5085 transferring a copy.
5088 You may modify your copy or copies of the Program or any portion of
5089 it, and copy and distribute such modifications under the terms of Paragraph
5090 1 above, provided that you also do the following:
5094 cause the modified files to carry prominent notices stating that
5095 you changed the files and the date of any change; and
5098 cause the whole of any work that you distribute or publish, that
5099 in whole or in part contains the Program or any part thereof, either
5100 with or without modifications, to be licensed at no charge to all
5101 third parties under the terms of this General Public License (except
5102 that you may choose to grant warranty protection to some or all
5103 third parties, at your option).
5106 If the modified program normally reads commands interactively when
5107 run, you must cause it, when started running for such interactive use
5108 in the simplest and most usual way, to print or display an
5109 announcement including an appropriate copyright notice and a notice
5110 that there is no warranty (or else, saying that you provide a
5111 warranty) and that users may redistribute the program under these
5112 conditions, and telling the user how to view a copy of this General
5116 You may charge a fee for the physical act of transferring a
5117 copy, and you may at your option offer warranty protection in
5121 Mere aggregation of another independent work with the Program (or its
5122 derivative) on a volume of a storage or distribution medium does not bring
5123 the other work under the scope of these terms.
5126 You may copy and distribute the Program (or a portion or derivative of
5127 it, under Paragraph 2) in object code or executable form under the terms of
5128 Paragraphs 1 and 2 above provided that you also do one of the following:
5132 accompany it with the complete corresponding machine-readable
5133 source code, which must be distributed under the terms of
5134 Paragraphs 1 and 2 above; or,
5137 accompany it with a written offer, valid for at least three
5138 years, to give any third party free (except for a nominal charge
5139 for the cost of distribution) a complete machine-readable copy of the
5140 corresponding source code, to be distributed under the terms of
5141 Paragraphs 1 and 2 above; or,
5144 accompany it with the information you received as to where the
5145 corresponding source code may be obtained. (This alternative is
5146 allowed only for noncommercial distribution and only if you
5147 received the program in object code or executable form alone.)
5150 Source code for a work means the preferred form of the work for making
5151 modifications to it. For an executable file, complete source code means
5152 all the source code for all modules it contains; but, as a special
5153 exception, it need not include source code for modules which are standard
5154 libraries that accompany the operating system on which the executable
5155 file runs, or for standard header files or definitions files that
5156 accompany that operating system.
5159 You may not copy, modify, sublicense, distribute or transfer the
5160 Program except as expressly provided under this General Public License.
5161 Any attempt otherwise to copy, modify, sublicense, distribute or transfer
5162 the Program is void, and will automatically terminate your rights to use
5163 the Program under this License. However, parties who have received
5164 copies, or rights to use copies, from you under this General Public
5165 License will not have their licenses terminated so long as such parties
5166 remain in full compliance.
5169 By copying, distributing or modifying the Program (or any work based
5170 on the Program) you indicate your acceptance of this license to do so,
5171 and all its terms and conditions.
5174 Each time you redistribute the Program (or any work based on the
5175 Program), the recipient automatically receives a license from the original
5176 licensor to copy, distribute or modify the Program subject to these
5177 terms and conditions. You may not impose any further restrictions on the
5178 recipients' exercise of the rights granted herein.
5181 The Free Software Foundation may publish revised and/or new versions
5182 of the General Public License from time to time. Such new versions will
5183 be similar in spirit to the present version, but may differ in detail to
5184 address new problems or concerns.
5186 Each version is given a distinguishing version number. If the Program
5187 specifies a version number of the license which applies to it and ``any
5188 later version'', you have the option of following the terms and conditions
5189 either of that version or of any later version published by the Free
5190 Software Foundation. If the Program does not specify a version number of
5191 the license, you may choose any version ever published by the Free Software
5195 If you wish to incorporate parts of the Program into other free
5196 programs whose distribution conditions are different, write to the author
5197 to ask for permission. For software which is copyrighted by the Free
5198 Software Foundation, write to the Free Software Foundation; we sometimes
5199 make exceptions for this. Our decision will be guided by the two goals
5200 of preserving the free status of all derivatives of our free software and
5201 of promoting the sharing and reuse of software generally.
5204 @heading NO WARRANTY
5211 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
5212 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
5213 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
5214 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
5215 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
5216 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
5217 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
5218 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
5219 REPAIR OR CORRECTION.
5222 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
5223 ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
5224 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
5225 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
5226 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
5227 LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
5228 SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
5229 WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
5230 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
5234 @heading END OF TERMS AND CONDITIONS
5237 @center END OF TERMS AND CONDITIONS
5241 @unnumberedsec Applying These Terms to Your New Programs
5243 If you develop a new program, and you want it to be of the greatest
5244 possible use to humanity, the best way to achieve this is to make it
5245 free software which everyone can redistribute and change under these
5248 To do so, attach the following notices to the program. It is safest to
5249 attach them to the start of each source file to most effectively convey
5250 the exclusion of warranty; and each file should have at least the
5251 ``copyright'' line and a pointer to where the full notice is found.
5254 @var{one line to give the program's name and a brief idea of what it does.}
5255 Copyright (C) 19@var{yy} @var{name of author}
5257 This program is free software; you can redistribute it and/or modify
5258 it under the terms of the GNU General Public License as published by
5259 the Free Software Foundation; either version 1, or (at your option)
5262 This program is distributed in the hope that it will be useful,
5263 but WITHOUT ANY WARRANTY; without even the implied warranty of
5264 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
5265 GNU General Public License for more details.
5267 You should have received a copy of the GNU General Public License
5268 along with this program; if not, write to the Free Software
5269 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
5272 Also add information on how to contact you by electronic and paper mail.
5274 If the program is interactive, make it output a short notice like this
5275 when it starts in an interactive mode:
5278 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
5279 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
5280 This is free software, and you are welcome to redistribute it
5281 under certain conditions; type `show c' for details.
5284 The hypothetical commands `show w' and `show c' should show the
5285 appropriate parts of the General Public License. Of course, the
5286 commands you use may be called something other than `show w' and `show
5287 c'; they could even be mouse-clicks or menu items---whatever suits your
5290 You should also get your employer (if you work as a programmer) or your
5291 school, if any, to sign a ``copyright disclaimer'' for the program, if
5292 necessary. Here is a sample; alter the names:
5295 Yoyodyne, Inc., hereby disclaims all copyright interest in the
5296 program `Gnomovision' (a program to direct compilers to make passes
5297 at assemblers) written by James Hacker.
5299 @var{signature of Ty Coon}, 1 April 1989
5300 Ty Coon, President of Vice
5303 That's all there is to it!