8 _if__(_AMD29K__ && !_ALL_ARCH__)
9 @setfilename as-29k.info
10 _fi__(_AMD29K__ && !_ALL_ARCH__)
11 _if__(_I960__ && !_ALL_ARCH__)
12 @setfilename as-960.info
13 _fi__(_I960__ && !_ALL_ARCH__)
14 _if__(_M680X0__ && !_ALL_ARCH__)
15 @setfilename as-m680x0.info
16 _fi__(_M680X0__ && !_ALL_ARCH__)
18 @c NOTE: this manual is marked up for preprocessing with a collection
19 @c of m4 macros called "pretex.m4". If you see <_if__> and <_fi__>
20 @c scattered around the source, you have the full source before
21 @c preprocessing; if you don't, you have the source configured for
22 @c _HOST__ architectures (and you can of course get the full source,
23 @c with all configurations, from wherever you got this).
26 THIS IS THE FULL SOURCE. The full source needs to be run through m4
27 before either tex- or info- formatting: for example,
28 m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
29 will produce (assuming your path finds either GNU or SysV m4; Berkeley
30 won't do) a file suitable for formatting. See the text in "pretex.m4"
31 for a fuller explanation (and the macro definitions).
37 This file documents the GNU Assembler "_AS__".
39 Copyright (C) 1991 Free Software Foundation, Inc.
41 Permission is granted to make and distribute verbatim copies of
42 this manual provided the copyright notice and this permission notice
43 are preserved on all copies.
46 Permission is granted to process this file through Tex and print the
47 results, provided the printed document carries copying permission
48 notice identical to this one except for the removal of this paragraph
49 (this paragraph not being relevant to the printed manual).
52 Permission is granted to copy and distribute modified versions of this
53 manual under the conditions for verbatim copying, provided also that the
54 section entitled ``GNU General Public License'' is included exactly as
55 in the original, and provided that the entire resulting derived work is
56 distributed under the terms of a permission notice identical to this
59 Permission is granted to copy and distribute translations of this manual
60 into another language, under the above conditions for modified versions,
61 except that the section entitled ``GNU General Public License'' may be
62 included in a translation approved by the author instead of in the
69 @setchapternewpage odd
74 @settitle Using _AS__ (_HOST__)
78 @subtitle{The GNU Assembler}
80 @subtitle{for the _HOST__ family}
85 The Free Software Foundation Inc. thanks The Nice Computer
86 Company of Australia for loaning Dean Elsner to write the
87 first (Vax) version of @code{as} for Project GNU.
88 The proprietors, management and staff of TNCCA thank FSF for
89 distracting the boss while they got some work
92 @author{Dean Elsner, Jay Fenlason & friends}
93 @author{revised by Roland Pesch for Cygnus Support}
97 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
98 \xdef\manvers{\$Revision$} % For use in headers, footers too
100 \hfill Cygnus Support\par
102 \hfill \TeX{}info \texinfoversion\par
104 %"boxit" macro for figures:
105 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
106 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
107 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
108 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
109 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
112 @vskip 0pt plus 1filll
113 Copyright @copyright{} 1991 Free Software Foundation, Inc.
115 Permission is granted to make and distribute verbatim copies of
116 this manual provided the copyright notice and this permission notice
117 are preserved on all copies.
119 Permission is granted to copy and distribute modified versions of this
120 manual under the conditions for verbatim copying, provided also that the
121 section entitled ``GNU General Public License'' is included exactly as
122 in the original, and provided that the entire resulting derived work is
123 distributed under the terms of a permission notice identical to this
126 Permission is granted to copy and distribute translations of this manual
127 into another language, under the above conditions for modified versions,
128 except that the section entitled ``GNU General Public License'' may be
129 included in a translation approved by the author instead of in the
135 This file is a user guide to the GNU assembler @code{_AS__}.
137 This version of the file describes @code{_AS__} configured to generate
138 code for _HOST__ architectures.
144 This manual is a user guide to the GNU assembler @code{_AS__}.
146 This version of the manual describes @code{_AS__} configured to generate
147 code for _HOST__ architectures.
152 @section Invoking @code{_AS__}
154 Here is a brief summary of how to invoke @code{_AS__}. For details,
157 @c We don't use @deffn and friends for the following because they seem
158 @c to be limited to one line for the header.
160 _AS__ [ -D ] [ -f ] [ -I @var{path} ] [ -k ] [ -L ]
161 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
163 @c am29k has no machine-dependent assembler options
166 @c see md_parse_option in i960.c
167 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
171 [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
173 [ -- | @var{files} @dots{} ]
179 This option is accepted only for script compatibility with calls to
180 other assemblers; it has no effect on @code{_AS__}.
183 ``fast''---skip preprocessing (assume source is compiler output)
186 Add @var{path} to the search list for @code{.include} directives
189 _if__(_AMD29K__ || _I960__)
190 This option is accepted but has no effect on the _HOST__ family.
191 _fi__(_AMD29K__ || _I960__)
192 _if__(!(_AMD29K__||_I960__))
193 Issue warnings when difference tables altered for long displacements
194 _fi__(!(_AMD29K__||_I960__))
197 Keep (in symbol table) local symbols, starting with @samp{L}
199 @item -o @var{objfile}
200 Name the object-file output from @code{_AS__}
203 Fold data segment into text segment
206 Suppress warning messages
209 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
210 Specify which variant of the 960 architecture is the target.
213 Add code to collect statistics about branches taken.
216 Do not alter compare-and-branch instructions for long displaements;
222 Shorten references to undefined symbols, to one word instead of two
224 @item -mc68000 | -mc68010 | -mc68020
225 Specify what processor in the 68000 family is the target (default 68020)
228 @item -- | @var{files} @dots{}
229 Source files to assemble, or standard input
232 @node Manual, GNU Assembler, Invoking, Overview
233 @section Structure of this Manual
234 This document is intended to describe what you need to know to use
235 @code{_AS__}. We cover the syntax expected in source files, including
236 notation for symbols, constants, and expressions; the directives that
237 @code{_AS__} understands; and of course how to invoke @code{_AS__}.
240 We also cover special features in the _HOST__
241 configuration of @code{_AS__}, including assembler directives.
244 This document also describes some of the machine-dependent features of
245 various flavors of the assembler.
248 This document also describes how the assembler works internally, and
249 provides some information that may be useful to people attempting to
250 port the assembler to another machine.
254 On the other hand, this manual is @emph{not} intended as an introduction
255 to programming in assembly language---let alone programming in general!
256 In a similar vein, we make no attempt to introduce the machine
257 architecture; we do @emph{not} describe the instruction set, standard
258 mnemonics, registers or addressing modes that are standard to a
259 particular architecture. You may want to consult the manufacturer's
260 machine architecture manual for this information.
263 @c I think this is premature---pesch@cygnus.com, 17jan1991
265 Throughout this document, we assume that you are running @dfn{GNU},
266 the portable operating system from the @dfn{Free Software
267 Foundation, Inc.}. This restricts our attention to certain kinds of
268 computer (in particular, the kinds of computers that GNU can run on);
269 once this assumption is granted examples and definitions need less
272 @code{_AS__} is part of a team of programs that turn a high-level
273 human-readable series of instructions into a low-level
274 computer-readable series of instructions. Different versions of
275 @code{_AS__} are used for different kinds of computer.
278 @c There used to be a section "Terminology" here, which defined
279 @c "contents", "byte", "word", and "long". Defining "word" to any
280 @c particular size is confusing when the .word directive may generate 16
281 @c bits on one machine and 32 bits on another; in general, for the user
282 @c version of this manual, none of these terms seem essential to define.
283 @c They were used very little even in the former draft of the manual;
284 @c this draft makes an effort to avoid them (except in names of
287 @node GNU Assembler,,,
288 @section _AS__, the GNU Assembler
289 GNU @code{as} is really a family of assemblers.
291 This manual describes @samp{_AS__}, a member of that family which is
292 configured for the _HOST__ architectures.
294 If you use (or have used) the GNU assembler on another architecture, you
295 should find a fairly similar environment. Each version has much in
296 common with the others, including object file formats, most assembler
297 directives (often called @dfn{pseudo-ops)} and assembler syntax.@refill
299 @code{_AS__} is primarily intended to assemble the output of the GNU C
300 compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless,
301 we've tried to make @code{_AS__} assemble correctly everything that the native
304 Any exceptions are documented explicitly (@pxref{_MACH_DEP__}).
306 _if__(_ALL_ARCH__||_M680X0__)
307 This doesn't mean @code{_AS__} always uses the same syntax as another
308 assembler for the same architecture; for example, we know of several
309 incompatible versions of 680x0 assembly language syntax.
310 _fi__(_ALL_ARCH__||_M680X0__)
312 Unlike older assemblers, @code{_AS__} is designed to assemble a source
313 program in one pass of the source file. This has a subtle impact on the
314 @kbd{.org} directive (@pxref{Org}).
316 @node Object Formats,,,
317 @section Object File Formats
318 The GNU assembler can be configured to produce several alternative
322 @code{_AS__} is configured to produce @code{a.out} format object
326 @code{_AS__} can be configured to produce either @code{b.out} or COFF
331 @node Command Line,,,
332 @section Command Line
334 After the program name @code{_AS__}, the command line may contain
335 options and file names. Options may be in any order, and may be
336 before, after, or between file names. The order of file names is
339 @file{--} (two hyphens) by itself names the standard input file
340 explicitly, as one of the files for @code{_AS__} to assemble.
342 Except for @samp{--} any command line argument that begins with a
343 hyphen (@samp{-}) is an option. Each option changes the behavior of
344 @code{_AS__}. No option changes the way another option works. An
345 option is a @samp{-} followed by one or more letters; the case of
346 the letter is important. All options are optional.
348 Some options expect exactly one file name to follow them. The file
349 name may either immediately follow the option's letter (compatible
350 with older assemblers) or it may be the next command argument (GNU
351 standard). These two command lines are equivalent:
354 _AS__ -o my-object-file.o mumble.s
355 _AS__ -omy-object-file.o mumble.s
358 @node Input Files, Object, Command Line, Overview
361 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
362 describe the program input to one run of @code{_AS__}. The program may
363 be in one or more files; how the source is partitioned into files
364 doesn't change the meaning of the source.
366 @c I added "con" prefix to "catenation" just to prove I can overcome my
367 @c APL training... pesch@cygnus.com
368 The source program is a concatenation of the text in all the files, in the
371 Each time you run @code{_AS__} it assembles exactly one source
372 program. The source program is made up of one or more files.
373 (The standard input is also a file.)
375 You give @code{_AS__} a command line that has zero or more input file
376 names. The input files are read (from left file name to right). A
377 command line argument (in any position) that has no special meaning
378 is taken to be an input file name.
380 If @code{_AS__} is given no file names it attempts to read one input file
381 from the @code{_AS__} standard input, which is normally your terminal. You
382 may have to type @key{ctl-D} to tell @code{_AS__} there is no more program
385 Use @samp{--} if you need to explicitly name the standard input file
386 in your command line.
388 If the source is empty, @code{_AS__} will produce a small, empty object
391 @node Filenames, , Input Files, Input Files
392 @subsection Filenames and Line-numbers
393 There are two ways of locating a line in the input file (or files) and both
394 are used in reporting error messages. One way refers to a line
395 number in a physical file; the other refers to a line number in a
398 @dfn{Physical files} are those files named in the command line given
401 @dfn{Logical files} are simply names declared explicitly by assembler
402 directives; they bear no relation to physical files. Logical file names
403 help error messages reflect the original source file, when @code{_AS__}
404 source is itself synthesized from other files. @xref{App-File}.
406 @node Object, Errors, Input Files, Overview
407 @section Output (Object) File
408 Every time you run @code{_AS__} it produces an output file, which is
409 your assembly language program translated into numbers. This file
410 is the object file, named @code{a.out} unless you tell @code{_AS__} to
411 give it another name by using the @code{-o} option. Conventionally,
412 object file names end with @file{.o}. The default name of
413 @file{a.out} is used for historical reasons: older assemblers were
414 capable of assembling self-contained programs directly into a
416 @c This may still work, but hasn't been tested.
418 The object file is meant for input to the linker @code{_LD__}. It contains
419 assembled program code, information to help @code{_LD__} integrate
420 the assembled program into a runnable file, and (optionally) symbolic
421 information for the debugger.
423 @comment link above to some info file(s) like the description of a.out.
424 @comment don't forget to describe GNU info as well as Unix lossage.
426 @node Errors, Options, Object, Overview
427 @section Error and Warning Messages
429 @code{_AS__} may write warnings and error messages to the standard error
430 file (usually your terminal). This should not happen when @code{_AS__} is
431 run automatically by a compiler. Warnings report an assumption made so
432 that @code{_AS__} could keep assembling a flawed program; errors report a
433 grave problem that stops the assembly.
435 Warning messages have the format
437 file_name:@b{NNN}:Warning Message Text
439 @noindent(where @b{NNN} is a line number). If a logical file name has
440 been given (@pxref{App-File}) it is used for the filename, otherwise the
441 name of the current input file is used. If a logical line number was
449 then it is used to calculate the number printed,
450 otherwise the actual line in the current source file is printed. The
451 message text is intended to be self explanatory (in the grand Unix
454 Error messages have the format
456 file_name:@b{NNN}:FATAL:Error Message Text
458 The file name and line number are derived as for warning
459 messages. The actual message text may be rather less explanatory
460 because many of them aren't supposed to happen.
462 @node Options, , Errors, Overview
464 This section describes command-line options available in @emph{all}
465 versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific
468 @subsection @code{-D}
469 This option has no effect whatsoever, but it is accepted to make it more
470 likely that scripts written for other assemblers will also work with
473 @subsection Work Faster: @code{-f}
474 @samp{-f} should only be used when assembling programs written by a
475 (trusted) compiler. @samp{-f} stops the assembler from pre-processing
476 the input file(s) before assembling them.
478 @emph{Warning:} if the files actually need to be pre-processed (if they
479 contain comments, for example), @code{_AS__} will not work correctly if
483 @subsection @code{.include} search path: @code{-I} @var{path}
484 Use this option to add a @var{path} to the list of directories
485 @code{_AS__} will search for files specified in @code{.include} directives
486 (@pxref{Include}). You may use @code{-I} as many times as necessary to
487 include a variety of paths. The current working directory is always
488 searched first; after that, @code{_AS__} searches any @samp{-I} directories
489 in the same order as they were specified (left to right) on the command
492 @subsection Difference Tables: @code{-k}
493 _if__(_AMD29K__ || _I960__)
494 On the _HOST__ family, this option is allowed, but has no effect. It is
495 permitted for compatibility with the GNU assembler on other platforms,
496 where it can be used to warn when the assembler alters the machine code
497 generated for @samp{.word} directives in difference tables. The _HOST__
498 family does not have the addressing limitations that sometimes lead to this
499 alteration on other platforms.
500 _fi__(_AMD29K__ || _I960__)
502 _if__(! (_AMD29K__ || _I960__) )
503 @code{_AS__} sometimes alters the code emitted for directives of the form
504 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word}.
505 You can use the @samp{-k} option if you want a warning issued when this
507 _fi__(! (_AMD29K__ || _I960__) )
509 @subsection Include Local Labels: @code{-L}
510 Labels beginning with @samp{L} (upper case only) are called @dfn{local
511 labels}. @xref{Symbol Names}. Normally you don't see such labels when
512 debugging, because they are intended for the use of programs (like
513 compilers) that compose assembler programs, not for your notice.
514 Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't
515 normally debug with them.
517 This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols
518 in the object file. Usually if you do this you also tell the linker
519 @code{_LD__} to preserve symbols whose names begin with @samp{L}.
521 @subsection Name the Object File: @code{-o}
522 There is always one object file output when you run @code{_AS__}. By
523 default it has the name @file{a.out}. You use this option (which
524 takes exactly one filename) to give the object file a different name.
526 Whatever the object file is called, @code{_AS__} will overwrite any
527 existing file of the same name.
529 @subsection Join Data and Text Segments: @code{-R}
530 @code{-R} tells @code{_AS__} to write the object file as if all
531 data-segment data lives in the text segment. This is only done at
532 the very last moment: your binary data are the same, but data
533 segment parts are relocated differently. The data segment part of
534 your object file is zero bytes long because all it bytes are
535 appended to the text segment. (@xref{Segments}.)
537 When you specify @code{-R} it would be possible to generate shorter
538 address displacements (because we don't have to cross between text and
539 data segment). We refrain from doing this simply for compatibility with
540 older versions of @code{_AS__}. In future, @code{-R} may work this way.
542 @subsection Suppress Warnings: @code{-W}
543 @code{_AS__} should never give a warning or error message when
544 assembling compiler output. But programs written by people often
545 cause @code{_AS__} to give a warning that a particular assumption was
546 made. All such warnings are directed to the standard error file.
547 If you use this option, no warnings are issued. This option only
548 affects the warning messages: it does not change any particular of how
549 @code{_AS__} assembles your file. Errors, which stop the assembly, are
552 @node Syntax, Segments, Overview, Top
554 This chapter describes the machine-independent syntax allowed in a
555 source file. @code{_AS__} syntax is similar to what many other assemblers
556 use; it is inspired in BSD 4.2
561 assembler, except that @code{_AS__} does not assemble Vax bit-fields.
564 @node Pre-processing, Whitespace, Syntax, Syntax
565 @section Pre-processing
570 adjusts and removes extra whitespace. It leaves one space or tab before
571 the keywords on a line, and turns any other whitespace on the line into
575 removes all comments, replacing them with a single space, or an
576 appropriate number of newlines.
579 converts character constants into the appropriate numeric values.
582 Excess whitespace, comments, and character constants
583 cannot be used in the portions of the input text that are not
586 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
587 option is given, the input file will not be pre-processed. Within such
588 an input file, parts of the file can be pre-processed by putting a line
589 that says @code{#APP} before the text that should be pre-processed, and
590 putting a line that says @code{#NO_APP} after them. This feature is
591 mainly intend to support @code{asm} statements in compilers whose output
592 normally does not need to be pre-processed.
594 @node Whitespace, Comments, Pre-processing, Syntax
596 @dfn{Whitespace} is one or more blanks or tabs, in any order.
597 Whitespace is used to separate symbols, and to make programs neater
598 for people to read. Unless within character constants
599 (@pxref{Characters}), any whitespace means the same as exactly one
602 @node Comments, Symbol Intro, Whitespace, Syntax
604 There are two ways of rendering comments to @code{_AS__}. In both
605 cases the comment is equivalent to one space.
607 Anything from @samp{/*} through the next @samp{*/} is a comment.
608 This means you may not nest these comments.
612 The only way to include a newline ('\n') in a comment
613 is to use this sort of comment.
616 /* This sort of comment does not nest. */
619 Anything from the @dfn{line comment} character to the next newline
620 is considered a comment and is ignored. The line comment character is
621 _if__(_VAX__ || _I960__)
622 @samp{#} on the _HOST__;
623 _fi__(_VAX__ || _I960__)
625 @samp{|} on the 680x0;
628 @samp{;} for the AMD 29K family;
630 @pxref{_MACH_DEP__}. @refill
633 On some machines there are two different line comment characters. One
634 will only begin a comment if it is the first non-whitespace character on
635 a line, while the other will always begin a comment.
638 To be compatible with past assemblers a special interpretation is
639 given to lines that begin with @samp{#}. Following the @samp{#} an
640 absolute expression (@pxref{Expressions}) is expected: this will be
641 the logical line number of the @b{next} line. Then a string
642 (@xref{Strings}.) is allowed: if present it is a new logical file
643 name. The rest of the line, if any, should be whitespace.
645 If the first non-whitespace characters on the line are not numeric,
646 the line is ignored. (Just like a comment.)
648 # This is an ordinary comment.
649 # 42-6 "new_file_name" # New logical file name
650 # This is logical line # 36.
652 This feature is deprecated, and may disappear from future versions
655 @node Symbol Intro, Statements, Comments, Syntax
657 A @dfn{symbol} is one or more characters chosen from the set of all
658 letters (both upper and lower case), digits and the three characters
659 @samp{_.$}. No symbol may begin with a digit. Case is significant.
660 There is no length limit: all characters are significant. Symbols are
661 delimited by characters not in that set, or by the beginning of a file
662 (since the source program must end with a newline, the end of a file is
663 not a possible symbol delimiter). @xref{Symbols}.
665 @node Statements, Constants, Symbol Intro, Syntax
668 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
669 semicolon (@samp{;}). The newline or semicolon is considered part of
670 the preceding statement. Newlines and semicolons within character
671 constants are an exception: they don't end statements.
674 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
675 sign (@samp{@@}). The newline or at sign is considered part of the
676 preceding statement. Newlines and at signs within character constants
677 are an exception: they don't end statements.
680 It is an error to end any statement with end-of-file: the last
681 character of any input file should be a newline.@refill
683 You may write a statement on more than one line if you put a
684 backslash (@kbd{\}) immediately in front of any newlines within the
685 statement. When @code{_AS__} reads a backslashed newline both
686 characters are ignored. You can even put backslashed newlines in
687 the middle of symbol names without changing the meaning of your
690 An empty statement is allowed, and may include whitespace. It is ignored.
692 @c "key symbol" is not used elsewhere in the document; seems pedantic to
693 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
695 A statement begins with zero or more labels, optionally followed by a
696 key symbol which determines what kind of statement it is. The key
697 symbol determines the syntax of the rest of the statement. If the
698 symbol begins with a dot @samp{.} then the statement is an assembler
699 directive: typically valid for any computer. If the symbol begins with
700 a letter the statement is an assembly language @dfn{instruction}: it
701 will assemble into a machine language instruction.
703 Different versions of @code{_AS__} for different computers will
704 recognize different instructions. In fact, the same symbol may
705 represent a different instruction in a different computer's assembly
709 A label is a symbol immediately followed by a colon (@code{:}).
710 Whitespace before a label or after a colon is permitted, but you may not
711 have whitespace between a label's symbol and its colon. @xref{Labels}.
714 label: .directive followed by something
715 another$label: # This is an empty statement.
716 instruction operand_1, operand_2, @dots{}
719 @node Constants, , Statements, Syntax
721 A constant is a number, written so that its value is known by
722 inspection, without knowing any context. Like this:
724 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
725 .ascii "Ring the bell\7" # A string constant.
726 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
727 .float 0f-314159265358979323846264338327\
728 95028841971.693993751E-40 # - pi, a flonum.
731 @node Characters, Numbers, Constants, Constants
732 @subsection Character Constants
733 There are two kinds of character constants. A @dfn{character} stands
734 for one character in one byte and its value may be used in
735 numeric expressions. String constants (properly called string
736 @emph{literals}) are potentially many bytes and their values may not be
737 used in arithmetic expressions.
739 @node Strings, Chars, Characters, Characters
740 @subsubsection Strings
741 A @dfn{string} is written between double-quotes. It may contain
742 double-quotes or null characters. The way to get special characters
743 into a string is to @dfn{escape} these characters: precede them with
744 a backslash @samp{\} character. For example @samp{\\} represents
745 one backslash: the first @code{\} is an escape which tells
746 @code{_AS__} to interpret the second character literally as a backslash
747 (which prevents @code{_AS__} from recognizing the second @code{\} as an
748 escape character). The complete list of escapes follows.
752 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
754 Mnemonic for backspace; for ASCII this is octal code 010.
756 @c Mnemonic for EOText; for ASCII this is octal code 004.
758 Mnemonic for FormFeed; for ASCII this is octal code 014.
760 Mnemonic for newline; for ASCII this is octal code 012.
762 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
764 Mnemonic for carriage-Return; for ASCII this is octal code 015.
766 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
769 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
771 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
772 @c @item \x @var{digit} @var{digit} @var{digit}
773 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
774 @item \ @var{digit} @var{digit} @var{digit}
775 An octal character code. The numeric code is 3 octal digits.
776 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
777 for example, @code{\008} has the value 010, and @code{\009} the value 011.
779 Represents one @samp{\} character.
781 @c Represents one @samp{'} (accent acute) character.
782 @c This is needed in single character literals
783 @c (@xref{Characters}.) to represent
786 Represents one @samp{"} character. Needed in strings to represent
787 this character, because an unescaped @samp{"} would end the string.
788 @item \ @var{anything-else}
789 Any other character when escaped by @kbd{\} will give a warning, but
790 assemble as if the @samp{\} was not present. The idea is that if
791 you used an escape sequence you clearly didn't want the literal
792 interpretation of the following character. However @code{_AS__} has no
793 other interpretation, so @code{_AS__} knows it is giving you the wrong
794 code and warns you of the fact.
797 Which characters are escapable, and what those escapes represent,
798 varies widely among assemblers. The current set is what we think
799 the BSD 4.2 assembler recognizes, and is a subset of what most C
800 compilers recognize. If you are in doubt, don't use an escape
803 @node Chars, , Strings, Characters
804 @subsubsection Characters
805 A single character may be written as a single quote immediately
806 followed by that character. The same escapes apply to characters as
807 to strings. So if you want to write the character backslash, you
808 must write @kbd{'\\} where the first @code{\} escapes the second
809 @code{\}. As you can see, the quote is an acute accent, not a
810 grave accent. A newline
812 (or semicolon @samp{;})
815 (or at sign @samp{@@})
817 immediately following an acute accent is taken as a literal character
818 and does not count as the end of a statement. The value of a character
819 constant in a numeric expression is the machine's byte-wide code for
820 that character. @code{_AS__} assumes your character code is ASCII:
821 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
824 @subsection Number Constants
825 @code{_AS__} distinguishes three kinds of numbers according to how they
826 are stored in the target machine. @emph{Integers} are numbers that
827 would fit into an @code{int} in the C language. @emph{Bignums} are
828 integers, but they are stored in more than 32 bits. @emph{Flonums}
829 are floating point numbers, described below.
832 @subsubsection Integers
833 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
834 the binary digits @samp{01}.
836 An octal integer is @samp{0} followed by zero or more of the octal
837 digits (@samp{01234567}).
839 A decimal integer starts with a non-zero digit followed by zero or
840 more digits (@samp{0123456789}).
842 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
843 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
845 Integers have the usual values. To denote a negative integer, use
846 the prefix operator @samp{-} discussed under expressions
847 (@pxref{Prefix Ops}).
850 @subsubsection Bignums
851 A @dfn{bignum} has the same syntax and semantics as an integer
852 except that the number (or its negative) takes more than 32 bits to
853 represent in binary. The distinction is made because in some places
854 integers are permitted while bignums are not.
857 @subsubsection Flonums
858 A @dfn{flonum} represents a floating point number. The translation is
859 complex: a decimal floating point number from the text is converted by
860 @code{_AS__} to a generic binary floating point number of more than
861 sufficient precision. This generic floating point number is converted
862 to a particular computer's floating point format (or formats) by a
863 portion of @code{_AS__} specialized to that computer.
865 A flonum is written by writing (in order)
871 One of the letters @samp{DFPRSX} (in upper or lower case), to tell
872 @code{_AS__} the rest of the number is a flonum.
875 One of the letters @samp{DFT} (in upper or lower case), to tell
876 @code{_AS__} the rest of the number is a flonum.
878 _if__(!(_AMD29K__||_I960__))
879 A letter, to tell @code{_AS__} the rest of the number is a flonum. @kbd{e}
880 is recommended. Case is not important. (Any otherwise illegal letter
881 will work here, but that might be changed. Vax BSD 4.2 assembler seems
882 to allow any of @samp{defghDEFGH}.)
883 _fi__(!(_AMD29K__||_I960__))
885 An optional sign: either @samp{+} or @samp{-}.
887 An optional @dfn{integer part}: zero or more decimal digits.
889 An optional @dfn{fraction part}: @samp{.} followed by zero
890 or more decimal digits.
892 An optional exponent, consisting of:
895 An @samp{E} or @samp{e}.
896 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
897 @c principle this can perfectly well be different on different targets.
899 Optional sign: either @samp{+} or @samp{-}.
901 One or more decimal digits.
905 At least one of @var{integer part} or @var{fraction part} must be
906 present. The floating point number has the usual base-10 value.
908 @code{_AS__} does all processing using integers. Flonums are computed
909 independently of any floating point hardware in the computer running
913 @c Bit fields are written as a general facility but are also controlled
914 @c by a conditional-compilation flag---which is as of now (21mar91)
915 @c turned on only by the i960 config of GAS.
917 @subsubsection Bit Fields
918 You can also define numeric constants as @dfn{bit fields}.
919 specify two numbers separated by a colon---
921 @var{mask}:@var{value}
924 the first will act as a mask; @code{_AS__} will bitwise-and it with the
927 The resulting number is then packed
929 (in host-dependent byte order)
931 into a field whose width depends on which assembler directive has the
932 bit-field as its argument. Overflow (a result from the bitwise and
933 requiring more binary digits to represent) is not an error; instead,
934 more constants are generated, of the specified width, beginning with the
935 least significant digits.@refill
937 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
938 @code{.short}, and @code{.word} accept bit-field arguments.
941 @node Segments, Symbols, Syntax, Top
942 @chapter Segments and Relocation
944 @node Segs Background, _LD__ Segments, Segments, Segments
946 Roughly, a segment is a range of addresses, with no gaps; all data
947 ``in'' those addresses is treated the same for some particular purpose.
948 For example there may be a ``read only'' segment.
950 The linker @code{_LD__} reads many object files (partial programs) and
951 combines their contents to form a runnable program. When @code{_AS__}
952 emits an object file, the partial program is assumed to start at address
953 0. @code{_LD__} will assign the final addresses the partial program
954 occupies, so that different partial programs don't overlap. This is
955 actually an over-simplification, but it will suffice to explain how
956 @code{_AS__} uses segments.
958 @code{_LD__} moves blocks of bytes of your program to their run-time
959 addresses. These blocks slide to their run-time addresses as rigid
960 units; their length does not change and neither does the order of bytes
961 within them. Such a rigid unit is called a @emph{segment}. Assigning
962 run-time addresses to segments is called @dfn{relocation}. It includes
963 the task of adjusting mentions of object-file addresses so they refer to
964 the proper run-time addresses.
966 An object file written by @code{_AS__} has three segments, any of which may
967 be empty. These are named @dfn{text}, @dfn{data} and @dfn{bss}
973 @emph{Warning:} @code{_AS__} can only assign output to one of these
974 three segments, even when configured for COFF output; the
975 @code{.section} directive is not supported.
979 Within the object file, the text segment starts at address @code{0}, the
980 data segment follows, and the bss segment follows the data segment.
982 To let @code{_LD__} know which data will change when the segments are
983 relocated, and how to change that data, @code{_AS__} also writes to the
984 object file details of the relocation needed. To perform relocation
985 @code{_LD__} must know, each time an address in the object
989 Where in the object file is the beginning of this reference to
992 How long (in bytes) is this reference?
994 Which segment does the address refer to? What is the numeric value of
996 (@var{address}) @minus{} (@var{start-address of segment})?
999 Is the reference to an address ``Program-Counter relative''?
1002 In fact, every address @code{_AS__} ever uses is expressed as
1004 (@var{segment}) + (@var{offset into segment})
1007 Further, every expression @code{_AS__} computes is of this segmented
1008 nature. @dfn{Absolute expression} means an expression with segment
1009 ``absolute'' (@pxref{_LD__ Segments}). A @dfn{pass1 expression} means
1010 an expression with segment ``pass1'' (@pxref{_AS__ Segments}). In this
1011 manual we use the notation @{@var{segname} @var{N}@} to mean ``offset
1012 @var{N} into segment @var{segname}''.
1014 Apart from text, data and bss segments you need to know about the
1015 @dfn{absolute} segment. When @code{_LD__} mixes partial programs,
1016 addresses in the absolute segment remain unchanged. That is, address
1017 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}.
1018 Although two partial programs' data segments will not overlap addresses
1019 after linking, @emph{by definition} their absolute segments will overlap.
1020 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1021 address when the program is running as address @code{@{absolute@ 239@}} in any
1022 other partial program.
1024 The idea of segments is extended to the @dfn{undefined} segment. Any
1025 address whose segment is unknown at assembly time is by definition
1026 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1027 Since numbers are always defined, the only way to generate an undefined
1028 address is to mention an undefined symbol. A reference to a named
1029 common block would be such a symbol: its value is unknown at assembly
1030 time so it has segment @emph{undefined}.
1032 By analogy the word @emph{segment} is used to describe groups of segments in
1033 the linked program. @code{_LD__} puts all partial programs' text
1034 segments in contiguous addresses in the linked program. It is
1035 customary to refer to the @emph{text segment} of a program, meaning all
1036 the addresses of all partial program's text segments. Likewise for
1037 data and bss segments.
1039 Some segments are manipulated by @code{_LD__}; others are invented for
1040 use of @code{_AS__} and have no meaning except during assembly.
1042 @node _LD__ Segments, _AS__ Segments, Segs Background, Segments
1043 @section _LD__ Segments
1044 @code{_LD__} deals with just five kinds of segments, summarized below.
1050 These segments hold your program. @code{_AS__} and @code{_LD__} treat them as
1051 separate but equal segments. Anything you can say of one segment is
1052 true of the other. When the program is running, however, it is
1053 customary for the text segment to be unalterable. The
1054 text segment is often shared among processes: it will contain
1055 instructions, constants and the like. The data segment of a running
1056 program is usually alterable: for example, C variables would be stored
1057 in the data segment.
1060 This segment contains zeroed bytes when your program begins running. It
1061 is used to hold unitialized variables or common storage. The length of
1062 each partial program's bss segment is important, but because it starts
1063 out containing zeroed bytes there is no need to store explicit zero
1064 bytes in the object file. The bss segment was invented to eliminate
1065 those explicit zeros from object files.
1067 @item absolute segment
1068 Address 0 of this segment is always ``relocated'' to runtime address 0.
1069 This is useful if you want to refer to an address that @code{_LD__} must
1070 not change when relocating. In this sense we speak of absolute
1071 addresses being ``unrelocatable'': they don't change during relocation.
1073 @item undefined segment
1074 This ``segment'' is a catch-all for address references to objects not in
1075 the preceding segments.
1076 @c FIXME: ref to some other doc on obj-file formats could go here.
1080 An idealized example of the three relocatable segments follows. Memory
1081 addresses are on the horizontal axis.
1086 partial program # 1: |ttttt|dddd|00|
1093 partial program # 2: |TTT|DDD|000|
1096 +--+---+-----+--+----+---+-----+~~
1097 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1098 +--+---+-----+--+----+---+-----+~~
1100 addresses: 0 @dots{}
1105 {\it Partial program \#1: }
1107 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1108 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1110 {\it Partial program \#2:}
1112 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1113 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1115 {\it linked program: }
1117 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1118 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1119 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1120 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1128 @node _AS__ Segments, Sub-Segments, _LD__ Segments, Segments
1129 @section _AS__ Internal Segments
1130 These segments are invented for the internal use of @code{_AS__}. They
1131 have no meaning at run-time. You don't need to know about these
1132 segments except that they might be mentioned in the @code{_AS__} warning
1133 messages. These segments are invented to permit the value of every
1134 expression in your assembly language program to be a segmented
1138 @item absent segment
1139 An expression was expected and none was
1143 An internal assembler logic error has been
1144 found. This means there is a bug in the assembler.
1147 A @dfn{grand number} is a bignum or a flonum, but not an integer. If a
1148 number can't be written as a C @code{int} constant, it is a grand
1149 number. @code{_AS__} has to remember that a flonum or a bignum does not
1150 fit into 32 bits, and cannot be an argument (@pxref{Arguments}) in an
1151 expression: this is done by making a flonum or bignum be in segment
1152 grand. This is purely for internal @code{_AS__} convenience; grand
1153 segment behaves similarly to absolute segment.
1156 The expression was impossible to evaluate in the first pass. The
1157 assembler will attempt a second pass (second reading of the source) to
1158 evaluate the expression. Your expression mentioned an undefined symbol
1159 in a way that defies the one-pass (segment + offset in segment) assembly
1160 process. No compiler need emit such an expression.
1163 @emph{Warning:} the second pass is currently not implemented. @code{_AS__}
1164 will abort with an error message if one is required.
1167 @item difference segment
1168 As an assist to the C compiler, expressions of the forms
1170 (@var{undefined symbol}) @minus{} (@var{expression})
1171 @var{something} @minus{} (@var{undefined symbol})
1172 (@var{undefined symbol}) @minus{} (@var{undefined symbol})
1174 are permitted, and belong to the difference segment. @code{_AS__}
1175 re-evaluates such expressions after the source file has been read and
1176 the symbol table built. If by that time there are no undefined symbols
1177 in the expression then the expression assumes a new segment. The
1178 intention is to permit statements like
1179 @samp{.word label - base_of_table}
1180 to be assembled in one pass where both @code{label} and
1181 @code{base_of_table} are undefined. This is useful for compiling C and
1182 Algol switch statements, Pascal case statements, FORTRAN computed goto
1183 statements and the like.
1186 @node Sub-Segments, bss, _AS__ Segments, Segments
1187 @section Sub-Segments
1188 Assembled bytes fall into two segments: text and data.
1189 Because you may have groups of text or data that you want to end up near
1190 to each other in the object file, @code{_AS__} allows you to use
1191 @dfn{subsegments}. Within each segment, there can be numbered
1192 subsegments with values from 0 to 8192. Objects assembled into the same
1193 subsegment will be grouped with other objects in the same subsegment
1194 when they are all put into the object file. For example, a compiler
1195 might want to store constants in the text segment, but might not want to
1196 have them interspersed with the program being assembled. In this case,
1197 the compiler could issue a @code{text 0} before each section of code
1198 being output, and a @code{text 1} before each group of constants being
1201 Subsegments are optional. If you don't use subsegments, everything
1202 will be stored in subsegment number zero.
1204 _if__(!(_AMD29K__||_I960__))
1205 Each subsegment is zero-padded up to a multiple of four bytes.
1206 (Subsegments may be padded a different amount on different flavors
1208 _fi__(!(_AMD29K__||_I960__))
1210 @c Rich Pixley says padding here depends on target obj code format; that
1211 @c doesn't seem particularly useful to say without further elaboration,
1212 @c so for now I say nothing about it. If this is a generic BFD issue,
1213 @c these paragraphs might need to vanish from this manual, and be
1214 @c discussed in BFD chapter of binutils (or some such).
1217 On the AMD 29K family, no particular padding is added to segment sizes;
1218 _AS__ forces no alignment on this platform.
1220 Subsegments appear in your object file in numeric order, lowest numbered
1221 to highest. (All this to be compatible with other people's assemblers.)
1222 The object file contains no representation of subsegments; @code{_LD__} and
1223 other programs that manipulate object files will see no trace of them.
1224 They just see all your text subsegments as a text segment, and all your
1225 data subsegments as a data segment.
1227 To specify which subsegment you want subsequent statements assembled
1228 into, use a @samp{.text @var{expression}} or a @samp{.data
1229 @var{expression}} statement. @var{Expression} should be an absolute
1230 expression. (@xref{Expressions}.) If you just say @samp{.text}
1231 then @samp{.text 0} is assumed. Likewise @samp{.data} means
1232 @samp{.data 0}. Assembly begins in @code{text 0}.
1235 .text 0 # The default subsegment is text 0 anyway.
1236 .ascii "This lives in the first text subsegment. *"
1238 .ascii "But this lives in the second text subsegment."
1240 .ascii "This lives in the data segment,"
1241 .ascii "in the first data subsegment."
1243 .ascii "This lives in the first text segment,"
1244 .ascii "immediately following the asterisk (*)."
1247 Each segment has a @dfn{location counter} incremented by one for every
1248 byte assembled into that segment. Because subsegments are merely a
1249 convenience restricted to @code{_AS__} there is no concept of a subsegment
1250 location counter. There is no way to directly manipulate a location
1251 counter---but the @code{.align} directive will change it, and any label
1252 definition will capture its current value. The location counter of the
1253 segment that statements are being assembled into is said to be the
1254 @dfn{active} location counter.
1256 @node bss, , Sub-Segments, Segments
1257 @section bss Segment
1258 The bss segment is used for local common variable storage.
1259 You may allocate address space in the bss segment, but you may
1260 not dictate data to load into it before your program executes. When
1261 your program starts running, all the contents of the bss
1262 segment are zeroed bytes.
1264 Addresses in the bss segment are allocated with special directives;
1265 you may not assemble anything directly into the bss segment. Hence
1266 there are no bss subsegments. @xref{Comm}; @pxref{Lcomm}.
1268 @node Symbols, Expressions, Segments, Top
1270 Symbols are a central concept: the programmer uses symbols to name
1271 things, the linker uses symbols to link, and the debugger uses symbols
1275 @emph{Warning:} @code{_AS__} does not place symbols in the object file in
1276 the same order they were declared. This may break some debuggers.
1279 @node Labels, Setting Symbols, Symbols, Symbols
1281 A @dfn{label} is written as a symbol immediately followed by a colon
1282 @samp{:}. The symbol then represents the current value of the
1283 active location counter, and is, for example, a suitable instruction
1284 operand. You are warned if you use the same symbol to represent two
1285 different locations: the first definition overrides any other
1288 @node Setting Symbols, Symbol Names, Labels, Symbols
1289 @section Giving Symbols Other Values
1290 A symbol can be given an arbitrary value by writing a symbol, followed
1291 by an equals sign @samp{=}, followed by an expression
1292 (@pxref{Expressions}). This is equivalent to using the @code{.set}
1293 directive. @xref{Set}.
1295 @node Symbol Names, Dot, Setting Symbols, Symbols
1296 @section Symbol Names
1297 Symbol names begin with a letter or with one of @samp{$._}. That
1298 character may be followed by any string of digits, letters,
1299 underscores and dollar signs. Case of letters is significant:
1300 @code{foo} is a different symbol name than @code{Foo}.
1303 For the AMD 29K family, @samp{?} is also allowed in the
1304 body of a symbol name, though not at its beginning.
1307 Each symbol has exactly one name. Each name in an assembly language
1308 program refers to exactly one symbol. You may use that symbol name any
1309 number of times in a program.
1311 @node Local Symbols, , Symbol Names, Symbol Names
1312 @subsection Local Symbol Names
1314 Local symbols help compilers and programmers use names temporarily.
1315 There are ten local symbol names, which are re-used throughout the
1316 program. You may refer to them using the names @samp{0} @samp{1}
1317 @dots{} @samp{9}. To define a local symbol, write a label of the form
1318 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
1319 recent previous definition of that symbol write @samp{@b{N}b}, using the
1320 same digit as when you defined the label. To refer to the next
1321 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
1322 a choice of 10 forward references. The @samp{b} stands for
1323 ``backwards'' and the @samp{f} stands for ``forwards''.
1325 Local symbols are not emitted by the current GNU C compiler.
1327 There is no restriction on how you can use these labels, but
1328 remember that at any point in the assembly you can refer to at most
1329 10 prior local labels and to at most 10 forward local labels.
1331 Local symbol names are only a notation device. They are immediately
1332 transformed into more conventional symbol names before the assembler
1333 uses them. The symbol names stored in the symbol table, appearing in
1334 error messages and optionally emitted to the object file have these
1339 All local labels begin with @samp{L}. Normally both @code{_AS__} and
1340 @code{_LD__} forget symbols that start with @samp{L}. These labels are
1341 used for symbols you are never intended to see. If you give the
1342 @samp{-L} option then @code{_AS__} will retain these symbols in the
1343 object file. If you also instruct @code{_LD__} to retain these symbols,
1344 you may use them in debugging.
1347 If the label is written @samp{0:} then the digit is @samp{0}.
1348 If the label is written @samp{1:} then the digit is @samp{1}.
1349 And so on up through @samp{9:}.
1352 This unusual character is included so you don't accidentally invent
1353 a symbol of the same name. The character has ASCII value
1356 @item @emph{ordinal number}
1357 This is a serial number to keep the labels distinct. The first
1358 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
1359 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
1363 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
1364 @code{3:} is named @code{L3@ctrl{A}44}.
1366 @node Dot, Symbol Attributes, Symbol Names, Symbols
1367 @section The Special Dot Symbol
1369 The special symbol @samp{.} refers to the current address that
1370 @code{_AS__} is assembling into. Thus, the expression @samp{melvin:
1371 .long .} will cause @code{melvin} to contain its own address.
1372 Assigning a value to @code{.} is treated the same as a @code{.org}
1373 directive. Thus, the expression @samp{.=.+4} is the same as saying
1381 @node Symbol Attributes, , Dot, Symbols
1382 @section Symbol Attributes
1383 Every symbol has, as well as its name, the attributes ``Value'' and
1384 ``Type''. Depending on output format, symbols also have auxiliary attributes.
1386 The detailed definitions are in _0__<a.out.h>_1__.
1389 If you use a symbol without defining it, @code{_AS__} assumes zero for
1390 all these attributes, and probably won't warn you. This makes the
1391 symbol an externally defined symbol, which is generally what you
1394 @node Symbol Value, Symbol Type, Symbol Attributes, Symbol Attributes
1396 The value of a symbol is (usually) 32 bits, the size of one GNU C
1397 @code{int}. For a symbol which labels a location in the text, data, bss
1398 or absolute segments the value is the number of addresses from the start
1399 of that segment to the label. Naturally for text, data and bss segments
1400 the value of a symbol changes as @code{_LD__} changes segment base
1401 addresses during linking. Absolute symbols' values do not change during
1402 linking: that is why they are called absolute.
1404 The value of an undefined symbol is treated in a special way. If it is
1405 0 then the symbol is not defined in this assembler source program, and
1406 @code{_LD__} will try to determine its value from other programs it is
1407 linked with. You make this kind of symbol simply by mentioning a symbol
1408 name without defining it. A non-zero value represents a @code{.comm}
1409 common declaration. The value is how much common storage to reserve, in
1410 bytes (addresses). The symbol refers to the first address of the
1413 @node Symbol Type, Symbol Desc, Symbol Value, Symbol Attributes
1415 The type attribute of a symbol contains relocation (segment)
1416 information, any flag settings indicating that a symbol is external, and
1417 (optionally), other information for linkers and debuggers. The exact
1418 format depends on the object-code output format in use.
1420 _if__(_AOUT__||_BOUT__)
1421 @node a.out Symbols,,,
1422 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
1423 These symbol attributes appear only when @code{_AS__} is configured for
1424 one of the Berkeley-descended object output formats.
1426 @node Symbol Desc, Symbol Other, Symbol Type, Symbol Attributes
1427 @subsubsection Descriptor
1428 This is an arbitrary 16-bit value. You may establish a symbol's
1429 descriptor value by using a @code{.desc} statement (@pxref{Desc}).
1430 A descriptor value means nothing to @code{_AS__}.
1432 @node Symbol Other, , Symbol Desc, Symbol Attributes
1433 @subsubsection Other
1434 This is an arbitrary 8-bit value. It means nothing to @code{_AS__}.
1435 _fi__(_AOUT__||_BOUT__)
1438 @node COFF Symbols,,,
1439 @subsection Symbol Attributes for COFF
1440 The COFF format supports a multitude of auxiliary symbol attributes;
1441 like the primary symbol attributes, they are set between @code{.def} and
1442 @code{.endef} directives.
1444 @subsubsection Primary Attributes
1445 The symbol name is set with @code{.def}; the value and type,
1446 respectively, with @code{.val} and @code{.type}.
1448 @subsubsection Auxiliary Attributes
1449 The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl},
1450 @code{.size}, and @code{.tag} can generate auxiliary symbol table
1451 information for COFF.
1454 @node Expressions, Pseudo Ops, Symbols, Top
1455 @chapter Expressions
1456 An @dfn{expression} specifies an address or numeric value.
1457 Whitespace may precede and/or follow an expression.
1459 @node Empty Exprs, Integer Exprs, Expressions, Expressions
1460 @section Empty Expressions
1461 An empty expression has no value: it is just whitespace or null.
1462 Wherever an absolute expression is required, you may omit the
1463 expression and @code{_AS__} will assume a value of (absolute) 0. This
1464 is compatible with other assemblers.
1466 @node Integer Exprs, , Empty Exprs, Expressions
1467 @section Integer Expressions
1468 An @dfn{integer expression} is one or more @emph{arguments} delimited
1469 by @emph{operators}.
1471 @node Arguments, Operators, Integer Exprs, Integer Exprs
1472 @subsection Arguments
1474 @dfn{Arguments} are symbols, numbers or subexpressions. In other
1475 contexts arguments are sometimes called ``arithmetic operands''. In
1476 this manual, to avoid confusing them with the ``instruction operands'' of
1477 the machine language, we use the term ``argument'' to refer to parts of
1478 expressions only, reserving the word ``operand'' to refer only to machine
1479 instruction operands.
1481 Symbols are evaluated to yield @{@var{segment} @var{NNN}@} where
1482 @var{segment} is one of text, data, bss, absolute,
1483 or undefined. @var{NNN} is a signed, 2's complement 32 bit
1486 Numbers are usually integers.
1488 A number can be a flonum or bignum. In this case, you are warned
1489 that only the low order 32 bits are used, and @code{_AS__} pretends
1490 these 32 bits are an integer. You may write integer-manipulating
1491 instructions that act on exotic constants, compatible with other
1494 Subexpressions are a left parenthesis @samp{(} followed by an integer
1495 expression, followed by a right parenthesis @samp{)}; or a prefix
1496 operator followed by an argument.
1498 @node Operators, Prefix Ops, Arguments, Integer Exprs
1499 @subsection Operators
1500 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
1501 operators are followed by an argument. Infix operators appear
1502 between their arguments. Operators may be preceded and/or followed by
1505 @node Prefix Ops, Infix Ops, Operators, Integer Exprs
1506 @subsection Prefix Operators
1507 @code{_AS__} has the following @dfn{prefix operators}. They each take
1508 one argument, which must be absolute.
1510 @c the tex/end tex stuff surrounding this small table is meant to make
1511 @c it align, on the printed page, with the similar table in the next
1512 @c section (which is inside an enumerate).
1514 \global\advance\leftskip by \itemindent
1519 @dfn{Negation}. Two's complement negation.
1521 @dfn{Complementation}. Bitwise not.
1525 \global\advance\leftskip by -\itemindent
1528 @node Infix Ops, , Prefix Ops, Integer Exprs
1529 @subsection Infix Operators
1531 @dfn{Infix operators} take two arguments, one on either side. Operators
1532 have precedence, but operations with equal precedence are performed left
1533 to right. Apart from @code{+} or @code{-}, both arguments must be
1534 absolute, and the result is absolute.
1542 @dfn{Multiplication}.
1544 @dfn{Division}. Truncation is the same as the C operator @samp{/}
1549 @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__}
1552 @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__}
1556 Intermediate precedence
1559 @dfn{Bitwise Inclusive Or}.
1563 @dfn{Bitwise Exclusive Or}.
1565 @dfn{Bitwise Or Not}.
1572 @dfn{Addition}. If either argument is absolute, the result
1573 has the segment of the other argument.
1574 If either argument is pass1 or undefined, the result is pass1.
1575 Otherwise @code{+} is illegal.
1577 @dfn{Subtraction}. If the right argument is absolute, the
1578 result has the segment of the left argument.
1579 If either argument is pass1 the result is pass1.
1580 If either argument is undefined the result is difference segment.
1581 If both arguments are in the same segment, the result is absolute---provided
1582 that segment is one of text, data or bss.
1583 Otherwise subtraction is illegal.
1587 The sense of the rule for addition is that it's only meaningful to add
1588 the @emph{offsets} in an address; you can only have a defined segment in
1589 one of the two arguments.
1591 Similarly, you can't subtract quantities from two different segments.
1593 @node Pseudo Ops, _MACH_DEP__, Expressions, Top
1594 @chapter Assembler Directives
1596 All assembler directives have names that begin with a period (@samp{.}).
1597 The rest of the name is letters: their case does not matter.
1599 This chapter discusses directives present regardless of the target
1600 machine configuration for the GNU assembler; @pxref{_MACH_DEP__} for
1601 additional directives.
1604 @section @code{.abort}
1605 This directive stops the assembly immediately. It is for
1606 compatibility with other assemblers. The original idea was that the
1607 assembly language source would be piped into the assembler. If the sender
1608 of the source quit, it could use this directive tells @code{_AS__} to
1609 quit also. One day @code{.abort} will not be supported.
1613 @section @code{.ABORT}
1614 When producing COFF output, @code{_AS__} accepts this directive as a
1615 synonym for @samp{.abort}.
1620 @section @code{.ABORT}
1623 When producing @code{b.out} output, @code{_AS__} accepts this directive,
1628 @section @code{.align @var{abs-expr} , @var{abs-expr}}
1629 Pad the location counter (in the current subsegment) to a particular
1630 storage boundary. The first expression (which must be absolute) is the
1631 number of low-order zero bits the location counter will have after
1632 advancement. For example @samp{.align 3} will advance the location
1633 counter until it a multiple of 8. If the location counter is already a
1634 multiple of 8, no change is needed.
1636 The second expression (also absolute) gives the value to be stored in
1637 the padding bytes. It (and the comma) may be omitted. If it is
1638 omitted, the padding bytes are zero.
1641 @section @code{.app-file @var{string}}
1644 (which may also be spelled @samp{.file})
1646 tells @code{_AS__} that we are about to start a new
1647 logical file. @var{string} is the new file name. In general, the
1648 filename is recognized whether or not it is surrounded by quotes @samp{"};
1649 but if you wish to specify an empty file name is permitted,
1650 you must give the quotes--@code{""}. This statement may go away in
1651 future: it is only recognized to be compatible with old @code{_AS__}
1655 @section @code{.ascii "@var{string}"}@dots{}
1656 @code{.ascii} expects zero or more string literals (@pxref{Strings})
1657 separated by commas. It assembles each string (with no automatic
1658 trailing zero byte) into consecutive addresses.
1660 @node Asciz, Byte, Ascii, Pseudo Ops
1661 @section @code{.asciz "@var{string}"}@dots{}
1662 @code{.asciz} is just like @code{.ascii}, but each string is followed by
1663 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
1665 @node Byte, Comm, Asciz, Pseudo Ops
1666 @section @code{.byte @var{expressions}}
1668 @code{.byte} expects zero or more expressions, separated by commas.
1669 Each expression is assembled into the next byte.
1671 @node Comm, Data, Byte, Pseudo Ops
1672 @section @code{.comm @var{symbol} , @var{length} }
1673 @code{.comm} declares a named common area in the bss segment. Normally
1674 @code{_LD__} reserves memory addresses for it during linking, so no partial
1675 program defines the location of the symbol. Use @code{.comm} to tell
1676 @code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__}
1677 will allocate space for each @code{.comm} symbol that is at least as
1678 long as the longest @code{.comm} request in any of the partial programs
1679 linked. @var{length} is an absolute expression.
1681 @node Data, Desc, Comm, Pseudo Ops
1682 @section @code{.data @var{subsegment}}
1683 @code{.data} tells @code{_AS__} to assemble the following statements onto the
1684 end of the data subsegment numbered @var{subsegment} (which is an
1685 absolute expression). If @var{subsegment} is omitted, it defaults
1690 @section @code{.def @var{name}}
1691 Begin defining debugging information for a symbol @var{name}; the
1692 definition extends until the @code{.endef} directive is encountered.
1695 This directive is only observed when @code{_AS__} is configured for COFF
1696 format output; when producing @code{b.out}, @samp{.def} is recognized,
1701 _if__(_AOUT__||_BOUT__)
1702 @node Desc, Double, Data, Pseudo Ops
1703 @section @code{.desc @var{symbol}, @var{abs-expression}}
1704 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
1705 to the low 16 bits of an absolute expression.
1708 The @samp{.desc} directive is not available when @code{_AS__} is
1709 configured for COFF output; it is only for @code{a.out} or @code{b.out}
1710 object format. For the sake of compatibility, @code{_AS__} will accept
1711 it, but produce no output, when configured for COFF.
1713 _fi__(_AOUT__||_BOUT__)
1717 @section @code{.dim}
1718 This directive is generated by compilers to include auxiliary debugging
1719 information in the symbol table. It is only permitted inside
1720 @code{.def}/@code{.endef} pairs.
1723 @samp{.dim} is only meaningful when generating COFF format output; when
1724 @code{_AS__} is generating @code{b.out}, it accepts this directive but
1729 @node Double, Else, Desc, Pseudo Ops
1730 @section @code{.double @var{flonums}}
1731 @code{.double} expects zero or more flonums, separated by commas. It
1732 assembles floating point numbers.
1734 The exact kind of floating point numbers emitted depends on how
1735 @code{_AS__} is configured. @xref{_MACH_DEP__}.
1737 _if__(_AMD29K__ || _I960__)
1738 On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers
1740 _fi__(_AMD29K__ || _I960__)
1743 @section @code{.else}
1744 @code{.else} is part of the @code{_AS__} support for conditional assembly;
1745 @pxref{If}. It marks the beginning of a section of code to be assembled
1746 if the condition for the preceding @code{.if} was false.
1750 @section @code{.end}
1751 This doesn't do anything---but isn't an s_ignore, so I suspect it's
1752 meant to do something eventually (which is why it isn't documented here
1753 as "for compatibility with blah").
1758 @section @code{.endef}
1759 This directive flags the end of a symbol definition begun with
1763 @samp{.endef} is only meaningful when generating COFF format output; if
1764 @code{_AS__} is configured to generate @code{b.out}, it accepts this
1765 directive but ignores it.
1769 @node Endif, Equ, End, Pseudo Ops
1770 @section @code{.endif}
1771 @code{.endif} is part of the @code{_AS__} support for conditional assembly;
1772 it marks the end of a block of code that is only assembled
1773 conditionally. @xref{If}.
1775 @node Equ, Extern, Endif, Pseudo Ops
1776 @section @code{.equ @var{symbol}, @var{expression}}
1778 This directive sets the value of @var{symbol} to @var{expression}.
1779 It is synonymous with @samp{.set}; @pxref{Set}.
1782 @section @code{.extern}
1783 @code{.extern} is accepted in the source program---for compatibility
1784 with other assemblers---but it is ignored. @code{_AS__} treats
1785 all undefined symbols as external.
1789 @section @code{.app-file @var{string}}
1790 @code{.file} (which may also be spelled @samp{.app-file}) tells
1791 @code{_AS__} that we are about to start a new logical file.
1792 @var{string} is the new file name. In general, the filename is
1793 recognized whether or not it is surrounded by quotes @samp{"}; but if
1794 you wish to specify an empty file name, you must give the
1795 quotes--@code{""}. This statement may go away in future: it is only
1796 recognized to be compatible with old @code{_AS__} programs.
1801 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
1802 @var{result}, @var{size} and @var{value} are absolute expressions.
1803 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
1804 may be zero or more. @var{Size} may be zero or more, but if it is
1805 more than 8, then it is deemed to have the value 8, compatible with
1806 other people's assemblers. The contents of each @var{repeat} bytes
1807 is taken from an 8-byte number. The highest order 4 bytes are
1808 zero. The lowest order 4 bytes are @var{value} rendered in the
1809 byte-order of an integer on the computer @code{_AS__} is assembling for.
1810 Each @var{size} bytes in a repetition is taken from the lowest order
1811 @var{size} bytes of this number. Again, this bizarre behavior is
1812 compatible with other people's assemblers.
1814 @var{size} and @var{value} are optional.
1815 If the second comma and @var{value} are absent, @var{value} is
1816 assumed zero. If the first comma and following tokens are absent,
1817 @var{size} is assumed to be 1.
1819 @node Float, Global, Fill, Pseudo Ops
1820 @section @code{.float @var{flonums}}
1821 This directive assembles zero or more flonums, separated by commas. It
1822 has the same effect as @code{.single}.
1824 The exact kind of floating point numbers emitted depends on how
1825 @code{_AS__} is configured.
1828 _if__(_AMD29K__ || _I960__)
1829 On the _HOST__ family, @code{.float} emits 32-bit floating point numbers
1831 _fi__(_AMD29K__ || _I960__)
1833 @node Global, Ident, Float, Pseudo Ops
1834 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
1835 @code{.global} makes the symbol visible to @code{_LD__}. If you define
1836 @var{symbol} in your partial program, its value is made available to
1837 other partial programs that are linked with it. Otherwise,
1838 @var{symbol} will take its attributes from a symbol of the same name
1839 from another partial program it is linked with.
1842 @c FIXME BFD implications; this is different in COFF.
1843 This is done by setting the @code{N_EXT} bit of that symbol's type byte
1844 to 1. @xref{Symbol Attributes}.
1847 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
1848 compatibility with other assemblers.
1850 @node hword, line, file, Machine Directives
1851 @section @code{.hword @var{expressions}}
1852 This expects zero or more @var{expressions}, and emits
1853 a 16 bit number for each.
1856 This directive is a synonym for @samp{.short}; depending on the target
1857 architecture, it may also be a synonym for @samp{.word}.
1859 _if__( (_AMD29K__ || _I960__) && !_ALL_ARCH__ )
1860 This directive is a synonym for @samp{.short}.
1861 _fi__( (_AMD29K__ || _I960__) && !_ALL_ARCH__ )
1863 _if__(_AOUT__||_BOUT__||_COFF__)
1864 @node Ident, If, Global, Pseudo Ops
1865 @section @code{.ident}
1866 This directive is used by some assemblers to place tags in object files.
1867 @code{_AS__} simply accepts the directive for source-file
1868 compatibility with such assemblers, but does not actually emit anything
1870 _fi__(_AOUT__||_BOUT__||_COFF__)
1872 @node If, Include, Ident, Pseudo Ops
1873 @section @code{.if @var{absolute expression}}
1874 @code{.if} marks the beginning of a section of code which is only
1875 considered part of the source program being assembled if the argument
1876 (which must be an @var{absolute expression}) is non-zero. The end of
1877 the conditional section of code must be marked by @code{.endif}
1878 (@pxref{Endif}); optionally, you may include code for the
1879 alternative condition, flagged by @code{.else} (@pxref{Else}.
1881 The following variants of @code{.if} are also supported:
1883 @item ifdef @var{symbol}
1884 Assembles the following section of code if the specified @var{symbol}
1889 Not yet implemented.
1892 @item ifndef @var{symbol}
1893 @itemx ifnotdef @var{symbol}
1894 Assembles the following section of code if the specified @var{symbol}
1895 has not been defined. Both spelling variants are equivalent.
1899 Not yet implemented.
1903 @node Include, Int, If, Pseudo Ops
1904 @section @code{.include "@var{file}"}
1905 This directive provides a way to include supporting files at specified
1906 points in your source program. The code from @var{file} is assembled as
1907 if it followed the point of the @code{.include}; when the end of the
1908 included file is reached, assembly of the original file continues. You
1909 can control the search paths used with the @samp{-I} command-line option
1910 (@pxref{Options}). Quotation marks are required around @var{file}.
1912 @node Int, Lcomm, Include, Pseudo Ops
1913 @section @code{.int @var{expressions}}
1914 Expect zero or more @var{expressions}, of any segment, separated by
1915 commas. For each expression, emit a 32-bit number that will, at run
1916 time, be the value of that expression. The byte order of the
1917 expression depends on what kind of computer will run the program.
1919 @node Lcomm, Line, Int, Pseudo Ops
1920 @section @code{.lcomm @var{symbol} , @var{length}}
1921 Reserve @var{length} (an absolute expression) bytes for a local
1922 common denoted by @var{symbol}. The segment and value of @var{symbol} are
1923 those of the new local common. The addresses are allocated in the
1924 bss segment, so at run-time the bytes will start off zeroed.
1925 @var{Symbol} is not declared global (@pxref{Global}), so is normally
1926 not visible to @code{_LD__}.
1928 _if__(_AOUT__||_BOUT__||_COFF__)
1931 @section @code{.line @var{line-number}}
1935 @section @code{.ln @var{line-number}}
1937 _fi__(_AOUT__||_BOUT__||_COFF__)
1938 _if__(_AOUT__||_BOUT__)
1939 Tell @code{_AS__} to change the logical line number. @var{line-number} must be
1940 an absolute expression. The next line will have that logical line
1941 number. So any other statements on the current line (after a statement
1949 will be reported as on logical line number
1950 @var{line-number} @minus{} 1.
1951 One day this directive will be unsupported: it is used only
1952 for compatibility with existing assembler programs. @refill
1953 _fi__(_AOUT__||_BOUT__)
1956 Even though this is a directive associated with the @code{a.out} or
1957 @code{b.out} object-code formats, @code{_AS__} will still recognize it
1958 when producing COFF output, and will treat @samp{.line} as though it
1959 were the COFF @samp{.ln} @emph{if} it is found outside a
1960 @code{.def}/@code{.endef} pair.
1962 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
1963 used by compilers to generate auxiliary symbol information for
1967 _if__(_AOUT__&&!_AMD29K__)
1969 @section @code{.ln @var{line-number}}
1970 @samp{.ln} is a synonym for @samp{.line}.
1971 _fi__(_AOUT__&&!_AMD29K__)
1973 _if__(_COFF__&&!_AOUT__)
1975 @section @code{.ln @var{line-number}}
1976 Tell @code{_AS__} to change the logical line number. @var{line-number}
1977 must be an absolute expression. The next line will have that logical
1978 line number. So any other statements on the current line (after a
1979 statement separator character @code{;}) will be reported as on logical
1980 line number @var{line-number} @minus{} 1.
1983 This directive is accepted, but ignored, when @code{_AS__} is configured for
1984 @code{b.out}; its effect is only associated with COFF output format.
1986 _fi__(_COFF__&&!_AOUT__)
1989 @section @code{.list} and related directives
1990 @code{_AS__} ignores the directives @code{.list}, @code{.nolist},
1991 @code{.eject}, @code{.lflags}, @code{.title}, @code{.sbttl}; however,
1992 they're accepted for compatibility with assemblers that use them.
1994 @node Long, Lsym, List, Pseudo Ops
1995 @section @code{.long @var{expressions}}
1996 @code{.long} is the same as @samp{.int}, @pxref{Int}.
1998 @node Lsym, Octa, Long, Pseudo Ops
1999 @section @code{.lsym @var{symbol}, @var{expression}}
2000 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
2001 the hash table, ensuring it cannot be referenced by name during the
2002 rest of the assembly. This sets the attributes of the symbol to be
2003 the same as the expression value:
2005 @var{other} = @var{descriptor} = 0
2006 @var{type} = @r{(segment of @var{expression})}
2007 @var{value} = @var{expression}
2010 The new symbol is not flagged as external.
2012 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
2013 @node Octa, Org, Lsym, Pseudo Ops
2014 @section @code{.octa @var{bignums}}
2015 This directive expects zero or more bignums, separated by commas. For each
2016 bignum, it emits a 16-byte integer.
2018 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
2019 hence @emph{octa}-word for 16 bytes.
2021 @node Org, Quad, Octa, Pseudo Ops
2022 @section @code{.org @var{new-lc} , @var{fill}}
2024 @code{.org} will advance the location counter of the current segment to
2025 @var{new-lc}. @var{new-lc} is either an absolute expression or an
2026 expression with the same segment as the current subsegment. That is,
2027 you can't use @code{.org} to cross segments: if @var{new-lc} has the
2028 wrong segment, the @code{.org} directive is ignored. To be compatible
2029 with former assemblers, if the segment of @var{new-lc} is absolute,
2030 @code{_AS__} will issue a warning, then pretend the segment of @var{new-lc}
2031 is the same as the current subsegment.
2033 @code{.org} may only increase the location counter, or leave it
2034 unchanged; you cannot use @code{.org} to move the location counter
2037 @c double negative used below "not undefined" because this is a specific
2038 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
2039 @c segment. pesch@cygnus.com 18feb91
2040 Because @code{_AS__} tries to assemble programs in one pass @var{new-lc}
2041 may not be undefined. If you really detest this restriction we eagerly await
2042 a chance to share your improved assembler.
2044 Beware that the origin is relative to the start of the segment, not
2045 to the start of the subsegment. This is compatible with other
2046 people's assemblers.
2048 When the location counter (of the current subsegment) is advanced, the
2049 intervening bytes are filled with @var{fill} which should be an
2050 absolute expression. If the comma and @var{fill} are omitted,
2051 @var{fill} defaults to zero.
2053 @node Quad, Set, Org, Pseudo Ops
2054 @section @code{.quad @var{bignums}}
2055 @code{.quad} expects zero or more bignums, separated by commas. For
2056 each bignum, it emits
2058 an 8-byte integer. If the bignum won't fit in 8
2059 bytes, it prints a warning message; and just takes the lowest order 8
2060 bytes of the bignum.@refill
2062 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
2063 hence @emph{quad}-word for 8 bytes.
2066 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
2067 warning message; and just takes the lowest order 16 bytes of the
2073 @section @code{.scl @var{class}}
2074 Set the storage-class value for a symbol. This directive may only be
2075 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
2076 whether a symbol is static or external, or it may record further
2077 symbolic debugging information.
2080 The @samp{.scl} directive is primarily associated with COFF output; when
2081 configured to generate @code{b.out} output format, @code{_AS__} will
2082 accept this directive but ignore it.
2088 @section @code{.set @var{symbol}, @var{expression}}
2090 This directive sets the value of @var{symbol} to @var{expression}. This
2091 will change @var{symbol}'s value and type to conform to
2092 @var{expression}. If @var{symbol} was flagged as external, it remains
2093 flagged. (@xref{Symbol Attributes}.)
2095 You may @code{.set} a symbol many times in the same assembly.
2096 If the expression's segment is unknowable during pass 1, a second
2097 pass over the source program will be forced. The second pass is
2098 currently not implemented. @code{_AS__} will abort with an error
2099 message if one is required.
2101 If you @code{.set} a global symbol, the value stored in the object
2102 file is the last value stored into it.
2104 @node Short, Single, Set, Pseudo Ops
2105 @section @code{.short @var{expressions}}
2106 _if__(! (_SPARC__ || _AMD29K__ || _I960__) )
2107 @code{.short} is the same as @samp{.word}. @xref{Word}.
2108 _fi__(! (_SPARC__ || _AMD29K__ || _I960__) )
2109 _if__(_SPARC__ || _AMD29K__ || _I960__)
2110 This expects zero or more @var{expressions}, and emits
2111 a 16 bit number for each.
2112 _fi__(_SPARC__ || _AMD29K__ || _I960__)
2115 @section @code{.single @var{flonums}}
2116 This directive assembles zero or more flonums, separated by commas. It
2117 has the same effect as @code{.float}.
2119 The exact kind of floating point numbers emitted depends on how
2120 @code{_AS__} is configured. @xref{_MACH_DEP__}.
2122 _if__(_AMD29K__ || _I960__)
2123 On the _HOST__ family, @code{.single} emits 32-bit floating point
2124 numbers in IEEE format.
2125 _fi__(_AMD29K__ || _I960__)
2129 @section @code{.size}
2130 This directive is generated by compilers to include auxiliary debugging
2131 information in the symbol table. It is only permitted inside
2132 @code{.def}/@code{.endef} pairs.
2135 @samp{.size} is only meaningful when generating COFF format output; when
2136 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2143 @section @code{.space @var{size} , @var{fill}}
2144 This directive emits @var{size} bytes, each of value @var{fill}. Both
2145 @var{size} and @var{fill} are absolute expressions. If the comma
2146 and @var{fill} are omitted, @var{fill} is assumed to be zero.
2150 @section @code{.space}
2151 This directive is ignored; it is accepted for compatibility with other
2155 @emph{Warning:} In other versions of the GNU assembler, the directive
2156 @code{.space} has the effect of @code{.block} @xref{Machine Directives}.
2160 _if__(_AOUT__||_BOUT__||_COFF__)
2161 @node Stab, Text, Space, Pseudo Ops
2162 @section @code{.stabd, .stabn, .stabs}
2163 There are three directives that begin @samp{.stab}.
2164 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
2165 The symbols are not entered in the @code{_AS__} hash table: they
2166 cannot be referenced elsewhere in the source file.
2167 Up to five fields are required:
2170 This is the symbol's name. It may contain any character except @samp{\000},
2171 so is more general than ordinary symbol names. Some debuggers used to
2172 code arbitrarily complex structures into symbol names using this field.
2174 An absolute expression. The symbol's type is set to the low 8
2175 bits of this expression.
2176 Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on
2179 An absolute expression.
2180 The symbol's ``other'' attribute is set to the low 8 bits of this expression.
2182 An absolute expression.
2183 The symbol's descriptor is set to the low 16 bits of this expression.
2185 An absolute expression which becomes the symbol's value.
2188 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
2189 or @code{.stabs} statement, the symbol has probably already been created
2190 and you will get a half-formed symbol in your object file. This is
2191 compatible with earlier assemblers!
2194 @item .stabd @var{type} , @var{other} , @var{desc}
2196 The ``name'' of the symbol generated is not even an empty string.
2197 It is a null pointer, for compatibility. Older assemblers used a
2198 null pointer so they didn't waste space in object files with empty
2201 The symbol's value is set to the location counter,
2202 relocatably. When your program is linked, the value of this symbol
2203 will be where the location counter was when the @code{.stabd} was
2206 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
2208 The name of the symbol is set to the empty string @code{""}.
2210 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
2212 All five fields are specified.
2214 _fi__(_AOUT__||_BOUT__||_COFF__)
2218 @section @code{.tag @var{structname}}
2219 This directive is generated by compilers to include auxiliary debugging
2220 information in the symbol table. It is only permitted inside
2221 @code{.def}/@code{.endef} pairs. Tags are used to link structure
2222 definitions in the symbol table with instances of those structures.
2225 @samp{.tag} is only used when generating COFF format output; when
2226 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2232 @section @code{.text @var{subsegment}}
2233 Tells @code{_AS__} to assemble the following statements onto the end of
2234 the text subsegment numbered @var{subsegment}, which is an absolute
2235 expression. If @var{subsegment} is omitted, subsegment number zero
2240 @section @code{.type @var{int}}
2241 This directive, permitted only within @code{.def}/@code{.endef} pairs,
2242 records the integer @var{int} as the type attribute of a symbol table entry.
2245 @samp{.type} is associated only with COFF format output; when
2246 @code{_AS__} is configured for @code{b.out} output, it accepts this
2247 directive but ignores it.
2253 @section @code{.val @var{addr}}
2254 This directive, permitted only within @code{.def}/@code{.endef} pairs,
2255 records the address @var{addr} as the value attribute of a symbol table
2259 @samp{.val} is used only for COFF output; when @code{_AS__} is
2260 configured for @code{b.out}, it accepts this directive but ignores it.
2265 @section @code{.word @var{expressions}}
2266 This directive expects zero or more @var{expressions}, of any segment,
2267 separated by commas.
2268 _if__(_SPARC__ || _AMD29K__ || _I960__)
2269 For each expression, @code{_AS__} emits a 32-bit number.
2270 _fi__(_SPARC__ || _AMD29K__ || _I960__)
2271 _if__(! (_SPARC__ || _AMD29K__ || _I960__) )
2272 For each expression, @code{_AS__} emits a 16-bit number.
2273 _fi__(! (_SPARC__ || _AMD29K__ || _I960__) )
2276 The byte order of the expression depends on what kind of computer will
2280 @c on these boxes the "special treatment to support compilers" doesn't
2281 @c happen---32-bit addressability, period; no long/short jumps.
2282 _if__(! (_AMD29K__ || _I960__) )
2283 @subsection Special Treatment to support Compilers
2285 In order to assemble compiler output into something that will work,
2286 @code{_AS__} will occasionlly do strange things to @samp{.word} directives.
2287 Directives of the form @samp{.word sym1-sym2} are often emitted by
2288 compilers as part of jump tables. Therefore, when @code{_AS__} assembles a
2289 directive of the form @samp{.word sym1-sym2}, and the difference between
2290 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will
2291 create a @dfn{secondary jump table}, immediately before the next label.
2292 This @var{secondary jump table} will be preceded by a short-jump to the
2293 first byte after the secondary table. This short-jump prevents the flow
2294 of control from accidentally falling into the new table. Inside the
2295 table will be a long-jump to @code{sym2}. The original @samp{.word}
2296 will contain @code{sym1} minus the address of the long-jump to
2299 If there were several occurrences of @samp{.word sym1-sym2} before the
2300 secondary jump table, all of them will be adjusted. If there was a
2301 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
2302 long-jump to @code{sym4} will be included in the secondary jump table,
2303 and the @code{.word} directives will be adjusted to contain @code{sym3}
2304 minus the address of the long-jump to @code{sym4}; and so on, for as many
2305 entries in the original jump table as necessary.
2308 @emph{This feature may be disabled by compiling @code{_AS__} with the
2309 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
2310 assembly language programmers.
2312 _fi__(! (_AMD29K__ || _I960__) )
2314 @node Deprecated, _MACH_DEP__, Word, Pseudo Ops
2315 @section Deprecated Directives
2316 One day these directives won't work.
2317 They are included for compatibility with older assemblers.
2324 @node _MACH_DEP__,,,
2326 @chapter Machine Dependent Features
2330 _CHAPSEC__(0+_ALL_ARCH__) VAX Dependent Features
2331 _CHAPSEC__(1+_ALL_ARCH__) Options
2333 The Vax version of @code{_AS__} accepts any of the following options,
2334 gives a warning message that the option was ignored and proceeds.
2335 These options are for compatibility with scripts designed for other
2336 people's assemblers.
2340 @item @kbd{-D} (Debug)
2341 @itemx @kbd{-S} (Symbol Table)
2342 @itemx @kbd{-T} (Token Trace)
2343 These are obsolete options used to debug old assemblers.
2345 @item @kbd{-d} (Displacement size for JUMPs)
2346 This option expects a number following the @kbd{-d}. Like options
2347 that expect filenames, the number may immediately follow the
2348 @kbd{-d} (old standard) or constitute the whole of the command line
2349 argument that follows @kbd{-d} (GNU standard).
2351 @item @kbd{-V} (Virtualize Interpass Temporary File)
2352 Some other assemblers use a temporary file. This option
2353 commanded them to keep the information in active memory rather
2354 than in a disk file. @code{_AS__} always does this, so this
2355 option is redundant.
2357 @item @kbd{-J} (JUMPify Longer Branches)
2358 Many 32-bit computers permit a variety of branch instructions
2359 to do the same job. Some of these instructions are short (and
2360 fast) but have a limited range; others are long (and slow) but
2361 can branch anywhere in virtual memory. Often there are 3
2362 flavors of branch: short, medium and long. Some other
2363 assemblers would emit short and medium branches, unless told by
2364 this option to emit short and long branches.
2366 @item @kbd{-t} (Temporary File Directory)
2367 Some other assemblers may use a temporary file, and this option
2368 takes a filename being the directory to site the temporary
2369 file. @code{_AS__} does not use a temporary disk file, so this
2370 option makes no difference. @kbd{-t} needs exactly one
2374 The Vax version of the assembler accepts two options when
2375 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
2376 @kbd{-h} option prevents @code{_AS__} from modifying the
2377 symbol-table entries for symbols that contain lowercase
2378 characters (I think). The @kbd{-+} option causes @code{_AS__} to
2379 print warning messages if the FILENAME part of the object file,
2380 or any symbol name is larger than 31 characters. The @kbd{-+}
2381 option also insertes some code following the @samp{_main}
2382 symbol so that the object file will be compatible with Vax-11
2385 _CHAPSEC__(1+_ALL_ARCH__) Floating Point
2386 Conversion of flonums to floating point is correct, and
2387 compatible with previous assemblers. Rounding is
2388 towards zero if the remainder is exactly half the least significant bit.
2390 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
2393 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
2394 are rendered correctly. Again, rounding is towards zero in the
2397 The @code{.float} directive produces @code{f} format numbers.
2398 The @code{.double} directive produces @code{d} format numbers.
2400 _CHAPSEC__(1+_ALL_ARCH__) Machine Directives
2401 The Vax version of the assembler supports four directives for
2402 generating Vax floating point constants. They are described in the
2407 This expects zero or more flonums, separated by commas, and
2408 assembles Vax @code{d} format 64-bit floating point constants.
2411 This expects zero or more flonums, separated by commas, and
2412 assembles Vax @code{f} format 32-bit floating point constants.
2415 This expects zero or more flonums, separated by commas, and
2416 assembles Vax @code{g} format 64-bit floating point constants.
2419 This expects zero or more flonums, separated by commas, and
2420 assembles Vax @code{h} format 128-bit floating point constants.
2424 _CHAPSEC__(1+_ALL_ARCH__) Opcodes
2425 All DEC mnemonics are supported. Beware that @code{case@dots{}}
2426 instructions have exactly 3 operands. The dispatch table that
2427 follows the @code{case@dots{}} instruction should be made with
2428 @code{.word} statements. This is compatible with all unix
2429 assemblers we know of.
2431 _CHAPSEC__(1+_ALL_ARCH__) Branch Improvement
2432 Certain pseudo opcodes are permitted. They are for branch
2433 instructions. They expand to the shortest branch instruction that
2434 will reach the target. Generally these mnemonics are made by
2435 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
2436 This feature is included both for compatibility and to help
2437 compilers. If you don't need this feature, don't use these
2438 opcodes. Here are the mnemonics, and the code they can expand into.
2442 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
2444 @item (byte displacement)
2446 @item (word displacement)
2448 @item (long displacement)
2453 Unconditional branch.
2455 @item (byte displacement)
2457 @item (word displacement)
2459 @item (long displacement)
2463 @var{COND} may be any one of the conditional branches
2464 @code{neq nequ eql eqlu gtr geq lss gtru lequ vc vs gequ cc lssu cs}.
2465 @var{COND} may also be one of the bit tests
2466 @code{bs bc bss bcs bsc bcc bssi bcci lbs lbc}.
2467 @var{NOTCOND} is the opposite condition to @var{COND}.
2469 @item (byte displacement)
2470 @kbd{b@var{COND} @dots{}}
2471 @item (word displacement)
2472 @kbd{b@var{UNCOND} foo ; brw @dots{} ; foo:}
2473 @item (long displacement)
2474 @kbd{b@var{UNCOND} foo ; jmp @dots{} ; foo:}
2477 @var{X} may be one of @code{b d f g h l w}.
2479 @item (word displacement)
2480 @kbd{@var{OPCODE} @dots{}}
2481 @item (long displacement)
2482 @kbd{@var{OPCODE} @dots{}, foo ; brb bar ; foo: jmp @dots{} ; bar:}
2485 @var{YYY} may be one of @code{lss leq}.
2487 @var{ZZZ} may be one of @code{geq gtr}.
2489 @item (byte displacement)
2490 @kbd{@var{OPCODE} @dots{}}
2491 @item (word displacement)
2492 @kbd{@var{OPCODE} @dots{}, foo ; brb bar ; foo: brw @var{destination} ; bar:}
2493 @item (long displacement)
2494 @kbd{@var{OPCODE} @dots{}, foo ; brb bar ; foo: jmp @var{destination} ; bar: }
2501 @item (byte displacement)
2502 @kbd{@var{OPCODE} @dots{}}
2503 @item (word displacement)
2504 @kbd{@var{OPCODE} @dots{}, foo ; brb bar ; foo: brw @var{destination} ; bar:}
2505 @item (long displacement)
2506 @kbd{@var{OPCODE} @dots{}, foo ; brb bar ; foo: jmp @var{destination} ; bar:}
2510 _CHAPSEC__(1+_ALL_ARCH__) operands
2511 The immediate character is @samp{$} for Unix compatibility, not
2512 @samp{#} as DEC writes it.
2514 The indirect character is @samp{*} for Unix compatibility, not
2515 @samp{@@} as DEC writes it.
2517 The displacement sizing character is @samp{`} (an accent grave) for
2518 Unix compatibility, not @samp{^} as DEC writes it. The letter
2519 preceding @samp{`} may have either case. @samp{G} is not
2520 understood, but all other letters (@code{b i l s w}) are understood.
2522 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
2523 pc}. Any case of letters will do.
2530 Any expression is permitted in an operand. Operands are comma
2533 @c There is some bug to do with recognizing expressions
2534 @c in operands, but I forget what it is. It is
2535 @c a syntax clash because () is used as an address mode
2536 @c and to encapsulate sub-expressions.
2537 _CHAPSEC__(1+_ALL_ARCH__) Not Supported
2538 Vax bit fields can not be assembled with @code{_AS__}. Someone
2539 can add the required code if they really need it.
2543 _CHAPSEC__(0+_ALL_ARCH__) AMD 29K Dependent Features
2544 @node AMD29K Options, AMD29K Syntax, _MACH_DEP__, _MACH_DEP__
2545 _CHAPSEC__(1+_ALL_ARCH__) Options
2546 @code{_AS__} has no additional command-line options for the AMD
2550 @node AMD29K Syntax, AMD29K Floating Point, AMD29K Options, _MACH_DEP__
2552 _CHAPSEC__(1+_ALL_ARCH__) Syntax
2553 _CHAPSEC__(2+_ALL_ARCH__) Special Characters
2554 @samp{;} is the line comment character.
2556 @samp{@@} can be used instead of a newline to separate statements.
2558 The character @samp{?} is permitted in identifiers (but may not begin
2562 _CHAPSEC__(2+_ALL_ARCH__) Register Names
2563 General-purpose registers are represented by predefined symbols of the
2564 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
2565 (for local registers), where @var{nnn} represents a number between
2566 @code{0} and @code{127}, written with no leading zeros. The leading
2567 letters may be in either upper or lower case; for example, @samp{gr13}
2568 and @samp{LR7} are both valid register names.
2570 You may also refer to general-purpose registers by specifying the
2571 register number as the result of an expression (prefixed with @samp{%%}
2572 to flag the expression as a register number):
2576 @noindent---where @var{expression} must be an absolute expression
2577 evaluating to a number between @code{0} and @code{255}. The range
2578 [0, 127] refers to global registers, and the range [128, 255] to local
2581 In addition, @code{_AS__} understands the following protected
2582 special-purpose register names for the AMD 29K family:
2592 These unprotected special-purpose register names are also recognized:
2600 @node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, _MACH_DEP__
2601 _CHAPSEC__(1+_ALL_ARCH__) Floating Point
2602 The AMD 29K family uses IEEE floating-point numbers.
2605 @node AMD29K Directives, AMD29K Opcodes, AMD29K Floating Point, _MACH_DEP__
2606 _CHAPSEC__(1+_ALL_ARCH__) Machine Directives
2608 @node block, cputype, AMD29K Directives, AMD29K Directives
2609 _CHAPSEC__(2+_ALL_ARCH__) @code{.block @var{size} , @var{fill}}
2610 This directive emits @var{size} bytes, each of value @var{fill}. Both
2611 @var{size} and @var{fill} are absolute expressions. If the comma
2612 and @var{fill} are omitted, @var{fill} is assumed to be zero.
2614 In other versions of the GNU assembler, this directive is called
2618 @node cputype, file, block, Machine Directives
2619 _CHAPSEC__(2+_ALL_ARCH__) @code{.cputype}
2620 This directive is ignored; it is accepted for compatibility with other
2623 @node file, hword, cputype, Machine Directives
2624 _CHAPSEC__(2+_ALL_ARCH__) @code{.file}
2625 This directive is ignored; it is accepted for compatibility with other
2629 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
2630 used for the directive called @code{.app-file} in the AMD 29K support.
2633 @node line, reg, hword, Machine Directives
2634 _CHAPSEC__(2+_ALL_ARCH__) @code{.line}
2635 This directive is ignored; it is accepted for compatibility with other
2638 @node reg, sect, line, Machine Directives
2639 _CHAPSEC__(2+_ALL_ARCH__) @code{.reg @var{symbol}, @var{expression}}
2640 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym}.
2642 @node sect, use, reg, Machine Directives
2643 _CHAPSEC__(2+_ALL_ARCH__) @code{.sect}
2644 This directive is ignored; it is accepted for compatibility with other
2647 @node use, , sect, Machine Directives
2648 _CHAPSEC__(2+_ALL_ARCH__) @code{.use @var{segment name}}
2649 Establishes the segment and subsegment for the following code;
2650 @var{segment name} may be one of @code{.text}, @code{.data},
2651 @code{.data1}, or @code{.lit}. With one of the first three @var{segment
2652 name} options, @samp{.use} is equivalent to the machine directive
2653 @var{segment name}; the remaining case, @samp{.use .lit}, is the same as
2657 @node AMD29K Opcodes, , AMD29K Directives, _MACH_DEP__
2659 @code{_AS__} implements all the standard AMD 29K opcodes. No
2660 additional pseudo-instructions are needed on this family.
2662 For information on the 29K machine instruction set, see @cite{Am29000
2663 User's Manual}, Advanced Micro Devices, Inc.
2667 _CHAPSEC__(0+_ALL_ARCH__) Intel 80960 Dependent Features
2668 @node Options-i960,,,
2669 _CHAPSEC__(1+_ALL_ARCH__) Command-line Options
2672 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
2673 Select the 80960 architecture. Instructions or features not supported
2674 by the selected architecture cause fatal errors.
2676 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
2677 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
2679 If none of these options is specified, @code{_AS__} will generate code for any
2680 instruction or feature that is supported by @emph{some} version of the
2681 960 (even if this means mixing architectures!). In principle,
2682 @code{_AS__} will attempt to deduce the minimal sufficient processor
2683 type if none is specified; depending on the object code format, the
2684 processor type may be recorded in the object file. If it is critical
2685 that the @code{_AS__} output match a specific architecture, specify that
2686 architecture explicitly.
2690 Add code to collect information about conditional branches taken, for
2691 later optimization using branch prediction bits. (The conditional branch
2692 instructions have branch prediction bits in the CA, CB, and CC
2693 architectures.) If @var{BR} represents a conditional branch instruction,
2694 the following represents the code generated by the assembler when
2695 @samp{-b} is specified:
2698 call @var{increment routine}
2699 .word 0 # pre-counter
2701 call @var{increment routine}
2702 .word 0 # post-counter
2705 The counter following a branch records the number of times that branch
2706 was @emph{not} taken; the differenc between the two counters is the
2707 number of times the branch @emph{was} taken.
2709 A table of all such @code{Label}s is also generated, so that the
2710 external postprocessor @samp{gbr960} (supplied by Intel) can locate all
2711 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
2712 this is a local symbol to permit collecting statistics for many separate
2713 object files. The table is word aligned, and begins with a two-word
2714 header. The first word, initialized to 0, is used in maintaining linked
2715 lists of branch tables. The second word is a count of the number of
2716 entries in the table, which follow immediately: each is a word, pointing
2717 to one of the labels illustrated above.
2721 +------------+------------+------------+ ... +------------+
2723 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
2725 +------------+------------+------------+ ... +------------+
2727 __BRANCH_TABLE__ layout
2732 \line{\leftskip=0pt\hskip\tableindent
2733 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
2734 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
2735 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
2738 The first word of the header is used to locate multiple branch tables,
2739 since each object file may contain one. Normally the links are
2740 maintained with a call to an initialization routine, placed at the
2741 beginning of each function in the file. The GNU C compiler will
2742 generate these calls automatically when you give it a @samp{-b} option.
2743 For further details, see the documentation of @samp{gbr960}.
2746 Normally, Compare-and-Branch instructions with targets that require
2747 displacements greater than 13 bits (or that have external targets) are
2748 replaced with the corresponding compare (or @samp{chkbit}) and branch
2749 instructions. You can use the @samp{-norelax} option to specify that
2750 @code{_AS__} should generate errors instead, if the target displacement
2751 is larger than 13 bits.
2753 This option does not affect the Compare-and-Jump instructions; the code
2754 emitted for them is @emph{always} adjusted when necessary (depending on
2755 displacement size), regardless of whether you use @samp{-norelax}.
2758 @node Floating Point-i960,,,
2759 _CHAPSEC__(1+_ALL_ARCH__) Floating Point
2760 @code{_AS__} generates IEEE floating-point numbers for the directives
2761 @samp{.float}, @samp{.double}, @samp{extended}, and @samp{.single}.
2764 @node Directives-i960,,,
2765 _CHAPSEC__(1+_ALL_ARCH__) Machine Directives
2768 _CHAPSEC__(2+_ALL_ARCH__) @code{.bss @var{symbol}, @var{length}, @var{align}}
2769 Reserve @var{length} bytes in the bss segment for a local @var{symbol},
2770 aligned to the power of two specified by @var{align}. @var{length} and
2771 @var{align} must be positive absolute expressions. This directive
2772 differs from @samp{.lcomm} only in that it permits you to specify
2773 an alignment. @xref{Lcomm}.
2776 @node extended-i960,,,
2777 _CHAPSEC__(2+_ALL_ARCH__) @code{.extended @var{flonums}}
2778 @code{.extended} expects zero or more flonums, separated by commas; for
2779 each flonum, @samp{.extended} emits an IEEE extended-format (80-bit)
2780 floating-point number.
2782 @node leafproc-i960,,,
2783 _CHAPSEC__(2+_ALL_ARCH__) @code{.leafproc @var{call-lab}, @var{bal-lab}}
2784 You can use the @samp{.leafproc} directive in conjunction with the
2785 optimized @code{callj} instruction to enable faster calls of leaf
2786 procedures. If a procedure is known to call no other procedures, you
2787 may define an entry point that skips procedure prolog code (and that does
2788 not depend on system-supplied saved context), and declare it as the
2789 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
2790 entry point that goes through the normal prolog, you can specify that
2791 entry point as @var{call-lab}.
2793 A @samp{.leafproc} declaration is meant for use in conjunction with the
2794 optimized call instruction @samp{callj}; the directive records the data
2795 needed later to choose between converting the @samp{callj} into a
2796 @code{bal} or a @code{call}.
2798 @var{call-lab} is optional; if only one argument is present, or if the
2799 two arguments are identical, the single argument is assumed to be the
2800 @code{bal} entry point.
2802 @node sysproc-i960,,,
2803 _CHAPSEC__(2+_ALL_ARCH__) @code{.sysproc @var{name}, @var{index}}
2804 The @samp{.sysproc} directive defines a name for a system procedure.
2805 After you define it using @samp{.sysproc}, you can use @var{name} to
2806 refer to the system procedure identified by @var{index} when calling
2807 procedures with the optimized call instruction @samp{callj}.
2809 Both arguments are required; @var{index} must be between 0 and 31
2812 @node Opcodes for i960,,,
2813 _CHAPSEC__(1+_ALL_ARCH__) i960 Opcodes
2814 All Intel 960 machine instructions are supported; @pxref{Options-i960}
2815 for a discussion of selecting the instruction subset for a particular
2816 960 architecture.@refill
2818 Some opcodes are processed beyond simply emitting a single corresponding
2819 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
2820 instructions with target displacements larger than 13 bits.
2823 _CHAPSEC__(2+_ALL_ARCH__) @code{callj}
2824 You can write @code{callj} to have the assembler or the linker determine
2825 the most appropriate form of subroutine call: @samp{call},
2826 @samp{bal}, or @samp{calls}. If the assembly source contains
2827 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
2828 defining the operand---then @code{_AS__} will translate the
2829 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
2830 for the linker to resolve.
2832 @node Compare-and-branch-i960
2833 _CHAPSEC__(2+_ALL_ARCH__) Compare-and-Branch
2835 The 960 architectures provide combined Compare-and-Branch instructions
2836 that permit you to store the branch target in the lower 13 bits of the
2837 instruction word itself. However, if you specify a branch target far
2838 enough away that its address won't fit in 13 bits, the assembler can
2839 either issue an error, or convert your Compare-and-Branch instruction
2840 into separate instructions to do the compare and the branch.
2842 Whether @code{_AS__} gives an error or expands the instruction depends
2843 on two choices you can make: whether you use the @samp{-norelax} option,
2844 and whether you use a ``Compare and Branch'' instruction or a ``Compare
2845 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
2846 expanded if necessary; the ``Branch'' instructions are expanded when
2847 necessary @emph{unless} you specify @code{-norelax}---in which case
2848 @code{_AS__} gives an error instead.
2850 These are the Compare-and-Branch instructions, their ``Jump'' variants,
2851 and the instruction pairs they may expand into:
2856 Branch Jump Expanded to
2857 ------ ------ ------------
2860 cmpibe cmpije cmpi; be
2861 cmpibg cmpijg cmpi; bg
2862 cmpibge cmpijge cmpi; bge
2863 cmpibl cmpijl cmpi; bl
2864 cmpible cmpijle cmpi; ble
2865 cmpibno cmpijno cmpi; bno
2866 cmpibne cmpijne cmpi; bne
2867 cmpibo cmpijo cmpi; bo
2868 cmpobe cmpoje cmpo; be
2869 cmpobg cmpojg cmpo; bg
2870 cmpobge cmpojge cmpo; bge
2871 cmpobl cmpojl cmpo; bl
2872 cmpoble cmpojle cmpo; ble
2873 cmpobne cmpojne cmpo; bne
2878 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
2879 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
2880 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
2881 bbc& & chkbit; bno\cr
2882 bbs& & chkbit; bo\cr
2883 cmpibe& cmpije& cmpi; be\cr
2884 cmpibg& cmpijg& cmpi; bg\cr
2885 cmpibge& cmpijge& cmpi; bge\cr
2886 cmpibl& cmpijl& cmpi; bl\cr
2887 cmpible& cmpijle& cmpi; ble\cr
2888 cmpibno& cmpijno& cmpi; bno\cr
2889 cmpibne& cmpijne& cmpi; bne\cr
2890 cmpibo& cmpijo& cmpi; bo\cr
2891 cmpobe& cmpoje& cmpo; be\cr
2892 cmpobg& cmpojg& cmpo; bg\cr
2893 cmpobge& cmpojge& cmpo; bge\cr
2894 cmpobl& cmpojl& cmpo; bl\cr
2895 cmpoble& cmpojle& cmpo; ble\cr
2896 cmpobne& cmpojne& cmpo; bne\cr}
2902 _CHAPSEC__(0+_ALL_ARCH__) M680x0 Dependent Features
2903 _CHAPSEC__(1+_ALL_ARCH__) M680x0 Options
2904 The Motorola 680x0 version of @code{_AS__} has two machine dependent options.
2905 One shortens undefined references from 32 to 16 bits, while the
2906 other is used to tell @code{_AS__} what kind of machine it is
2910 You can use the @kbd{-l} option to shorten the size of references to
2911 undefined symbols. If the @kbd{-l} option is not given, references to
2912 undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__}
2913 cannot know where these symbols will end up, @code{_AS__} can only allocate
2914 space for the linker to fill in later. Since @code{_AS__} doesn't know how
2915 far away these symbols will be, it allocates as much space as it can.)
2916 If this option is given, the references will only be one word wide (16
2917 bits). This may be useful if you want the object file to be as small as
2918 possible, and you know that the relevant symbols will be less than 17
2921 The 680x0 version of @code{_AS__} is most frequently used to assemble
2922 programs for the Motorola MC68020 microprocessor. Occasionally it is
2923 used to assemble programs for the mostly similar, but slightly different
2924 MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options
2925 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
2926 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
2929 _CHAPSEC__(1+_ALL_ARCH__) Syntax
2931 The 680x0 version of @code{_AS__} uses syntax similar to the Sun assembler.
2932 Size modifiers are appended directly to the end of the opcode without an
2933 intervening period. For example, write @samp{movl} rather than
2937 If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow
2938 Sun-style local labels of the form @samp{1$} through @samp{$9}.
2941 In the following table @dfn{apc} stands for any of the address
2942 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
2943 Program Counter (@samp{pc}), or the zero-address relative to the
2944 program counter (@samp{zpc}).
2946 The following addressing modes are understood:
2949 @samp{#@var{digits}}
2952 @samp{d0} through @samp{d7}
2954 @item Address Register
2955 @samp{a0} through @samp{a7}
2957 @item Address Register Indirect
2958 @samp{a0@@} through @samp{a7@@}
2960 @item Address Register Postincrement
2961 @samp{a0@@+} through @samp{a7@@+}
2963 @item Address Register Predecrement
2964 @samp{a0@@-} through @samp{a7@@-}
2966 @item Indirect Plus Offset
2967 @samp{@var{apc}@@(@var{digits})}
2970 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
2971 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
2974 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
2975 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
2978 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
2979 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
2981 @item Memory Indirect
2982 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
2985 @samp{@var{symbol}}, or @samp{@var{digits}}
2987 @c pesch@cygnus.com: gnu, rich concur the following needs careful
2988 @c research before documenting.
2989 , or either of the above followed
2990 by @samp{:b}, @samp{:w}, or @samp{:l}.
2994 _CHAPSEC__(1+_ALL_ARCH__) Floating Point
2995 The floating point code is not too well tested, and may have
2998 Packed decimal (P) format floating literals are not supported.
2999 Feel free to add the code!
3001 The floating point formats generated by directives are these.
3004 @code{Single} precision floating point constants.
3006 @code{Double} precision floating point constants.
3009 There is no directive to produce regions of memory holding
3010 extended precision numbers, however they can be used as
3011 immediate operands to floating-point instructions. Adding a
3012 directive to create extended precision numbers would not be
3013 hard, but it has not yet seemed necessary.
3015 _CHAPSEC__(1+_ALL_ARCH__) Machine Directives
3016 In order to be compatible with the Sun assembler the 680x0 assembler
3017 understands the following directives.
3020 This directive is identical to a @code{.data 1} directive.
3022 This directive is identical to a @code{.data 2} directive.
3024 This directive is identical to a @code{.align 1} directive.
3025 @c Is this true? does it work???
3027 This directive is identical to a @code{.space} directive.
3030 _CHAPSEC__(1+_ALL_ARCH__) Opcodes
3031 @c pesch@cygnus.com: I don't see any point in the following
3032 @c paragraph. Bugs are bugs; how does saying this
3035 Danger: Several bugs have been found in the opcode table (and
3036 fixed). More bugs may exist. Be careful when using obscure
3040 _CHAPSEC__(2+_ALL_ARCH__) Branch Improvement
3042 Certain pseudo opcodes are permitted for branch instructions.
3043 They expand to the shortest branch instruction that will reach the
3044 target. Generally these mnemonics are made by substituting @samp{j} for
3045 @samp{b} at the start of a Motorola mnemonic.
3047 The following table summarizes the pseudo-operations. A @code{*} flags
3048 cases that are more fully described after the table:
3052 +---------------------------------------------------------
3054 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
3055 +---------------------------------------------------------
3056 jbsr |bsrs bsr bsrl jsr jsr
3057 jra |bras bra bral jmp jmp
3058 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
3059 * dbXX |dbXX dbXX dbXX; bra; jmpl
3060 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
3063 NX: negative of condition XX
3066 @center{@code{*}---see full description below}
3071 These are the simplest jump pseudo-operations; they always map to one
3072 particular machine instruction, depending on the displacement to the
3076 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
3077 where @var{XX} is a conditional branch or condition-code test. The full
3078 list of pseudo-ops in this family is:
3080 jhi jls jcc jcs jne jeq jvc
3081 jvs jpl jmi jge jlt jgt jle
3084 For the cases of non-PC relative displacements and long displacements on
3085 the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of
3086 @var{NX}, the opposite condition to @var{XX}:
3098 The full family of pseudo-operations covered here is
3100 dbhi dbls dbcc dbcs dbne dbeq dbvc
3101 dbvs dbpl dbmi dbge dblt dbgt dble
3105 Other than for word and byte displacements, when the source reads
3106 @samp{db@var{XX} foo}, @code{_AS__} will emit
3115 This family includes
3117 fjne fjeq fjge fjlt fjgt fjle fjf
3118 fjt fjgl fjgle fjnge fjngl fjngle fjngt
3119 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
3120 fjor fjseq fjsf fjsne fjst fjueq fjuge
3121 fjugt fjule fjult fjun
3124 For branch targets that are not PC relative, @code{_AS__} emits
3130 when it encounters @samp{fj@var{XX} foo}.
3134 _CHAPSEC__(2+_ALL_ARCH__) Special Characters
3135 The immediate character is @samp{#} for Sun compatibility. The
3136 line-comment character is @samp{|}. If a @samp{#} appears at the
3137 beginning of a line, it is treated as a comment unless it looks like
3138 @samp{# line file}, in which case it is treated normally.
3140 @c pesch@cygnus.com: conditionalize on something other than 0 when filled in.
3144 The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to
3145 specify thiat it is compiling for a 32032 processor, or a
3146 @kbd{-m32532} to specify that it is compiling for a 32532 option.
3147 The default (if neither is specified) is chosen when the assembler
3151 I don't know anything about the 32x32 syntax assembled by
3152 @code{_AS__}. Someone who undersands the processor (I've never seen
3153 one) and the possible syntaxes should write this section.
3155 @subsection Floating Point
3156 The 32x32 uses IEEE floating point numbers, but @code{_AS__} will only
3157 create single or double precision values. I don't know if the 32x32
3158 understands extended precision numbers.
3160 @subsection Machine Directives
3161 The 32x32 has no machine dependent directives.
3164 @c fixme (sparc): Fill in "syntax" section!
3165 _CHAPSEC__(0+_ALL_ARCH__) SPARC Dependent Features
3168 The sparc has no machine dependent options.
3171 I don't know anything about Sparc syntax. Someone who does
3172 will have to write this section.
3174 @subsection Floating Point
3175 The Sparc uses ieee floating-point numbers.
3177 @subsection Machine Directives
3178 The Sparc version of @code{_AS__} supports the following additional
3183 This must be followed by a symbol name, a positive number, and
3184 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
3185 syntax is different.
3188 This is functionally identical to @code{.globl}.
3191 This is functionally identical to @code{.short}.
3194 This directive is ignored. Any text following it on the same
3195 line is also ignored.
3198 This must be followed by a symbol name, a positive number, and
3199 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
3200 syntax is different.
3203 This must be followed by @code{"text"}, @code{"data"}, or
3204 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
3208 This is functionally identical to the .space directive.
3211 On the Sparc, the .word directive produces 32 bit values,
3212 instead of the 16 bit values it produces on every other machine.
3217 _CHAPSEC__(0+_ALL_ARCH__) 80386 Dependent Features
3218 _CHAPSEC__(1+_ALL_ARCH__) Options
3219 The 80386 has no machine dependent options.
3221 _CHAPSEC__(1+_ALL_ARCH__) AT&T Syntax versus Intel Syntax
3222 In order to maintain compatibility with the output of @code{_GCC__},
3223 @code{_AS__} supports AT&T System V/386 assembler syntax. This is quite
3224 different from Intel syntax. We mention these differences because
3225 almost all 80386 documents used only Intel syntax. Notable differences
3226 between the two syntaxes are:
3229 AT&T immediate operands are preceded by @samp{$}; Intel immediate
3230 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
3231 AT&T register operands are preceded by @samp{%}; Intel register operands
3232 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
3233 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
3236 AT&T and Intel syntax use the opposite order for source and destination
3237 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
3238 @samp{source, dest} convention is maintained for compatibility with
3239 previous Unix assemblers.
3242 In AT&T syntax the size of memory operands is determined from the last
3243 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
3244 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
3245 memory references. Intel syntax accomplishes this by prefixes memory
3246 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
3247 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
3248 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
3251 Immediate form long jumps and calls are
3252 @samp{lcall/ljmp $@var{segment}, $@var{offset}} in AT&T syntax; the
3254 @samp{call/jmp far @var{segment}:@var{offset}}. Also, the far return
3256 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
3257 @samp{ret far @var{stack-adjust}}.
3260 The AT&T assembler does not provide support for multiple segment
3261 programs. Unix style systems expect all programs to be single segments.
3264 _CHAPSEC__(1+_ALL_ARCH__) Opcode Naming
3265 Opcode names are suffixed with one character modifiers which specify the
3266 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
3267 byte, word, and long operands. If no suffix is specified by an
3268 instruction and it contains no memory operands then @code{_AS__} tries to
3269 fill in the missing suffix based on the destination register operand
3270 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
3271 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
3272 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
3273 assembler which assumes that a missing opcode suffix implies long
3274 operand size. (This incompatibility does not affect compiler output
3275 since compilers always explicitly specify the opcode suffix.)
3277 Almost all opcodes have the same names in AT&T and Intel format. There
3278 are a few exceptions. The sign extend and zero extend instructions need
3279 two sizes to specify them. They need a size to sign/zero extend
3280 @emph{from} and a size to zero extend @emph{to}. This is accomplished
3281 by using two opcode suffixes in AT&T syntax. Base names for sign extend
3282 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
3283 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
3284 suffixes are tacked on to this base name, the @emph{from} suffix before
3285 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
3286 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
3287 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
3288 and @samp{wl} (from word to long).
3290 The Intel syntax conversion instructions
3293 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
3295 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
3297 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
3299 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
3301 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
3302 AT&T naming. @code{_AS__} accepts either naming for these instructions.
3304 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
3305 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
3308 _CHAPSEC__(1+_ALL_ARCH__) Register Naming
3309 Register operands are always prefixes with @samp{%}. The 80386 registers
3313 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
3314 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
3315 frame pointer), and @samp{%esp} (the stack pointer).
3318 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
3319 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
3322 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
3323 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
3324 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
3325 @samp{%cx}, and @samp{%dx})
3328 the 6 segment registers @samp{%cs} (code segment), @samp{%ds}
3329 (data segment), @samp{%ss} (stack segment), @samp{%es}, @samp{%fs},
3333 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
3337 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
3338 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
3341 the 2 test registers @samp{%tr6} and @samp{%tr7}.
3344 the 8 floating point register stack @samp{%st} or equivalently
3345 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
3346 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
3349 _CHAPSEC__(1+_ALL_ARCH__) Opcode Prefixes
3350 Opcode prefixes are used to modify the following opcode. They are used
3351 to repeat string instructions, to provide segment overrides, to perform
3352 bus lock operations, and to give operand and address size (16-bit
3353 operands are specified in an instruction by prefixing what would
3354 normally be 32-bit operands with a ``operand size'' opcode prefix).
3355 Opcode prefixes are usually given as single-line instructions with no
3356 operands, and must directly precede the instruction they act upon. For
3357 example, the @samp{scas} (scan string) instruction is repeated with:
3363 Here is a list of opcode prefixes:
3366 Segment override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
3367 @samp{fs}, @samp{gs}. These are automatically added by specifying
3368 using the @var{segment}:@var{memory-operand} form for memory references.
3371 Operand/Address size prefixes @samp{data16} and @samp{addr16}
3372 change 32-bit operands/addresses into 16-bit operands/addresses. Note
3373 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
3374 are not supported (yet).
3377 The bus lock prefix @samp{lock} inhibits interrupts during
3378 execution of the instruction it precedes. (This is only valid with
3379 certain instructions; see a 80386 manual for details).
3382 The wait for coprocessor prefix @samp{wait} waits for the
3383 coprocessor to complete the current instruction. This should never be
3384 needed for the 80386/80387 combination.
3387 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
3388 to string instructions to make them repeat @samp{%ecx} times.
3391 _CHAPSEC__(1+_ALL_ARCH__) Memory References
3392 An Intel syntax indirect memory reference of the form
3394 @var{segment}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
3396 is translated into the AT&T syntax
3398 @var{segment}:@var{disp}(@var{base}, @var{index}, @var{scale})
3400 where @var{base} and @var{index} are the optional 32-bit base and
3401 index registers, @var{disp} is the optional displacement, and
3402 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
3403 to calculate the address of the operand. If no @var{scale} is
3404 specified, @var{scale} is taken to be 1. @var{segment} specifies the
3405 optional segment register for the memory operand, and may override the
3406 default segment register (see a 80386 manual for segment register
3407 defaults). Note that segment overrides in AT&T syntax @emph{must} have
3408 be preceded by a @samp{%}. If you specify a segment override which
3409 coincides with the default segment register, @code{_AS__} will @emph{not}
3410 output any segment register override prefixes to assemble the given
3411 instruction. Thus, segment overrides can be specified to emphasize which
3412 segment register is used for a given memory operand.
3414 Here are some examples of Intel and AT&T style memory references:
3417 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
3418 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{segment} is
3419 missing, and the default segment is used (@samp{%ss} for addressing with
3420 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
3422 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
3423 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
3424 @samp{foo}. All other fields are missing. The segment register here
3425 defaults to @samp{%ds}.
3427 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
3428 This uses the value pointed to by @samp{foo} as a memory operand.
3429 Note that @var{base} and @var{index} are both missing, but there is only
3430 @emph{one} @samp{,}. This is a syntactic exception.
3432 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
3433 This selects the contents of the variable @samp{foo} with segment
3434 register @var{segment} being @samp{%gs}.
3438 Absolute (as opposed to PC relative) call and jump operands must be
3439 prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will
3440 always choose PC relative addressing for jump/call labels.
3442 Any instruction that has a memory operand @emph{must} specify its size (byte,
3443 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
3446 _CHAPSEC__(1+_ALL_ARCH__) Handling of Jump Instructions
3447 Jump instructions are always optimized to use the smallest possible
3448 displacements. This is accomplished by using byte (8-bit) displacement
3449 jumps whenever the target is sufficiently close. If a byte displacement
3450 is insufficient a long (32-bit) displacement is used. We do not support
3451 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
3452 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
3453 @samp{%eip} to 16 bits after the word displacement is added.
3455 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
3456 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
3457 byte displacements, so that it is possible that use of these
3458 instructions (@code{_GCC__} does not use them) will cause the assembler to
3459 print an error message (and generate incorrect code). The AT&T 80386
3460 assembler tries to get around this problem by expanding @samp{jcxz foo} to
3468 _CHAPSEC__(1+_ALL_ARCH__) Floating Point
3469 All 80387 floating point types except packed BCD are supported.
3470 (BCD support may be added without much difficulty). These data
3471 types are 16-, 32-, and 64- bit integers, and single (32-bit),
3472 double (64-bit), and extended (80-bit) precision floating point.
3473 Each supported type has an opcode suffix and a constructor
3474 associated with it. Opcode suffixes specify operand's data
3475 types. Constructors build these data types into memory.
3479 Floating point constructors are @samp{.float} or @samp{.single},
3480 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
3481 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
3482 @samp{t} stands for temporary real, and that the 80387 only supports
3483 this format via the @samp{fldt} (load temporary real to stack top) and
3484 @samp{fstpt} (store temporary real and pop stack) instructions.
3487 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
3488 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
3489 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
3490 (quad). As with the temporary real format the 64-bit @samp{q} format is
3491 only present in the @samp{fildq} (load quad integer to stack top) and
3492 @samp{fistpq} (store quad integer and pop stack) instructions.
3495 Register to register operations do not require opcode suffixes,
3496 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
3498 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
3499 instructions are almost never needed (this is not the case for the
3500 80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses
3501 the @samp{fwait} instruction whenever it is implicitly selected by one
3502 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
3503 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
3504 instructions are made equivalent to @samp{f@dots{}} instructions. If
3505 @samp{fwait} is desired it must be explicitly coded.
3507 _CHAPSEC__(1+_ALL_ARCH__) Notes
3508 There is some trickery concerning the @samp{mul} and @samp{imul}
3509 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
3510 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
3511 for @samp{imul}) can be output only in the one operand form. Thus,
3512 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
3513 the expanding multiply would clobber the @samp{%edx} register, and this
3514 would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the
3515 64-bit product in @samp{%edx:%eax}.
3517 We have added a two operand form of @samp{imul} when the first operand
3518 is an immediate mode expression and the second operand is a register.
3519 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
3520 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
3524 @c pesch@cygnus.com: we ignore the following chapters, since internals are
3525 @c changing rapidly. These may need to be moved to another
3526 @c book anyhow, if we adopt the model of user/modifier
3528 @node Maintenance, Retargeting, _MACH_DEP__, Top
3529 @chapter Maintaining the Assembler
3530 [[this chapter is still being built]]
3533 We had these goals, in descending priority:
3536 For every program composed by a compiler, @code{_AS__} should emit
3537 ``correct'' code. This leaves some latitude in choosing addressing
3538 modes, order of @code{relocation_info} structures in the object
3541 @item Speed, for usual case.
3542 By far the most common use of @code{_AS__} will be assembling compiler
3545 @item Upward compatibility for existing assembler code.
3546 Well @dots{} we don't support Vax bit fields but everything else
3547 seems to be upward compatible.
3550 The code should be maintainable with few surprises. (JF: ha!)
3554 We assumed that disk I/O was slow and expensive while memory was
3555 fast and access to memory was cheap. We expect the in-memory data
3556 structures to be less than 10 times the size of the emitted object
3557 file. (Contrast this with the C compiler where in-memory structures
3558 might be 100 times object file size!)
3562 Try to read the source file from disk only one time. For other
3563 reasons, we keep large chunks of the source file in memory during
3564 assembly so this is not a problem. Also the assembly algorithm
3565 should only scan the source text once if the compiler composed the
3566 text according to a few simple rules.
3568 Emit the object code bytes only once. Don't store values and then
3571 Build the object file in memory and do direct writes to disk of
3575 RMS suggested a one-pass algorithm which seems to work well. By not
3576 parsing text during a second pass considerable time is saved on
3577 large programs (@emph{e.g.} the sort of C program @code{yacc} would
3580 It happened that the data structures needed to emit relocation
3581 information to the object file were neatly subsumed into the data
3582 structures that do backpatching of addresses after pass 1.
3584 Many of the functions began life as re-usable modules, loosely
3585 connected. RMS changed this to gain speed. For example, input
3586 parsing routines which used to work on pre-sanitized strings now
3587 must parse raw data. Hence they have to import knowledge of the
3588 assemblers' comment conventions @emph{etc}.
3590 @section Deprecated Feature(?)s
3591 We have stopped supporting some features:
3594 @code{.org} statements must have @b{defined} expressions.
3596 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
3599 It might be a good idea to not support these features in a future release:
3602 @kbd{#} should begin a comment, even in column 1.
3604 Why support the logical line & file concept any more?
3606 Subsegments are a good candidate for flushing.
3607 Depends on which compilers need them I guess.
3610 @section Bugs, Ideas, Further Work
3611 Clearly the major improvement is DON'T USE A TEXT-READING
3612 ASSEMBLER for the back end of a compiler. It is much faster to
3613 interpret binary gobbledygook from a compiler's tables than to
3614 ask the compiler to write out human-readable code just so the
3615 assembler can parse it back to binary.
3617 Assuming you use @code{_AS__} for human written programs: here are
3621 Document (here) @code{APP}.
3623 Take advantage of knowing no spaces except after opcode
3624 to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces:
3625 only keep space/tabs at begin of line or between 2
3628 Put pointers in this documentation to @file{a.out} documentation.
3630 Split the assembler into parts so it can gobble direct binary
3631 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
3632 just so @code{_AS__} can parse it back to binary.
3634 Rewrite hash functions: I want a more modular, faster library.
3636 Clean up LOTS of code.
3638 Include all the non-@file{.c} files in the maintenance chapter.
3642 Implement flonum short literals.
3644 Change all talk of expression operands to expression quantities,
3645 or perhaps to expression arguments.
3649 Whenever a @code{.text} or @code{.data} statement is seen, we close
3650 of the current frag with an imaginary @code{.fill 0}. This is
3651 because we only have one obstack for frags, and we can't grow new
3652 frags for a new subsegment, then go back to the old subsegment and
3653 append bytes to the old frag. All this nonsense goes away if we
3654 give each subsegment its own obstack. It makes code simpler in
3655 about 10 places, but nobody has bothered to do it because C compiler
3656 output rarely changes subsegments (compared to ending frags with
3657 relaxable addresses, which is common).
3661 @c The following files in the @file{_AS__} directory
3662 @c are symbolic links to other files, of
3663 @c the same name, in a different directory.
3666 @c @file{atof_generic.c}
3668 @c @file{atof_vax.c}
3670 @c @file{flonum_const.c}
3672 @c @file{flonum_copy.c}
3674 @c @file{flonum_get.c}
3676 @c @file{flonum_multip.c}
3678 @c @file{flonum_normal.c}
3680 @c @file{flonum_print.c}
3683 Here is a list of the source files in the @file{_AS__} directory.
3687 This contains the pre-processing phase, which deletes comments,
3688 handles whitespace, etc. This was recently re-written, since app
3689 used to be a separate program, but RMS wanted it to be inline.
3692 This is a subroutine to append a string to another string returning a
3693 pointer just after the last @code{char} appended. (JF: All these
3694 little routines should probably all be put in one file.)
3697 Here you will find the main program of the assembler @code{_AS__}.
3700 This is a branch office of @file{read.c}. This understands
3701 expressions, arguments. Inside @code{_AS__}, arguments are called
3702 (expression) @emph{operands}. This is confusing, because we also talk
3703 (elsewhere) about instruction @emph{operands}. Also, expression
3704 operands are called @emph{quantities} explicitly to avoid confusion
3705 with instruction operands. What a mess.
3708 This implements the @b{frag} concept. Without frags, finding the
3709 right size for branch instructions would be a lot harder.
3712 This contains the symbol table, opcode table @emph{etc.} hashing
3716 This is a table of values of digits, for use in atoi() type
3717 functions. Could probably be flushed by using calls to strtol(), or
3721 This contains Operating system dependent source file reading
3722 routines. Since error messages often say where we are in reading
3723 the source file, they live here too. Since @code{_AS__} is intended to
3724 run under GNU and Unix only, this might be worth flushing. Anyway,
3725 almost all C compilers support stdio.
3728 This deals with calling the pre-processor (if needed) and feeding the
3729 chunks back to the rest of the assembler the right way.
3732 This contains operating system independent parts of fatal and
3733 warning message reporting. See @file{append.c} above.
3736 This contains operating system dependent functions that write an
3737 object file for @code{_AS__}. See @file{input-file.c} above.
3740 This implements all the directives of @code{_AS__}. This also deals
3741 with passing input lines to the machine dependent part of the
3745 This is a C library function that isn't in most C libraries yet.
3746 See @file{append.c} above.
3749 This implements subsegments.
3752 This implements symbols.
3755 This contains the code to perform relaxation, and to write out
3756 the object file. It is mostly operating system independent, but
3757 different OSes have different object file formats in any case.
3760 This implements @code{malloc()} or bust. See @file{append.c} above.
3763 This implements @code{realloc()} or bust. See @file{append.c} above.
3765 @item atof-generic.c
3766 The following files were taken from a machine-independent subroutine
3767 library for manipulating floating point numbers and very large
3770 @file{atof-generic.c} turns a string into a flonum internal format
3771 floating-point number.
3773 @item flonum-const.c
3774 This contains some potentially useful floating point numbers in
3778 This copies a flonum.
3780 @item flonum-multip.c
3781 This multiplies two flonums together.
3784 This copies a bignum.
3788 Here is a table of all the machine-specific files (this includes
3789 both source and header files). Typically, there is a
3790 @var{machine}.c file, a @var{machine}-opcode.h file, and an
3791 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
3792 be identical to the one used by GDB (which uses it for disassembly.)
3797 This contains code to turn a flonum into a ieee literal constant.
3798 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}.
3801 This is the opcode-table for the i386 version of the assembler.
3804 This contains all the code for the i386 version of the assembler.
3807 This defines constants and macros used by the i386 version of the assembler.
3810 generic 68020 header file. To be linked to m68k.h on a
3811 non-sun3, non-hpux system.
3814 68010 header file for Sun2 workstations. Not well tested. To be linked
3815 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
3819 68020 header file for Sun3 workstations. To be linked to m68k.h before
3820 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
3824 68020 header file for a HPUX (system 5?) box. Which box, which
3825 version of HPUX, etc? I don't know.
3828 A hard- or symbolic- link to one of @file{m-generic.h},
3829 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
3830 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
3834 Opcode table for 68020. This is now a link to the opcode table
3835 in the @code{GDB} source directory.
3838 All the mc680x0 code, in one huge, slow-to-compile file.
3841 This contains the code for the ns32032/ns32532 version of the
3844 @item ns32k-opcode.h
3845 This contains the opcode table for the ns32032/ns32532 version
3849 Vax specific file for describing Vax operands and other Vax-ish things.
3855 Vax specific parts of @code{_AS__}. Also includes the former files
3856 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
3859 Turns a flonum into a Vax constant.
3862 This file contains the special code needed to put out a VMS
3863 style object file for the Vax.
3867 Here is a list of the header files in the source directory.
3868 (Warning: This section may not be very accurate. I didn't
3869 write the header files; I just report them.) Also note that I
3870 think many of these header files could be cleaned up or
3876 This describes the structures used to create the binary header data
3877 inside the object file. Perhaps we should use the one in
3878 @file{/usr/include}?
3881 This defines all the globally useful things, and pulls in _0__<stdio.h>_1__
3882 and _0__<assert.h>_1__.
3885 This defines macros useful for dealing with bignums.
3888 Structure and macros for dealing with expression()
3891 This defines the structure for dealing with floating point
3892 numbers. It #includes @file{bignum.h}.
3895 This contains macro for appending a byte to the current frag.
3898 Structures and function definitions for the hashing functions.
3901 Function headers for the input-file.c functions.
3904 structures and function headers for things defined in the
3905 machine dependent part of the assembler.
3908 This is the GNU systemwide include file for manipulating obstacks.
3909 Since nobody is running under real GNU yet, we include this file.
3912 Macros and function headers for reading in source files.
3914 @item struct-symbol.h
3915 Structure definition and macros for dealing with the _AS__
3916 internal form of a symbol.
3919 structure definition for dealing with the numbered subsegments
3920 of the text and data segments.
3923 Macros and function headers for dealing with symbols.
3926 Structure for doing segment fixups.
3929 @comment ~subsection Test Directory
3930 @comment (Note: The test directory seems to have disappeared somewhere
3931 @comment along the line. If you want it, you'll probably have to find a
3932 @comment REALLY OLD dump tape~dots{})
3934 @comment The ~file{test/} directory is used for regression testing.
3935 @comment After you modify ~@code{_AS__}, you can get a quick go/nogo
3936 @comment confidence test by running the new ~@code{_AS__} over the source
3937 @comment files in this directory. You use a shell script ~file{test/do}.
3939 @comment The tests in this suite are evolving. They are not comprehensive.
3940 @comment They have, however, caught hundreds of bugs early in the debugging
3941 @comment cycle of ~@code{_AS__}. Most test statements in this suite were naturally
3942 @comment selected: they were used to demonstrate actual ~@code{_AS__} bugs rather
3943 @comment than being written ~i{a prioi}.
3945 @comment Another testing suggestion: over 30 bugs have been found simply by
3946 @comment running examples from this manual through ~@code{_AS__}.
3947 @comment Some examples in this manual are selected
3948 @comment to distinguish boundary conditions; they are good for testing ~@code{_AS__}.
3950 @comment ~subsubsection Regression Testing
3951 @comment Each regression test involves assembling a file and comparing the
3952 @comment actual output of ~@code{_AS__} to ``known good'' output files. Both
3953 @comment the object file and the error/warning message file (stderr) are
3954 @comment inspected. Optionally the ~@code{_AS__} exit status may be checked.
3955 @comment Discrepencies are reported. Each discrepency means either that
3956 @comment you broke some part of ~@code{_AS__} or that the ``known good'' files
3957 @comment are now out of date and should be changed to reflect the new
3958 @comment definition of ``good''.
3960 @comment Each regression test lives in its own directory, in a tree
3961 @comment rooted in the directory ~file{test/}. Each such directory
3962 @comment has a name ending in ~file{.ret}, where `ret' stands for
3963 @comment REgression Test. The ~file{.ret} ending allows ~code{find
3964 @comment (1)} to find all regression tests in the tree, without
3965 @comment needing to list them explicitly.
3967 @comment Any ~file{.ret} directory must contain a file called
3968 @comment ~file{input} which is the source file to assemble. During
3969 @comment testing an object file ~file{output} is created, as well as
3970 @comment a file ~file{stdouterr} which contains the output to both
3971 @comment stderr and stderr. If there is a file ~file{output.good} in
3972 @comment the directory, and if ~file{output} contains exactly the
3973 @comment same data as ~file{output.good}, the file ~file{output} is
3974 @comment deleted. Likewise ~file{stdouterr} is removed if it exactly
3975 @comment matches a file ~file{stdouterr.good}. If file
3976 @comment ~file{status.good} is present, containing a decimal number
3977 @comment before a newline, the exit status of ~@code{_AS__} is compared
3978 @comment to this number. If the status numbers are not equal, a file
3979 @comment ~file{status} is written to the directory, containing the
3980 @comment actual status as a decimal number followed by newline.
3982 @comment Should any of the ~file{*.good} files fail to match their corresponding
3983 @comment actual files, this is noted by a 1-line message on the screen during
3984 @comment the regression test, and you can use ~@code{find (1)} to find any
3985 @comment files named ~file{status}, ~file {output} or ~file{stdouterr}.
3987 @node Retargeting, License, Maintenance, Top
3988 @chapter Teaching the Assembler about a New Machine
3990 This chapter describes the steps required in order to make the
3991 assembler work with another machine's assembly language. This
3992 chapter is not complete, and only describes the steps in the
3993 broadest terms. You should look at the source for the
3994 currently supported machine in order to discover some of the
3995 details that aren't mentioned here.
3997 You should create a new file called @file{@var{machine}.c}, and
3998 add the appropriate lines to the file @file{Makefile} so that
3999 you can compile your new version of the assembler. This should
4000 be straighforward; simply add lines similar to the ones there
4001 for the four current versions of the assembler.
4003 If you want to be compatible with GDB, (and the current
4004 machine-dependent versions of the assembler), you should create
4005 a file called @file{@var{machine}-opcode.h} which should
4006 contain all the information about the names of the machine
4007 instructions, their opcodes, and what addressing modes they
4008 support. If you do this right, the assembler and GDB can share
4009 this file, and you'll only have to write it once. Note that
4010 while you're writing @code{_AS__}, you may want to use an
4011 independent program (if you have access to one), to make sure
4012 that @code{_AS__} is emitting the correct bytes. Since @code{_AS__}
4013 and @code{GDB} share the opcode table, an incorrect opcode
4014 table entry may make invalid bytes look OK when you disassemble
4015 them with @code{GDB}.
4017 @section Functions You will Have to Write
4019 Your file @file{@var{machine}.c} should contain definitions for
4020 the following functions and variables. It will need to include
4021 some header files in order to use some of the structures
4022 defined in the machine-independent part of the assembler. The
4023 needed header files are mentioned in the descriptions of the
4024 functions that will need them.
4029 This long integer holds the value to place at the beginning of
4030 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
4031 machines that store additional information in the magic-number.
4033 @item char comment_chars[];
4034 This character array holds the values of the characters that
4035 start a comment anywhere in a line. Comments are stripped off
4036 automatically by the machine independent part of the
4037 assembler. Note that the @samp{/*} will always start a
4038 comment, and that only @samp{*/} will end a comment started by
4041 @item char line_comment_chars[];
4042 This character array holds the values of the chars that start a
4043 comment only if they are the first (non-whitespace) character
4044 on a line. If the character @samp{#} does not appear in this
4045 list, you may get unexpected results. (Various
4046 machine-independent parts of the assembler treat the comments
4047 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
4048 that start with @samp{#} are comments.)
4050 @item char EXP_CHARS[];
4051 This character array holds the letters that can separate the
4052 mantissa and the exponent of a floating point number. Typical
4053 values are @samp{e} and @samp{E}.
4055 @item char FLT_CHARS[];
4056 This character array holds the letters that--when they appear
4057 immediately after a leading zero--indicate that a number is a
4058 floating-point number. (Sort of how 0x indicates that a
4059 hexadecimal number follows.)
4061 @item pseudo_typeS md_pseudo_table[];
4062 (@var{pseudo_typeS} is defined in @file{md.h})
4063 This array contains a list of the machine_dependent directives
4064 the assembler must support. It contains the name of each
4065 pseudo op (Without the leading @samp{.}), a pointer to a
4066 function to be called when that directive is encountered, and
4067 an integer argument to be passed to that function.
4069 @item void md_begin(void)
4070 This function is called as part of the assembler's
4071 initialization. It should do any initialization required by
4072 any of your other routines.
4074 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
4075 This routine is called once for each option on the command line
4076 that the machine-independent part of @code{_AS__} does not
4077 understand. This function should return non-zero if the option
4078 pointed to by @var{optionPTR} is a valid option. If it is not
4079 a valid option, this routine should return zero. The variables
4080 @var{argcPTR} and @var{argvPTR} are provided in case the option
4081 requires a filename or something similar as an argument. If
4082 the option is multi-character, @var{optionPTR} should be
4083 advanced past the end of the option, otherwise every letter in
4084 the option will be treated as a separate single-character
4087 @item void md_assemble(char *string)
4088 This routine is called for every machine-dependent
4089 non-directive line in the source file. It does all the real
4090 work involved in reading the opcode, parsing the operands,
4091 etc. @var{string} is a pointer to a null-terminated string,
4092 that comprises the input line, with all excess whitespace and
4095 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
4096 This routine is called to turn a C long int, short int, or char
4097 into the series of bytes that represents that number on the
4098 target machine. @var{outputPTR} points to an array where the
4099 result should be stored; @var{value} is the value to store; and
4100 @var{nbytes} is the number of bytes in 'value' that should be
4103 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
4104 This routine is called to turn a C long int, short int, or char
4105 into the series of bytes that represent an immediate value on
4106 the target machine. It is identical to the function @code{md_number_to_chars},
4107 except on NS32K machines.@refill
4109 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
4110 This routine is called to turn a C long int, short int, or char
4111 into the series of bytes that represent an displacement value on
4112 the target machine. It is identical to the function @code{md_number_to_chars},
4113 except on NS32K machines.@refill
4115 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
4116 This routine is identical to @code{md_number_to_chars},
4117 except on NS32K machines.
4119 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
4120 (@code{struct relocation_info} is defined in @file{a.out.h})
4121 This routine emits the relocation info in @var{ri}
4122 in the appropriate bit-pattern for the target machine.
4123 The result should be stored in the location pointed
4124 to by @var{riPTR}. This routine may be a no-op unless you are
4125 attempting to do cross-assembly.
4127 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
4128 This routine turns a series of digits into the appropriate
4129 internal representation for a floating-point number.
4130 @var{type} is a character from @var{FLT_CHARS[]} that describes
4131 what kind of floating point number is wanted; @var{outputPTR}
4132 is a pointer to an array that the result should be stored in;
4133 and @var{sizePTR} is a pointer to an integer where the size (in
4134 bytes) of the result should be stored. This routine should
4135 return an error message, or an empty string (not (char *)0) for
4138 @item int md_short_jump_size;
4139 This variable holds the (maximum) size in bytes of a short (16
4140 bit or so) jump created by @code{md_create_short_jump()}. This
4141 variable is used as part of the broken-word feature, and isn't
4142 needed if the assembler is compiled with
4143 @samp{-DWORKING_DOT_WORD}.
4145 @item int md_long_jump_size;
4146 This variable holds the (maximum) size in bytes of a long (32
4147 bit or so) jump created by @code{md_create_long_jump()}. This
4148 variable is used as part of the broken-word feature, and isn't
4149 needed if the assembler is compiled with
4150 @samp{-DWORKING_DOT_WORD}.
4152 @item void md_create_short_jump(char *resultPTR,long from_addr,
4153 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
4154 This function emits a jump from @var{from_addr} to @var{to_addr} in
4155 the array of bytes pointed to by @var{resultPTR}. If this creates a
4156 type of jump that must be relocated, this function should call
4157 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
4158 emitted by this function may be smaller than @var{md_short_jump_size},
4159 but it must never create a larger one.
4160 (If it creates a smaller jump, the extra bytes of memory will not be
4161 used.) This function is used as part of the broken-word feature,
4162 and isn't needed if the assembler is compiled with
4163 @samp{-DWORKING_DOT_WORD}.@refill
4165 @item void md_create_long_jump(char *ptr,long from_addr,
4166 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
4167 This function is similar to the previous function,
4168 @code{md_create_short_jump()}, except that it creates a long
4169 jump instead of a short one. This function is used as part of
4170 the broken-word feature, and isn't needed if the assembler is
4171 compiled with @samp{-DWORKING_DOT_WORD}.
4173 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
4174 This function does the initial setting up for relaxation. This
4175 includes forcing references to still-undefined symbols to the
4176 appropriate addressing modes.
4178 @item relax_typeS md_relax_table[];
4179 (relax_typeS is defined in md.h)
4180 This array describes the various machine dependent states a
4181 frag may be in before relaxation. You will need one group of
4182 entries for each type of addressing mode you intend to relax.
4184 @item void md_convert_frag(fragS *fragPTR)
4185 (@var{fragS} is defined in @file{as.h})
4186 This routine does the required cleanup after relaxation.
4187 Relaxation has changed the type of the frag to a type that can
4188 reach its destination. This function should adjust the opcode
4189 of the frag to use the appropriate addressing mode.
4190 @var{fragPTR} points to the frag to clean up.
4192 @item void md_end(void)
4193 This function is called just before the assembler exits. It
4194 need not free up memory unless the operating system doesn't do
4195 it automatically on exit. (In which case you'll also have to
4196 track down all the other places where the assembler allocates
4197 space but never frees it.)
4201 @section External Variables You will Need to Use
4203 You will need to refer to or change the following external variables
4204 from within the machine-dependent part of the assembler.
4207 @item extern char flagseen[];
4208 This array holds non-zero values in locations corresponding to
4209 the options that were on the command line. Thus, if the
4210 assembler was called with @samp{-W}, @var{flagseen['W']} would
4213 @item extern fragS *frag_now;
4214 This pointer points to the current frag--the frag that bytes
4215 are currently being added to. If nothing else, you will need
4216 to pass it as an argument to various machine-independent
4217 functions. It is maintained automatically by the
4218 frag-manipulating functions; you should never have to change it
4221 @item extern LITTLENUM_TYPE generic_bignum[];
4222 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
4223 This is where @dfn{bignums}--numbers larger than 32 bits--are
4224 returned when they are encountered in an expression. You will
4225 need to use this if you need to implement directives (or
4226 anything else) that must deal with these large numbers.
4227 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
4228 @file{as.h}, and have a positive @code{X_add_number}. The
4229 @code{X_add_number} of a @code{bignum} is the number of
4230 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
4233 @item extern FLONUM_TYPE generic_floating_point_number;
4234 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
4235 The is where @dfn{flonums}--floating-point numbers within
4236 expressions--are returned. @code{Flonums} are of @code{segT}
4237 @code{SEG_BIG}, and have a negative @code{X_add_number}.
4238 @code{Flonums} are returned in a generic format. You will have
4239 to write a routine to turn this generic format into the
4240 appropriate floating-point format for your machine.
4242 @item extern int need_pass_2;
4243 If this variable is non-zero, the assembler has encountered an
4244 expression that cannot be assembled in a single pass. Since
4245 the second pass isn't implemented, this flag means that the
4246 assembler is punting, and is only looking for additional syntax
4247 errors. (Or something like that.)
4249 @item extern segT now_seg;
4250 This variable holds the value of the segment the assembler is
4251 currently assembling into.
4255 @section External functions will you need
4257 You will find the following external functions useful (or
4258 indispensable) when you're writing the machine-dependent part
4263 @item char *frag_more(int bytes)
4264 This function allocates @var{bytes} more bytes in the current
4265 frag (or starts a new frag, if it can't expand the current frag
4266 any more.) for you to store some object-file bytes in. It
4267 returns a pointer to the bytes, ready for you to store data in.
4269 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
4270 This function stores a relocation fixup to be acted on later.
4271 @var{frag} points to the frag the relocation belongs in;
4272 @var{where} is the location within the frag where the relocation begins;
4273 @var{size} is the size of the relocation, and is usually 1 (a single byte),
4274 2 (sixteen bits), or 4 (a longword).
4275 The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
4276 at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the
4277 location is subtracted from the result. A relocation entry is also added
4278 to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
4279 @var{offset} may be NULL.@refill
4281 @item char *frag_var(relax_stateT type, int max_chars, int var,
4282 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
4283 This function creates a machine-dependent frag of type @var{type}
4284 (usually @code{rs_machine_dependent}).
4285 @var{max_chars} is the maximum size in bytes that the frag may grow by;
4286 @var{var} is the current size of the variable end of the frag;
4287 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
4288 @var{md_relax_table[]} during @code{relaxation}.
4289 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
4290 @var{opcode} points into a byte whose value may have to be modified if the
4291 addressing mode used by this frag changes. It typically points into the
4292 @var{fr_literal[]} of the previous frag, and is used to point to a location
4293 that @code{md_convert_frag()}, may have to change.@refill
4295 @item void frag_wane(fragS *fragPTR)
4296 This function is useful from within @code{md_convert_frag}. It
4297 changes a frag to type rs_fill, and sets the variable-sized
4298 piece of the frag to zero. The frag will never change in size
4301 @item segT expression(expressionS *retval)
4302 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
4303 This function parses the string pointed to by the external char
4304 pointer @var{input_line_pointer}, and returns the segment-type
4305 of the expression. It also stores the results in the
4306 @var{expressionS} pointed to by @var{retval}.
4307 @var{input_line_pointer} is advanced to point past the end of
4308 the expression. (@var{input_line_pointer} is used by other
4309 parts of the assembler. If you modify it, be sure to restore
4310 it to its original value.)
4312 @item as_warn(char *message,@dots{})
4313 If warning messages are disabled, this function does nothing.
4314 Otherwise, it prints out the current file name, and the current
4315 line number, then uses @code{fprintf} to print the
4316 @var{message} and any arguments it was passed.
4318 @item as_bad(char *message,@dots{})
4319 This function should be called when @code{_AS__} encounters
4320 conditions that are bad enough that @code{_AS__} should not
4321 produce an object file, but should continue reading input and
4322 printing warning and bad error messages.
4324 @item as_fatal(char *message,@dots{})
4325 This function prints out the current file name and line number,
4326 prints the word @samp{FATAL:}, then uses @code{fprintf} to
4327 print the @var{message} and any arguments it was passed. Then
4328 the assembler exits. This function should only be used for
4329 serious, unrecoverable errors.
4331 @item void float_const(int float_type)
4332 This function reads floating-point constants from the current
4333 input line, and calls @code{md_atof} to assemble them. It is
4334 useful as the function to call for the directives
4335 @samp{.single}, @samp{.double}, @samp{.float}, etc.
4336 @var{float_type} must be a character from @var{FLT_CHARS}.
4338 @item void demand_empty_rest_of_line(void);
4339 This function can be used by machine-dependent directives to
4340 make sure the rest of the input line is empty. It prints a
4341 warning message if there are additional characters on the line.
4343 @item long int get_absolute_expression(void)
4344 This function can be used by machine-dependent directives to
4345 read an absolute number from the current input line. It
4346 returns the result. If it isn't given an absolute expression,
4347 it prints a warning message and returns zero.
4352 @section The concept of Frags
4354 This assembler works to optimize the size of certain addressing
4355 modes. (e.g. branch instructions) This means the size of many
4356 pieces of object code cannot be determined until after assembly
4357 is finished. (This means that the addresses of symbols cannot be
4358 determined until assembly is finished.) In order to do this,
4359 @code{_AS__} stores the output bytes as @dfn{frags}.
4361 Here is the definition of a frag (from @file{as.h})
4367 relax_stateT fr_type;
4368 relax_substateT fr_substate;
4369 unsigned long fr_address;
4371 struct symbol *fr_symbol;
4373 struct frag *fr_next;
4380 is the size of the fixed-size piece of the frag.
4383 is the maximum (?) size of the variable-sized piece of the frag.
4386 is the type of the frag.
4391 rs_machine_dependent
4394 This stores the type of machine-dependent frag this is. (what
4395 kind of addressing mode is being used, and what size is being
4399 @var{fr_address} is only valid after relaxation is finished.
4400 Before relaxation, the only way to store an address is (pointer
4401 to frag containing the address) plus (offset into the frag).
4404 This contains a number, whose meaning depends on the type of
4406 for machine_dependent frags, this contains the offset from
4407 fr_symbol that the frag wants to go to. Thus, for branch
4408 instructions it is usually zero. (unless the instruction was
4409 @samp{jba foo+12} or something like that.)
4412 for machine_dependent frags, this points to the symbol the frag
4416 This points to the location in the frag (or in a previous frag)
4417 of the opcode for the instruction that caused this to be a frag.
4418 @var{fr_opcode} is needed if the actual opcode must be changed
4419 in order to use a different form of the addressing mode.
4420 (For example, if a conditional branch only comes in size tiny,
4421 a large-size branch could be implemented by reversing the sense
4422 of the test, and turning it into a tiny branch over a large jump.
4423 This would require changing the opcode.)
4425 @var{fr_literal} is a variable-size array that contains the
4426 actual object bytes. A frag consists of a fixed size piece of
4427 object data, (which may be zero bytes long), followed by a
4428 piece of object data whose size may not have been determined
4429 yet. Other information includes the type of the frag (which
4430 controls how it is relaxed),
4433 This is the next frag in the singly-linked list. This is
4434 usually only needed by the machine-independent part of
4440 @node License, , Retargeting, Top
4441 @unnumbered GNU GENERAL PUBLIC LICENSE
4442 @center Version 1, February 1989
4445 Copyright @copyright{} 1989 Free Software Foundation, Inc.
4446 675 Mass Ave, Cambridge, MA 02139, USA
4448 Everyone is permitted to copy and distribute verbatim copies
4449 of this license document, but changing it is not allowed.
4452 @unnumberedsec Preamble
4454 The license agreements of most software companies try to keep users
4455 at the mercy of those companies. By contrast, our General Public
4456 License is intended to guarantee your freedom to share and change free
4457 software---to make sure the software is free for all its users. The
4458 General Public License applies to the Free Software Foundation's
4459 software and to any other program whose authors commit to using it.
4460 You can use it for your programs, too.
4462 When we speak of free software, we are referring to freedom, not
4463 price. Specifically, the General Public License is designed to make
4464 sure that you have the freedom to give away or sell copies of free
4465 software, that you receive source code or can get it if you want it,
4466 that you can change the software or use pieces of it in new free
4467 programs; and that you know you can do these things.
4469 To protect your rights, we need to make restrictions that forbid
4470 anyone to deny you these rights or to ask you to surrender the rights.
4471 These restrictions translate to certain responsibilities for you if you
4472 distribute copies of the software, or if you modify it.
4474 For example, if you distribute copies of a such a program, whether
4475 gratis or for a fee, you must give the recipients all the rights that
4476 you have. You must make sure that they, too, receive or can get the
4477 source code. And you must tell them their rights.
4479 We protect your rights with two steps: (1) copyright the software, and
4480 (2) offer you this license which gives you legal permission to copy,
4481 distribute and/or modify the software.
4483 Also, for each author's protection and ours, we want to make certain
4484 that everyone understands that there is no warranty for this free
4485 software. If the software is modified by someone else and passed on, we
4486 want its recipients to know that what they have is not the original, so
4487 that any problems introduced by others will not reflect on the original
4488 authors' reputations.
4490 The precise terms and conditions for copying, distribution and
4491 modification follow.
4494 @unnumberedsec TERMS AND CONDITIONS
4497 @center TERMS AND CONDITIONS
4502 This License Agreement applies to any program or other work which
4503 contains a notice placed by the copyright holder saying it may be
4504 distributed under the terms of this General Public License. The
4505 ``Program'', below, refers to any such program or work, and a ``work based
4506 on the Program'' means either the Program or any work containing the
4507 Program or a portion of it, either verbatim or with modifications. Each
4508 licensee is addressed as ``you''.
4511 You may copy and distribute verbatim copies of the Program's source
4512 code as you receive it, in any medium, provided that you conspicuously and
4513 appropriately publish on each copy an appropriate copyright notice and
4514 disclaimer of warranty; keep intact all the notices that refer to this
4515 General Public License and to the absence of any warranty; and give any
4516 other recipients of the Program a copy of this General Public License
4517 along with the Program. You may charge a fee for the physical act of
4518 transferring a copy.
4521 You may modify your copy or copies of the Program or any portion of
4522 it, and copy and distribute such modifications under the terms of Paragraph
4523 1 above, provided that you also do the following:
4527 cause the modified files to carry prominent notices stating that
4528 you changed the files and the date of any change; and
4531 cause the whole of any work that you distribute or publish, that
4532 in whole or in part contains the Program or any part thereof, either
4533 with or without modifications, to be licensed at no charge to all
4534 third parties under the terms of this General Public License (except
4535 that you may choose to grant warranty protection to some or all
4536 third parties, at your option).
4539 If the modified program normally reads commands interactively when
4540 run, you must cause it, when started running for such interactive use
4541 in the simplest and most usual way, to print or display an
4542 announcement including an appropriate copyright notice and a notice
4543 that there is no warranty (or else, saying that you provide a
4544 warranty) and that users may redistribute the program under these
4545 conditions, and telling the user how to view a copy of this General
4549 You may charge a fee for the physical act of transferring a
4550 copy, and you may at your option offer warranty protection in
4554 Mere aggregation of another independent work with the Program (or its
4555 derivative) on a volume of a storage or distribution medium does not bring
4556 the other work under the scope of these terms.
4559 You may copy and distribute the Program (or a portion or derivative of
4560 it, under Paragraph 2) in object code or executable form under the terms of
4561 Paragraphs 1 and 2 above provided that you also do one of the following:
4565 accompany it with the complete corresponding machine-readable
4566 source code, which must be distributed under the terms of
4567 Paragraphs 1 and 2 above; or,
4570 accompany it with a written offer, valid for at least three
4571 years, to give any third party free (except for a nominal charge
4572 for the cost of distribution) a complete machine-readable copy of the
4573 corresponding source code, to be distributed under the terms of
4574 Paragraphs 1 and 2 above; or,
4577 accompany it with the information you received as to where the
4578 corresponding source code may be obtained. (This alternative is
4579 allowed only for noncommercial distribution and only if you
4580 received the program in object code or executable form alone.)
4583 Source code for a work means the preferred form of the work for making
4584 modifications to it. For an executable file, complete source code means
4585 all the source code for all modules it contains; but, as a special
4586 exception, it need not include source code for modules which are standard
4587 libraries that accompany the operating system on which the executable
4588 file runs, or for standard header files or definitions files that
4589 accompany that operating system.
4592 You may not copy, modify, sublicense, distribute or transfer the
4593 Program except as expressly provided under this General Public License.
4594 Any attempt otherwise to copy, modify, sublicense, distribute or transfer
4595 the Program is void, and will automatically terminate your rights to use
4596 the Program under this License. However, parties who have received
4597 copies, or rights to use copies, from you under this General Public
4598 License will not have their licenses terminated so long as such parties
4599 remain in full compliance.
4602 By copying, distributing or modifying the Program (or any work based
4603 on the Program) you indicate your acceptance of this license to do so,
4604 and all its terms and conditions.
4607 Each time you redistribute the Program (or any work based on the
4608 Program), the recipient automatically receives a license from the original
4609 licensor to copy, distribute or modify the Program subject to these
4610 terms and conditions. You may not impose any further restrictions on the
4611 recipients' exercise of the rights granted herein.
4614 The Free Software Foundation may publish revised and/or new versions
4615 of the General Public License from time to time. Such new versions will
4616 be similar in spirit to the present version, but may differ in detail to
4617 address new problems or concerns.
4619 Each version is given a distinguishing version number. If the Program
4620 specifies a version number of the license which applies to it and ``any
4621 later version'', you have the option of following the terms and conditions
4622 either of that version or of any later version published by the Free
4623 Software Foundation. If the Program does not specify a version number of
4624 the license, you may choose any version ever published by the Free Software
4628 If you wish to incorporate parts of the Program into other free
4629 programs whose distribution conditions are different, write to the author
4630 to ask for permission. For software which is copyrighted by the Free
4631 Software Foundation, write to the Free Software Foundation; we sometimes
4632 make exceptions for this. Our decision will be guided by the two goals
4633 of preserving the free status of all derivatives of our free software and
4634 of promoting the sharing and reuse of software generally.
4637 @heading NO WARRANTY
4644 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4645 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4646 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4647 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
4648 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4649 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
4650 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
4651 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
4652 REPAIR OR CORRECTION.
4655 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
4656 ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4657 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4658 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
4659 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
4660 LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
4661 SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
4662 WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
4663 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
4667 @heading END OF TERMS AND CONDITIONS
4670 @center END OF TERMS AND CONDITIONS
4674 @unnumberedsec Applying These Terms to Your New Programs
4676 If you develop a new program, and you want it to be of the greatest
4677 possible use to humanity, the best way to achieve this is to make it
4678 free software which everyone can redistribute and change under these
4681 To do so, attach the following notices to the program. It is safest to
4682 attach them to the start of each source file to most effectively convey
4683 the exclusion of warranty; and each file should have at least the
4684 ``copyright'' line and a pointer to where the full notice is found.
4687 @var{one line to give the program's name and a brief idea of what it does.}
4688 Copyright (C) 19@var{yy} @var{name of author}
4690 This program is free software; you can redistribute it and/or modify
4691 it under the terms of the GNU General Public License as published by
4692 the Free Software Foundation; either version 1, or (at your option)
4695 This program is distributed in the hope that it will be useful,
4696 but WITHOUT ANY WARRANTY; without even the implied warranty of
4697 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4698 GNU General Public License for more details.
4700 You should have received a copy of the GNU General Public License
4701 along with this program; if not, write to the Free Software
4702 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
4705 Also add information on how to contact you by electronic and paper mail.
4707 If the program is interactive, make it output a short notice like this
4708 when it starts in an interactive mode:
4711 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
4712 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
4713 This is free software, and you are welcome to redistribute it
4714 under certain conditions; type `show c' for details.
4717 The hypothetical commands `show w' and `show c' should show the
4718 appropriate parts of the General Public License. Of course, the
4719 commands you use may be called something other than `show w' and `show
4720 c'; they could even be mouse-clicks or menu items---whatever suits your
4723 You should also get your employer (if you work as a programmer) or your
4724 school, if any, to sign a ``copyright disclaimer'' for the program, if
4725 necessary. Here is a sample; alter the names:
4728 Yoyodyne, Inc., hereby disclaims all copyright interest in the
4729 program `Gnomovision' (a program to direct compilers to make passes
4730 at assemblers) written by James Hacker.
4732 @var{signature of Ty Coon}, 1 April 1989
4733 Ty Coon, President of Vice
4736 That's all there is to it!