2 _dnl__ Copyright (c) 1991 1992 Free Software Foundation, Inc.
4 \input texinfo @c -*-Texinfo-*-
5 @c Copyright (c) 1991 1992 Free Software Foundation, Inc.
7 @setfilename _AS__.info
12 @settitle Using _AS__ (_HOST__)
14 @setchapternewpage odd
22 * As: (as). The GNU assembler.
32 NOTE: this manual is marked up for preprocessing with a collection
33 of m4 macros called "pretex.m4".
35 THIS IS THE FULL SOURCE. The full source needs to be run through m4
36 before either tex- or info- formatting: for example,
37 m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
38 will produce (assuming your path finds either GNU or SysV m4; Berkeley
39 won't do) a file, configured for the M680x0 version of GAS, suitable for
40 formatting. See the text in "pretex.m4" for a fuller explanation (and
41 the macro definitions).
46 This file documents the GNU Assembler "_AS__".
48 Copyright (C) 1991, 1992 Free Software Foundation, Inc.
50 Permission is granted to make and distribute verbatim copies of
51 this manual provided the copyright notice and this permission notice
52 are preserved on all copies.
55 Permission is granted to process this file through Tex and print the
56 results, provided the printed document carries copying permission
57 notice identical to this one except for the removal of this paragraph
58 (this paragraph not being relevant to the printed manual).
61 Permission is granted to copy and distribute modified versions of this
62 manual under the conditions for verbatim copying, provided also that the
63 section entitled ``GNU General Public License'' is included exactly as
64 in the original, and provided that the entire resulting derived work is
65 distributed under the terms of a permission notice identical to this
68 Permission is granted to copy and distribute translations of this manual
69 into another language, under the above conditions for modified versions,
70 except that the section entitled ``GNU General Public License'' may be
71 included in a translation approved by the Free Software Foundation
72 instead of in the original English.
77 @subtitle The GNU Assembler
79 @subtitle for the _HOST__ family
82 @subtitle November 1992
85 The Free Software Foundation Inc. thanks The Nice Computer
86 Company of Australia for loaning Dean Elsner to write the
87 first (Vax) version of @code{as} for Project GNU.
88 The proprietors, management and staff of TNCCA thank FSF for
89 distracting the boss while they got some work
92 @author Dean Elsner, Jay Fenlason & friends
93 @c edited by: pesch@cygnus.com
96 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
97 \xdef\manvers{\$Revision$} % For use in headers, footers too
99 \hfill {\it Using {\tt _AS__}} \manvers\par
100 \hfill \TeX{}info \texinfoversion\par
101 \hfill Edited by Roland Pesch for Cygnus Support\par
103 %"boxit" macro for figures:
104 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
105 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
106 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
107 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
108 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
111 @vskip 0pt plus 1filll
112 Copyright @copyright{} 1991, 1992 Free Software Foundation, Inc.
114 Permission is granted to make and distribute verbatim copies of
115 this manual provided the copyright notice and this permission notice
116 are preserved on all copies.
118 Permission is granted to copy and distribute modified versions of this
119 manual under the conditions for verbatim copying, provided also that the
120 section entitled ``GNU General Public License'' is included exactly as
121 in the original, and provided that the entire resulting derived work is
122 distributed under the terms of a permission notice identical to this
125 Permission is granted to copy and distribute translations of this manual
126 into another language, under the above conditions for modified versions,
127 except that the section entitled ``GNU General Public License'' may be
128 included in a translation approved by the Free Software Foundation
129 instead of in the original English.
136 This file is a user guide to the GNU assembler @code{_AS__}.
138 This version of the file describes @code{_AS__} configured to generate
139 code for _HOST__ architectures.
142 * Overview:: Overview
143 * Invoking:: Command-Line Options
145 * Sections:: Sections and Relocation
147 * Expressions:: Expressions
148 * Pseudo Ops:: Assembler Directives
149 * _MACH_DEP__:: Machine Dependent Features
150 * Copying:: GNU GENERAL PUBLIC LICENSE
158 This manual is a user guide to the GNU assembler @code{_AS__}.
160 This version of the manual describes @code{_AS__} configured to generate
161 code for _HOST__ architectures.
165 @cindex invocation summary
166 @cindex option summary
167 @cindex summary of options
168 Here is a brief summary of how to invoke @code{_AS__}. For details,
169 @pxref{Invoking,,Comand-Line Options}.
171 @c We don't use deffn and friends for the following because they seem
172 @c to be limited to one line for the header.
174 _AS__ [ -a | -al | -as ] [ -D ] [ -f ]
175 [ -I @var{path} ] [ -K ] [ -L ]
176 [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ]
178 @c am29k has no machine-dependent assembler options
181 @c h8/300 has no machine-dependent assembler options
184 @c Z8000 has no machine-dependent assembler options
187 @c see md_parse_option in i960.c
188 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
192 [ -l ] [ -mc68000 | -mc68010 | -mc68020 ]
194 [ -- | @var{files} @dots{} ]
199 Turn on assembly listings; @samp{-al}, listing only, @samp{-as}, symbols
200 only, @samp{-a}, everything.
203 This option is accepted only for script compatibility with calls to
204 other assemblers; it has no effect on @code{_AS__}.
207 ``fast''---skip preprocessing (assume source is compiler output)
210 Add @var{path} to the search list for @code{.include} directives
213 _if__((!_GENERIC__) && !_DIFFTABKLUG__)
214 This option is accepted but has no effect on the _HOST__ family.
215 _fi__((!_GENERIC__) && !_DIFFTABKLUG__)
216 _if__(_GENERIC__ || _DIFFTABKLUG__)
217 Issue warnings when difference tables altered for long displacements.
218 _fi__(_GENERIC__ || _DIFFTABKLUG__)
221 Keep (in symbol table) local symbols, starting with @samp{L}
223 @item -o @var{objfile}
224 Name the object-file output from @code{_AS__}
227 Fold data section into text section
230 Announce @code{as} version
233 Suppress warning messages
236 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
238 (When configured for Intel 960).
240 Specify which variant of the 960 architecture is the target.
244 (When configured for Intel 960).
246 Add code to collect statistics about branches taken.
250 (When configured for Intel 960).
252 Do not alter compare-and-branch instructions for long displacements;
259 (When configured for Motorola 68000).
261 Shorten references to undefined symbols, to one word instead of two
263 @item -mc68000 | -mc68010 | -mc68020
265 (When configured for Motorola 68000).
267 Specify what processor in the 68000 family is the target (default 68020)
270 @item -- | @var{files} @dots{}
271 Standard input, or source files to assemble
275 * Manual:: Structure of this Manual
276 * GNU Assembler:: _AS__, the GNU Assembler
277 * Object Formats:: Object File Formats
278 * Command Line:: Command Line
279 * Input Files:: Input Files
280 * Object:: Output (Object) File
281 * Errors:: Error and Warning Messages
285 @section Structure of this Manual
287 @cindex manual, structure and purpose
288 This manual is intended to describe what you need to know to use
289 @sc{gnu} @code{_AS__}. We cover the syntax expected in source files, including
290 notation for symbols, constants, and expressions; the directives that
291 @code{_AS__} understands; and of course how to invoke @code{_AS__}.
294 We also cover special features in the _HOST__
295 configuration of @code{_AS__}, including assembler directives.
298 This manual also describes some of the machine-dependent features of
299 various flavors of the assembler.
302 This manual also describes how the assembler works internally, and
303 provides some information that may be useful to people attempting to
304 port the assembler to another machine.
308 @cindex machine instructions (not covered)
309 On the other hand, this manual is @emph{not} intended as an introduction
310 to programming in assembly language---let alone programming in general!
311 In a similar vein, we make no attempt to introduce the machine
312 architecture; we do @emph{not} describe the instruction set, standard
313 mnemonics, registers or addressing modes that are standard to a
314 particular architecture.
316 You may want to consult the manufacturer's
317 machine architecture manual for this information.
319 _if__(_H8__&&!_GENERIC__)
320 For information on the H8/300 machine instruction set, see @cite{H8/300
321 Series Programming Manual} (Hitachi ADE--602--025).
322 _fi__(_H8__&&!_GENERIC__)
323 _if__(_Z8000__&&!_GENERIC__)
324 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
325 _fi__(_Z8000__&&!_GENERIC__)
328 @c I think this is premature---pesch@cygnus.com, 17jan1991
330 Throughout this manual, we assume that you are running @dfn{GNU},
331 the portable operating system from the @dfn{Free Software
332 Foundation, Inc.}. This restricts our attention to certain kinds of
333 computer (in particular, the kinds of computers that GNU can run on);
334 once this assumption is granted examples and definitions need less
337 @code{_AS__} is part of a team of programs that turn a high-level
338 human-readable series of instructions into a low-level
339 computer-readable series of instructions. Different versions of
340 @code{_AS__} are used for different kinds of computer.
343 @c There used to be a section "Terminology" here, which defined
344 @c "contents", "byte", "word", and "long". Defining "word" to any
345 @c particular size is confusing when the .word directive may generate 16
346 @c bits on one machine and 32 bits on another; in general, for the user
347 @c version of this manual, none of these terms seem essential to define.
348 @c They were used very little even in the former draft of the manual;
349 @c this draft makes an effort to avoid them (except in names of
353 @section _AS__, the GNU Assembler
355 GNU @code{as} is really a family of assemblers.
357 This manual describes @code{_AS__}, a member of that family which is
358 configured for the _HOST__ architectures.
360 If you use (or have used) the GNU assembler on one architecture, you
361 should find a fairly similar environment when you use it on another
362 architecture. Each version has much in common with the others,
363 including object file formats, most assembler directives (often called
364 @dfn{pseudo-ops)} and assembler syntax.@refill
366 _if__(_GENERIC__||!_H8__)
367 @cindex purpose of @sc{gnu} @code{_AS__}
368 @code{_AS__} is primarily intended to assemble the output of the GNU C
369 compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless,
370 we've tried to make @code{_AS__} assemble correctly everything that the native
372 _fi__(_GENERIC__||!_H8__)
374 Any exceptions are documented explicitly (@pxref{_MACH_DEP__}).
376 _if__(_GENERIC__||_M680X0__)
377 This doesn't mean @code{_AS__} always uses the same syntax as another
378 assembler for the same architecture; for example, we know of several
379 incompatible versions of 680x0 assembly language syntax.
380 _fi__(_GENERIC__||_M680X0__)
382 Unlike older assemblers, @code{_AS__} is designed to assemble a source
383 program in one pass of the source file. This has a subtle impact on the
384 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
387 @section Object File Formats
389 @cindex object file format
390 The GNU assembler can be configured to produce several alternative
391 object file formats. For the most part, this does not affect how you
392 write assembly language programs; but directives for debugging symbols
393 are typically different in different file formats. @xref{Symbol
394 Attributes,,Symbol Attributes}.
396 _if__(!(_I960__||_A29K__))
397 _if__(_AOUT__ && (!_COFF__) && (!_ELF__))
398 On the _HOST__, @code{_AS__} is configured to produce @code{a.out} format object
400 _fi__(_AOUT__ && (!_COFF__) && (!_ELF__))
401 _if__((!_AOUT__) && _COFF__ && (!_ELF__))
402 On the _HOST__, @code{_AS__} is configured to produce COFF format object
404 _fi__((!_AOUT__) && _COFF__ && (!_ELF__))
405 _fi__(!(_I960__||_A29K__))
407 On the _HOST__, @code{_AS__} can be configured to produce either
408 @code{a.out} or COFF format object files.
411 On the _HOST__, @code{_AS__} can be configured to produce either @code{b.out} or COFF
417 @section Command Line
419 @cindex command line conventions
420 After the program name @code{_AS__}, the command line may contain
421 options and file names. Options may appear in any order, and may be
422 before, after, or between file names. The order of file names is
425 @cindex standard input, as input file
427 @file{--} (two hyphens) by itself names the standard input file
428 explicitly, as one of the files for @code{_AS__} to assemble.
430 @cindex options, command line
431 Except for @samp{--} any command line argument that begins with a
432 hyphen (@samp{-}) is an option. Each option changes the behavior of
433 @code{_AS__}. No option changes the way another option works. An
434 option is a @samp{-} followed by one or more letters; the case of
435 the letter is important. All options are optional.
437 Some options expect exactly one file name to follow them. The file
438 name may either immediately follow the option's letter (compatible
439 with older assemblers) or it may be the next command argument (GNU
440 standard). These two command lines are equivalent:
443 _AS__ -o my-object-file.o mumble.s
444 _AS__ -omy-object-file.o mumble.s
451 @cindex source program
453 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
454 describe the program input to one run of @code{_AS__}. The program may
455 be in one or more files; how the source is partitioned into files
456 doesn't change the meaning of the source.
458 @c I added "con" prefix to "catenation" just to prove I can overcome my
459 @c APL training... pesch@cygnus.com
460 The source program is a concatenation of the text in all the files, in the
463 Each time you run @code{_AS__} it assembles exactly one source
464 program. The source program is made up of one or more files.
465 (The standard input is also a file.)
467 You give @code{_AS__} a command line that has zero or more input file
468 names. The input files are read (from left file name to right). A
469 command line argument (in any position) that has no special meaning
470 is taken to be an input file name.
472 If you give @code{_AS__} no file names it attempts to read one input file
473 from the @code{_AS__} standard input, which is normally your terminal. You
474 may have to type @key{ctl-D} to tell @code{_AS__} there is no more program
477 Use @samp{--} if you need to explicitly name the standard input file
478 in your command line.
480 If the source is empty, @code{_AS__} will produce a small, empty object
483 @subheading Filenames and Line-numbers
485 @cindex input file linenumbers
486 @cindex line numbers, in input files
487 There are two ways of locating a line in the input file (or files) and
488 either may be used in reporting error messages. One way refers to a line
489 number in a physical file; the other refers to a line number in a
490 ``logical'' file. @xref{Errors, ,Error and Warning Messages}.
492 @dfn{Physical files} are those files named in the command line given
495 @dfn{Logical files} are simply names declared explicitly by assembler
496 directives; they bear no relation to physical files. Logical file names
497 help error messages reflect the original source file, when @code{_AS__}
498 source is itself synthesized from other files.
499 @xref{App-File,,@code{.app-file}}.
502 @section Output (Object) File
508 Every time you run @code{_AS__} it produces an output file, which is
509 your assembly language program translated into numbers. This file
510 is the object file, named @code{a.out} unless you tell @code{_AS__} to
511 give it another name by using the @code{-o} option. Conventionally,
512 object file names end with @file{.o}. The default name of
513 @file{a.out} is used for historical reasons: older assemblers were
514 capable of assembling self-contained programs directly into a
516 @c This may still work, but hasn't been tested.
520 The object file is meant for input to the linker @code{_LD__}. It contains
521 assembled program code, information to help @code{_LD__} integrate
522 the assembled program into a runnable file, and (optionally) symbolic
523 information for the debugger.
525 @c link above to some info file(s) like the description of a.out.
526 @c don't forget to describe GNU info as well as Unix lossage.
529 @section Error and Warning Messages
531 @cindex error messsages
532 @cindex warning messages
533 @cindex messages from @code{_AS__}
534 @code{_AS__} may write warnings and error messages to the standard error
535 file (usually your terminal). This should not happen when a compiler
536 runs @code{_AS__} automatically. Warnings report an assumption made so
537 that @code{_AS__} could keep assembling a flawed program; errors report a
538 grave problem that stops the assembly.
540 @cindex format of warning messages
541 Warning messages have the format
544 file_name:@b{NNN}:Warning Message Text
548 @cindex line numbers, in warnings/errors
549 (where @b{NNN} is a line number). If a logical file name has
550 been given (@pxref{App-File,,@code{.app-file}}) it is used for the filename, otherwise the
551 name of the current input file is used. If a logical line number was
554 (@pxref{Line,,@code{.line}})
557 (@pxref{Ln,,@code{.ln}})
559 then it is used to calculate the number printed,
560 otherwise the actual line in the current source file is printed. The
561 message text is intended to be self explanatory (in the grand Unix
564 @cindex format of error messages
565 Error messages have the format
567 file_name:@b{NNN}:FATAL:Error Message Text
569 The file name and line number are derived as for warning
570 messages. The actual message text may be rather less explanatory
571 because many of them aren't supposed to happen.
574 @chapter Command-Line Options
576 @cindex options, all versions of @code{_AS__}
577 This chapter describes command-line options available in @emph{all}
578 versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific
583 to particular machine architectures.
586 @section Enable Listings: @code{-a}, @code{-al}, @code{-as}
591 @cindex listings, enabling
592 @cindex assembly listings, enabling
593 These options enable listing output from the assembler. @samp{-a} by
594 itself requests all listing output; @samp{-al} requests only the
595 output-program listing, and @samp{-as} requests only a symbol table
598 Once you have specified one of these options, you can further control
599 listing output and its appearance using the directives @code{.list},
600 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
603 If you do not request listing output with one of the @samp{-a} options, the
604 listing-control directives have no effect.
609 This option has no effect whatsoever, but it is accepted to make it more
610 likely that scripts written for other assemblers will also work with
613 @section Work Faster: @code{-f}
616 @cindex trusted compiler
617 @cindex faster processing (@code{-f})
618 @samp{-f} should only be used when assembling programs written by a
619 (trusted) compiler. @samp{-f} stops the assembler from pre-processing
620 the input file(s) before assembling them. @xref{Pre-processing,
624 @emph{Warning:} if the files actually need to be pre-processed (if they
625 contain comments, for example), @code{_AS__} will not work correctly if
629 @section @code{.include} search path: @code{-I} @var{path}
631 @kindex -I @var{path}
632 @cindex paths for @code{.include}
633 @cindex search path for @code{.include}
634 @cindex @code{include} directive search path
635 Use this option to add a @var{path} to the list of directories
636 @code{_AS__} will search for files specified in @code{.include}
637 directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as
638 many times as necessary to include a variety of paths. The current
639 working directory is always searched first; after that, @code{_AS__}
640 searches any @samp{-I} directories in the same order as they were
641 specified (left to right) on the command line.
643 @section Difference Tables: @code{-K}
646 _if__((!_GENERIC__) && (!_DIFFTABKLUG__))
647 On the _HOST__ family, this option is allowed, but has no effect. It is
648 permitted for compatibility with the GNU assembler on other platforms,
649 where it can be used to warn when the assembler alters the machine code
650 generated for @samp{.word} directives in difference tables. The _HOST__
651 family does not have the addressing limitations that sometimes lead to this
652 alteration on other platforms.
653 _fi__((!_GENERIC__) && (!_DIFFTABKLUG__))
655 _if__(_GENERIC__ || _DIFFTABKLUG__ )
656 @cindex difference tables, warning
657 @cindex warning for altered difference tables
658 @code{_AS__} sometimes alters the code emitted for directives of the form
659 @samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
660 You can use the @samp{-K} option if you want a warning issued when this
662 _fi__(_GENERIC__ || _DIFFTABKLUG__ )
664 @section Include Local Labels: @code{-L}
667 @cindex local labels, retaining in output
668 Labels beginning with @samp{L} (upper case only) are called @dfn{local
669 labels}. @xref{Symbol Names}. Normally you don't see such labels when
670 debugging, because they are intended for the use of programs (like
671 compilers) that compose assembler programs, not for your notice.
672 Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't
673 normally debug with them.
675 This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols
676 in the object file. Usually if you do this you also tell the linker
677 @code{_LD__} to preserve symbols whose names begin with @samp{L}.
679 @section Name the Object File: @code{-o}
682 @cindex naming object file
683 @cindex object file name
684 There is always one object file output when you run @code{_AS__}. By
685 default it has the name @file{a.out}. You use this option (which
686 takes exactly one filename) to give the object file a different name.
688 Whatever the object file is called, @code{_AS__} will overwrite any
689 existing file of the same name.
691 @section Join Data and Text Sections: @code{-R}
694 @cindex data and text sections, joining
695 @cindex text and data sections, joining
696 @cindex joining text and data sections
697 @cindex merging text and data sections
698 @code{-R} tells @code{_AS__} to write the object file as if all
699 data-section data lives in the text section. This is only done at
700 the very last moment: your binary data are the same, but data
701 section parts are relocated differently. The data section part of
702 your object file is zero bytes long because all it bytes are
703 appended to the text section. (@xref{Sections,,Sections and Relocation}.)
705 When you specify @code{-R} it would be possible to generate shorter
706 address displacements (because we don't have to cross between text and
707 data section). We refrain from doing this simply for compatibility with
708 older versions of @code{_AS__}. In future, @code{-R} may work this way.
711 When @code{_AS__} is configured for COFF output,
712 this option is only useful if you use sections named @samp{.text} and
716 @section Announce Version: @code{-v}
720 @cindex @code{_AS__} version
721 @cindex version of @code{_AS__}
722 You can find out what version of as is running by including the
723 option @samp{-v} (which you can also spell as @samp{-version}) on the
726 @section Suppress Warnings: @code{-W}
729 @cindex suppressing warnings
730 @cindex warnings, suppressing
731 @code{_AS__} should never give a warning or error message when
732 assembling compiler output. But programs written by people often
733 cause @code{_AS__} to give a warning that a particular assumption was
734 made. All such warnings are directed to the standard error file.
735 If you use this option, no warnings are issued. This option only
736 affects the warning messages: it does not change any particular of how
737 @code{_AS__} assembles your file. Errors, which stop the assembly, are
743 @cindex machine-independent syntax
744 @cindex syntax, machine-independent
745 This chapter describes the machine-independent syntax allowed in a
746 source file. @code{_AS__} syntax is similar to what many other assemblers
747 use; it is inspired in BSD 4.2
752 assembler, except that @code{_AS__} does not assemble Vax bit-fields.
756 * Pre-processing:: Pre-processing
757 * Whitespace:: Whitespace
758 * Comments:: Comments
759 * Symbol Intro:: Symbols
760 * Statements:: Statements
761 * Constants:: Constants
765 @section Pre-Processing
767 @cindex preprocessing
770 @cindex whitespace, removed by preprocessor
772 adjusts and removes extra whitespace. It leaves one space or tab before
773 the keywords on a line, and turns any other whitespace on the line into
776 @cindex comments, removed by preprocessor
778 removes all comments, replacing them with a single space, or an
779 appropriate number of newlines.
781 @cindex constants, converted by preprocessor
783 converts character constants into the appropriate numeric values.
786 Excess whitespace, comments, and character constants
787 cannot be used in the portions of the input text that are not
790 @cindex turning preprocessing on and off
791 @cindex preprocessing, turning on and off
794 If the first line of an input file is @code{#NO_APP} or the @samp{-f}
795 option is given, the input file will not be pre-processed. Within such
796 an input file, parts of the file can be pre-processed by putting a line
797 that says @code{#APP} before the text that should be pre-processed, and
798 putting a line that says @code{#NO_APP} after them. This feature is
799 mainly intend to support @code{asm} statements in compilers whose output
800 normally does not need to be pre-processed.
806 @dfn{Whitespace} is one or more blanks or tabs, in any order.
807 Whitespace is used to separate symbols, and to make programs neater for
808 people to read. Unless within character constants
809 (@pxref{Characters,,Character Constants}), any whitespace means the same
810 as exactly one space.
816 There are two ways of rendering comments to @code{_AS__}. In both
817 cases the comment is equivalent to one space.
819 Anything from @samp{/*} through the next @samp{*/} is a comment.
820 This means you may not nest these comments.
824 The only way to include a newline ('\n') in a comment
825 is to use this sort of comment.
828 /* This sort of comment does not nest. */
831 @cindex line comment character
832 Anything from the @dfn{line comment} character to the next newline
833 is considered a comment and is ignored. The line comment character is
838 @samp{#} on the i960;
841 @samp{|} on the 680x0;
844 @samp{;} for the AMD 29K family;
847 @samp{;} for the _HOST__ family;
850 @samp{!} for the Z8000;
852 see @ref{_MACH_DEP__}. @refill
853 @c FIXME: fill in SPARC line comment char
856 On some machines there are two different line comment characters. One
857 will only begin a comment if it is the first non-whitespace character on
858 a line, while the other will always begin a comment.
862 @cindex lines starting with @code{#}
863 @cindex logical line numbers
864 To be compatible with past assemblers, a special interpretation is
865 given to lines that begin with @samp{#}. Following the @samp{#} an
866 absolute expression (@pxref{Expressions}) is expected: this will be
867 the logical line number of the @b{next} line. Then a string
868 (@xref{Strings}.) is allowed: if present it is a new logical file
869 name. The rest of the line, if any, should be whitespace.
871 If the first non-whitespace characters on the line are not numeric,
872 the line is ignored. (Just like a comment.)
874 # This is an ordinary comment.
875 # 42-6 "new_file_name" # New logical file name
876 # This is logical line # 36.
878 This feature is deprecated, and may disappear from future versions
884 @cindex characters used in symbols
885 A @dfn{symbol} is one or more characters chosen from the set of all
886 letters (both upper and lower case), digits and
888 the three characters @samp{_.$}
891 the two characters @samp{_.}
893 On most machines, you can also use @code{$} in symbol names; exceptions
894 are noted in @ref{_MACH_DEP__}.
897 No symbol may begin with a digit. Case is significant.
898 There is no length limit: all characters are significant. Symbols are
899 delimited by characters not in that set, or by the beginning of a file
900 (since the source program must end with a newline, the end of a file is
901 not a possible symbol delimiter). @xref{Symbols}.
902 @cindex length of symbols
907 @cindex statements, structure of
908 @cindex line separator character
909 @cindex statement separator character
911 _if__(!(_A29K__||_H8__))
912 A @dfn{statement} ends at a newline character (@samp{\n}) or at a
913 semicolon (@samp{;}). The newline or semicolon is considered part of
914 the preceding statement. Newlines and semicolons within character
915 constants are an exception: they don't end statements.
916 _fi__(!(_A29K__||_H8__))
918 A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
919 sign (@samp{@@}). The newline or at sign is considered part of the
920 preceding statement. Newlines and at signs within character constants
921 are an exception: they don't end statements.
924 A @dfn{statement} ends at a newline character (@samp{\n}) or a dollar
925 sign (@samp{$}). The newline or dollar sign is considered part of the
926 preceding statement. Newlines and dollar signs within character constants
927 are an exception: they don't end statements.
931 A @dfn{statement} ends at a newline character (@samp{\n}) or line
932 separator character. (The line separator is usually @samp{;}, unless
933 this conflicts with the comment character; @pxref{_MACH_DEP__}.) The
934 newline or separator character is considered part of the preceding
935 statement. Newlines and separators within character constants are an
936 exception: they don't end statements.
939 @cindex newline, required at file end
940 @cindex EOF, newline must precede
941 It is an error to end any statement with end-of-file: the last
942 character of any input file should be a newline.@refill
944 @cindex continuing statements
945 @cindex multi-line statements
946 @cindex statement on multiple lines
947 You may write a statement on more than one line if you put a
948 backslash (@kbd{\}) immediately in front of any newlines within the
949 statement. When @code{_AS__} reads a backslashed newline both
950 characters are ignored. You can even put backslashed newlines in
951 the middle of symbol names without changing the meaning of your
954 An empty statement is allowed, and may include whitespace. It is ignored.
956 @cindex instructions and directives
957 @cindex directives and instructions
958 @c "key symbol" is not used elsewhere in the document; seems pedantic to
959 @c @defn{} it in that case, as was done previously... pesch@cygnus.com,
961 A statement begins with zero or more labels, optionally followed by a
962 key symbol which determines what kind of statement it is. The key
963 symbol determines the syntax of the rest of the statement. If the
964 symbol begins with a dot @samp{.} then the statement is an assembler
965 directive: typically valid for any computer. If the symbol begins with
966 a letter the statement is an assembly language @dfn{instruction}: it
967 will assemble into a machine language instruction.
969 Different versions of @code{_AS__} for different computers will
970 recognize different instructions. In fact, the same symbol may
971 represent a different instruction in a different computer's assembly
975 @cindex @code{:} (label)
976 @cindex label (@code{:})
977 A label is a symbol immediately followed by a colon (@code{:}).
978 Whitespace before a label or after a colon is permitted, but you may not
979 have whitespace between a label's symbol and its colon. @xref{Labels}.
982 label: .directive followed by something
983 another_label: # This is an empty statement.
984 instruction operand_1, operand_2, @dots{}
991 A constant is a number, written so that its value is known by
992 inspection, without knowing any context. Like this:
994 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
995 .ascii "Ring the bell\7" # A string constant.
996 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
997 .float 0f-314159265358979323846264338327\
998 95028841971.693993751E-40 # - pi, a flonum.
1002 * Characters:: Character Constants
1003 * Numbers:: Number Constants
1007 @subsection Character Constants
1009 @cindex character constants
1010 @cindex constants, character
1011 There are two kinds of character constants. A @dfn{character} stands
1012 for one character in one byte and its value may be used in
1013 numeric expressions. String constants (properly called string
1014 @emph{literals}) are potentially many bytes and their values may not be
1015 used in arithmetic expressions.
1019 * Chars:: Characters
1023 @subsubsection Strings
1025 @cindex string constants
1026 @cindex constants, string
1027 A @dfn{string} is written between double-quotes. It may contain
1028 double-quotes or null characters. The way to get special characters
1029 into a string is to @dfn{escape} these characters: precede them with
1030 a backslash @samp{\} character. For example @samp{\\} represents
1031 one backslash: the first @code{\} is an escape which tells
1032 @code{_AS__} to interpret the second character literally as a backslash
1033 (which prevents @code{_AS__} from recognizing the second @code{\} as an
1034 escape character). The complete list of escapes follows.
1036 @cindex escape codes, character
1037 @cindex character escape codes
1040 @c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
1043 @cindex @code{\b} (backspace character)
1044 @cindex backspace (@code{\b})
1045 Mnemonic for backspace; for ASCII this is octal code 010.
1048 @c Mnemonic for EOText; for ASCII this is octal code 004.
1051 @cindex @code{\f} (formfeed character)
1052 @cindex formfeed (@code{\f})
1053 Mnemonic for FormFeed; for ASCII this is octal code 014.
1056 @cindex @code{\n} (newline character)
1057 @cindex newline (@code{\n})
1058 Mnemonic for newline; for ASCII this is octal code 012.
1061 @c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
1064 @cindex @code{\r} (carriage return character)
1065 @cindex carriage return (@code{\r})
1066 Mnemonic for carriage-Return; for ASCII this is octal code 015.
1069 @c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
1070 @c other assemblers.
1073 @cindex @code{\t} (tab)
1074 @cindex tab (@code{\t})
1075 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
1078 @c Mnemonic for Vertical tab; for ASCII this is octal code 013.
1079 @c @item \x @var{digit} @var{digit} @var{digit}
1080 @c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
1082 @item \ @var{digit} @var{digit} @var{digit}
1083 @cindex @code{\@var{ddd}} (octal character code)
1084 @cindex octal character code (@code{\@var{ddd}})
1085 An octal character code. The numeric code is 3 octal digits.
1086 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
1087 for example, @code{\008} has the value 010, and @code{\009} the value 011.
1090 @cindex @code{\\} (@samp{\} character)
1091 @cindex backslash (@code{\\})
1092 Represents one @samp{\} character.
1095 @c Represents one @samp{'} (accent acute) character.
1096 @c This is needed in single character literals
1097 @c (@xref{Characters,,Character Constants}.) to represent
1101 @cindex @code{\"} (doublequote character)
1102 @cindex doublequote (@code{\"})
1103 Represents one @samp{"} character. Needed in strings to represent
1104 this character, because an unescaped @samp{"} would end the string.
1106 @item \ @var{anything-else}
1107 Any other character when escaped by @kbd{\} will give a warning, but
1108 assemble as if the @samp{\} was not present. The idea is that if
1109 you used an escape sequence you clearly didn't want the literal
1110 interpretation of the following character. However @code{_AS__} has no
1111 other interpretation, so @code{_AS__} knows it is giving you the wrong
1112 code and warns you of the fact.
1115 Which characters are escapable, and what those escapes represent,
1116 varies widely among assemblers. The current set is what we think
1117 the BSD 4.2 assembler recognizes, and is a subset of what most C
1118 compilers recognize. If you are in doubt, don't use an escape
1122 @subsubsection Characters
1124 @cindex single character constant
1125 @cindex character, single
1126 @cindex constant, single character
1127 A single character may be written as a single quote immediately
1128 followed by that character. The same escapes apply to characters as
1129 to strings. So if you want to write the character backslash, you
1130 must write @kbd{'\\} where the first @code{\} escapes the second
1131 @code{\}. As you can see, the quote is an acute accent, not a
1132 grave accent. A newline
1134 _if__(!(_A29K__||_H8__))
1135 (or semicolon @samp{;})
1136 _fi__(!(_A29K__||_H8__))
1138 (or at sign @samp{@@})
1141 (or dollar sign @samp{$})
1144 immediately following an acute accent is taken as a literal character
1145 and does not count as the end of a statement. The value of a character
1146 constant in a numeric expression is the machine's byte-wide code for
1147 that character. @code{_AS__} assumes your character code is ASCII:
1148 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
1151 @subsection Number Constants
1153 @cindex constants, number
1154 @cindex number constants
1155 @code{_AS__} distinguishes three kinds of numbers according to how they
1156 are stored in the target machine. @emph{Integers} are numbers that
1157 would fit into an @code{int} in the C language. @emph{Bignums} are
1158 integers, but they are stored in more than 32 bits. @emph{Flonums}
1159 are floating point numbers, described below.
1162 * Integers:: Integers
1165 _if__(_I960__&&!_GENERIC__)
1166 * Bit Fields:: Bit Fields
1167 _fi__(_I960__&&!_GENERIC__)
1171 @subsubsection Integers
1173 @cindex constants, integer
1175 @cindex binary integers
1176 @cindex integers, binary
1177 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
1178 the binary digits @samp{01}.
1180 @cindex octal integers
1181 @cindex integers, octal
1182 An octal integer is @samp{0} followed by zero or more of the octal
1183 digits (@samp{01234567}).
1185 @cindex decimal integers
1186 @cindex integers, decimal
1187 A decimal integer starts with a non-zero digit followed by zero or
1188 more digits (@samp{0123456789}).
1190 @cindex hexadecimal integers
1191 @cindex integers, hexadecimal
1192 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
1193 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
1195 Integers have the usual values. To denote a negative integer, use
1196 the prefix operator @samp{-} discussed under expressions
1197 (@pxref{Prefix Ops,,Prefix Operators}).
1200 @subsubsection Bignums
1203 @cindex constants, bignum
1204 A @dfn{bignum} has the same syntax and semantics as an integer
1205 except that the number (or its negative) takes more than 32 bits to
1206 represent in binary. The distinction is made because in some places
1207 integers are permitted while bignums are not.
1210 @subsubsection Flonums
1212 @cindex floating point numbers
1213 @cindex constants, floating point
1215 @cindex precision, floating point
1216 A @dfn{flonum} represents a floating point number. The translation is
1217 indirect: a decimal floating point number from the text is converted by
1218 @code{_AS__} to a generic binary floating point number of more than
1219 sufficient precision. This generic floating point number is converted
1220 to a particular computer's floating point format (or formats) by a
1221 portion of @code{_AS__} specialized to that computer.
1223 A flonum is written by writing (in order)
1228 A letter, to tell @code{_AS__} the rest of the number is a flonum.
1230 @kbd{e} is recommended. Case is not important.
1232 @c FIXME: verify if flonum syntax really this vague for most cases
1233 (Any otherwise illegal letter
1234 will work here, but that might be changed. Vax BSD 4.2 assembler seems
1235 to allow any of @samp{defghDEFGH}.)
1238 _if__(_A29K__||_H8__)
1240 On the AMD 29K and H8/300 architectures, the letter must be:
1242 One of the letters @samp{DFPRSX} (in upper or lower case).
1243 _fi__(_A29K__||_H8__)
1246 On the Intel 960 architecture, the letter must be:
1248 One of the letters @samp{DFT} (in upper or lower case).
1251 An optional sign: either @samp{+} or @samp{-}.
1253 An optional @dfn{integer part}: zero or more decimal digits.
1255 An optional @dfn{fractional part}: @samp{.} followed by zero
1256 or more decimal digits.
1258 An optional exponent, consisting of:
1261 An @samp{E} or @samp{e}.
1262 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
1263 @c principle this can perfectly well be different on different targets.
1265 Optional sign: either @samp{+} or @samp{-}.
1267 One or more decimal digits.
1271 At least one of the integer part or the fractional part must be
1272 present. The floating point number has the usual base-10 value.
1274 @code{_AS__} does all processing using integers. Flonums are computed
1275 independently of any floating point hardware in the computer running
1278 _if__(_I960__&&!_GENERIC__)
1279 @c Bit fields are written as a general facility but are also controlled
1280 @c by a conditional-compilation flag---which is as of now (21mar91)
1281 @c turned on only by the i960 config of GAS.
1283 @subsubsection Bit Fields
1286 @cindex constants, bit field
1287 You can also define numeric constants as @dfn{bit fields}.
1288 specify two numbers separated by a colon---
1290 @var{mask}:@var{value}
1293 the first will act as a mask; @code{_AS__} will bitwise-and it with the
1296 The resulting number is then packed
1298 @c this conditional paren in case bit fields turned on elsewhere than 960
1299 (in host-dependent byte order)
1301 into a field whose width depends on which assembler directive has the
1302 bit-field as its argument. Overflow (a result from the bitwise and
1303 requiring more binary digits to represent) is not an error; instead,
1304 more constants are generated, of the specified width, beginning with the
1305 least significant digits.@refill
1307 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
1308 @code{.short}, and @code{.word} accept bit-field arguments.
1309 _fi__(_I960__&&!_GENERIC__)
1312 @chapter Sections and Relocation
1317 * Secs Background:: Background
1318 * _LD__ Sections:: _LD__ Sections
1319 * _AS__ Sections:: _AS__ Internal Sections
1320 * Sub-Sections:: Sub-Sections
1324 @node Secs Background
1327 Roughly, a section is a range of addresses, with no gaps; all data
1328 ``in'' those addresses is treated the same for some particular purpose.
1329 For example there may be a ``read only'' section.
1331 @cindex linker, and assembler
1332 @cindex assembler, and linker
1333 The linker @code{_LD__} reads many object files (partial programs) and
1334 combines their contents to form a runnable program. When @code{_AS__}
1335 emits an object file, the partial program is assumed to start at address
1336 0. @code{_LD__} will assign the final addresses the partial program
1337 occupies, so that different partial programs don't overlap. This is
1338 actually an over-simplification, but it will suffice to explain how
1339 @code{_AS__} uses sections.
1341 @code{_LD__} moves blocks of bytes of your program to their run-time
1342 addresses. These blocks slide to their run-time addresses as rigid
1343 units; their length does not change and neither does the order of bytes
1344 within them. Such a rigid unit is called a @emph{section}. Assigning
1345 run-time addresses to sections is called @dfn{relocation}. It includes
1346 the task of adjusting mentions of object-file addresses so they refer to
1347 the proper run-time addresses.
1349 For the H8/300, @code{_AS__} pads sections if needed to ensure they end
1350 on a word (sixteen bit) boundary.
1353 @cindex standard @code{_AS__} sections
1354 An object file written by @code{_AS__} has at least three sections, any
1355 of which may be empty. These are named @dfn{text}, @dfn{data} and
1360 When it generates COFF output,
1362 @code{_AS__} can also generate whatever other named sections you specify
1363 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
1364 If you don't use any directives that place output in the @samp{.text}
1365 or @samp{.data} sections, these sections will still exist, but will be empty.
1368 Within the object file, the text section starts at address @code{0}, the
1369 data section follows, and the bss section follows the data section.
1371 To let @code{_LD__} know which data will change when the sections are
1372 relocated, and how to change that data, @code{_AS__} also writes to the
1373 object file details of the relocation needed. To perform relocation
1374 @code{_LD__} must know, each time an address in the object
1378 Where in the object file is the beginning of this reference to
1381 How long (in bytes) is this reference?
1383 Which section does the address refer to? What is the numeric value of
1385 (@var{address}) @minus{} (@var{start-address of section})?
1388 Is the reference to an address ``Program-Counter relative''?
1391 @cindex addresses, format of
1392 @cindex section-relative addressing
1393 In fact, every address @code{_AS__} ever uses is expressed as
1395 (@var{section}) + (@var{offset into section})
1398 Further, every expression @code{_AS__} computes is of this section-relative
1399 nature. @dfn{Absolute expression} means an expression with section
1400 ``absolute'' (@pxref{_LD__ Sections}). A @dfn{pass1 expression} means
1401 an expression with section ``pass1'' (@pxref{_AS__ Sections,,_AS__
1402 Internal Sections}). In this manual we use the notation @{@var{secname}
1403 @var{N}@} to mean ``offset @var{N} into section @var{secname}''.
1405 Apart from text, data and bss sections you need to know about the
1406 @dfn{absolute} section. When @code{_LD__} mixes partial programs,
1407 addresses in the absolute section remain unchanged. For example, address
1408 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}.
1409 Although two partial programs' data sections will not overlap addresses
1410 after linking, @emph{by definition} their absolute sections will overlap.
1411 Address @code{@{absolute@ 239@}} in one partial program will always be the same
1412 address when the program is running as address @code{@{absolute@ 239@}} in any
1413 other partial program.
1415 The idea of sections is extended to the @dfn{undefined} section. Any
1416 address whose section is unknown at assembly time is by definition
1417 rendered @{undefined @var{U}@}---where @var{U} will be filled in later.
1418 Since numbers are always defined, the only way to generate an undefined
1419 address is to mention an undefined symbol. A reference to a named
1420 common block would be such a symbol: its value is unknown at assembly
1421 time so it has section @emph{undefined}.
1423 By analogy the word @emph{section} is used to describe groups of sections in
1424 the linked program. @code{_LD__} puts all partial programs' text
1425 sections in contiguous addresses in the linked program. It is
1426 customary to refer to the @emph{text section} of a program, meaning all
1427 the addresses of all partial program's text sections. Likewise for
1428 data and bss sections.
1430 Some sections are manipulated by @code{_LD__}; others are invented for
1431 use of @code{_AS__} and have no meaning except during assembly.
1433 @node _LD__ Sections
1434 @section _LD__ Sections
1435 @code{_LD__} deals with just four kinds of sections, summarized below.
1439 _if__(_GENERIC__||_COFF__)
1440 @cindex named sections
1441 @cindex sections, named
1442 @item named sections
1443 _fi__(_GENERIC__||_COFF__)
1444 _if__(_AOUT__||_BOUT__)
1445 @cindex text section
1446 @cindex data section
1449 _fi__(_AOUT__||_BOUT__)
1450 These sections hold your program. @code{_AS__} and @code{_LD__} treat them as
1451 separate but equal sections. Anything you can say of one section is
1453 _if__(_AOUT__||_BOUT__)
1454 When the program is running, however, it is
1455 customary for the text section to be unalterable. The
1456 text section is often shared among processes: it will contain
1457 instructions, constants and the like. The data section of a running
1458 program is usually alterable: for example, C variables would be stored
1459 in the data section.
1460 _fi__(_AOUT__||_BOUT__)
1464 This section contains zeroed bytes when your program begins running. It
1465 is used to hold unitialized variables or common storage. The length of
1466 each partial program's bss section is important, but because it starts
1467 out containing zeroed bytes there is no need to store explicit zero
1468 bytes in the object file. The bss section was invented to eliminate
1469 those explicit zeros from object files.
1471 @cindex absolute section
1472 @item absolute section
1473 Address 0 of this section is always ``relocated'' to runtime address 0.
1474 This is useful if you want to refer to an address that @code{_LD__} must
1475 not change when relocating. In this sense we speak of absolute
1476 addresses being ``unrelocatable'': they don't change during relocation.
1478 @cindex undefined section
1479 @item undefined section
1480 This ``section'' is a catch-all for address references to objects not in
1481 the preceding sections.
1482 @c FIXME: ref to some other doc on obj-file formats could go here.
1485 @cindex relocation example
1486 An idealized example of three relocatable sections follows.
1488 The example uses the traditional section names @samp{.text} and @samp{.data}.
1490 Memory addresses are on the horizontal axis.
1494 @c END TEXI2ROFF-KILL
1497 partial program # 1: |ttttt|dddd|00|
1504 partial program # 2: |TTT|DDD|000|
1507 +--+---+-----+--+----+---+-----+~~
1508 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1509 +--+---+-----+--+----+---+-----+~~
1511 addresses: 0 @dots{}
1515 @c FIXME make sure no page breaks inside figure!!
1518 \line{\it Partial program \#1: \hfil}
1519 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1520 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
1522 \line{\it Partial program \#2: \hfil}
1523 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
1524 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
1526 \line{\it linked program: \hfil}
1527 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
1528 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
1529 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
1530 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
1532 \line{\it addresses: \hfil}
1536 @c END TEXI2ROFF-KILL
1538 @node _AS__ Sections
1539 @section _AS__ Internal Sections
1541 @cindex internal @code{_AS__} sections
1542 @cindex sections in messages, internal
1543 These sections are meant only for the internal use of @code{_AS__}. They
1544 have no meaning at run-time. You don't really need to know about these
1545 sections for most purposes; but they can be mentioned in @code{_AS__}
1546 warning messages, so it might be helpful to have an idea of their
1547 meanings to @code{_AS__}. These sections are used to permit the
1548 value of every expression in your assembly language program to be a
1549 section-relative address.
1553 @cindex absent (internal section)
1554 An expression was expected and none was found.
1556 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
1557 @cindex assembler internal logic error
1558 An internal assembler logic error has been found. This means there is a
1559 bug in the assembler.
1562 @cindex bignum/flonum (internal section)
1563 If a number can't be written as a C @code{int} constant (a bignum or a
1564 flonum, but not an integer), it is recorded as belonging to this
1565 ``section''. @code{_AS__} has to remember that a flonum or a bignum
1566 does not fit into 32 bits, and cannot be an argument (@pxref{Arguments})
1567 in an expression: this is done by making a flonum or bignum be in a
1568 separate internal section. This is purely for internal @code{_AS__}
1569 convenience; bignum/flonum section behaves similarly to absolute
1573 @cindex pass1 (internal section)
1574 The expression was impossible to evaluate in the first pass. The
1575 assembler will attempt a second pass (second reading of the source) to
1576 evaluate the expression. Your expression mentioned an undefined symbol
1577 in a way that defies the one-pass (section + offset in section) assembly
1578 process. No compiler need emit such an expression.
1581 @emph{Warning:} the second pass is currently not implemented. @code{_AS__}
1582 will abort with an error message if one is required.
1585 @item difference section
1586 @cindex difference (internal section)
1587 As an assist to the C compiler, expressions of the forms
1589 (@var{undefined symbol}) @minus{} (@var{expression})
1590 @var{something} @minus{} (@var{undefined symbol})
1591 (@var{undefined symbol}) @minus{} (@var{undefined symbol})
1594 are permitted, and belong to the difference section. @code{_AS__}
1595 re-evaluates such expressions after the source file has been read and
1596 the symbol table built. If by that time there are no undefined symbols
1597 in the expression then the expression assumes a new section. The
1598 intention is to permit statements like
1599 @samp{.word label - base_of_table}
1600 to be assembled in one pass where both @code{label} and
1601 @code{base_of_table} are undefined. This is useful for compiling C and
1602 Algol switch statements, Pascal case statements, FORTRAN computed goto
1603 statements and the like.
1605 @c FIXME item transfer[t] vector preload
1606 @c FIXME item transfer[t] vector postload
1607 @c FIXME item register
1611 @section Sub-Sections
1613 @cindex numbered subsections
1614 @cindex grouping data
1615 _if__(_AOUT__||_BOUT__)
1620 fall into two sections: text and data.
1621 _fi__(_AOUT__||_BOUT__)
1622 You may have separate groups of
1623 _if__(_COFF__||_GENERIC__)
1624 data in named sections
1625 _fi__(_COFF__||_GENERIC__)
1626 _if__((_AOUT__||_BOUT__)&&!_GENERIC__)
1628 _fi__((_AOUT__||_BOUT__)&&!_GENERIC__)
1629 that you want to end up near to each other in the object
1630 file, even though they are not contiguous in the assembler source.
1631 @code{_AS__} allows you to use @dfn{subsections} for this purpose.
1632 Within each section, there can be numbered subsections with
1633 values from 0 to 8192. Objects assembled into the same subsection will
1634 be grouped with other objects in the same subsection when they are all
1635 put into the object file. For example, a compiler might want to store
1636 constants in the text section, but might not want to have them
1637 interspersed with the program being assembled. In this case, the
1638 compiler could issue a @samp{.text 0} before each section of code being
1639 output, and a @samp{.text 1} before each group of constants being output.
1641 Subsections are optional. If you don't use subsections, everything
1642 will be stored in subsection number zero.
1645 Each subsection is zero-padded up to a multiple of four bytes.
1646 (Subsections may be padded a different amount on different flavors
1651 On the H8/300 platform, each subsection is zero-padded to a word
1652 boundary (two bytes).
1655 @c FIXME section padding (alignment)?
1656 @c Rich Pixley says padding here depends on target obj code format; that
1657 @c doesn't seem particularly useful to say without further elaboration,
1658 @c so for now I say nothing about it. If this is a generic BFD issue,
1659 @c these paragraphs might need to vanish from this manual, and be
1660 @c discussed in BFD chapter of binutils (or some such).
1663 On the AMD 29K family, no particular padding is added to section or
1664 subsection sizes; _AS__ forces no alignment on this platform.
1668 Subsections appear in your object file in numeric order, lowest numbered
1669 to highest. (All this to be compatible with other people's assemblers.)
1670 The object file contains no representation of subsections; @code{_LD__} and
1671 other programs that manipulate object files will see no trace of them.
1672 They just see all your text subsections as a text section, and all your
1673 data subsections as a data section.
1675 To specify which subsection you want subsequent statements assembled
1676 into, use a numeric argument to specify it, in a @samp{.text
1677 @var{expression}} or a @samp{.data @var{expression}} statement.
1680 When generating COFF output, you
1685 can also use an extra subsection
1686 argument with arbitrary named sections: @samp{.section @var{name},
1689 @var{Expression} should be an absolute expression.
1690 (@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
1691 is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
1692 begins in @code{text 0}. For instance:
1694 .text 0 # The default subsection is text 0 anyway.
1695 .ascii "This lives in the first text subsection. *"
1697 .ascii "But this lives in the second text subsection."
1699 .ascii "This lives in the data section,"
1700 .ascii "in the first data subsection."
1702 .ascii "This lives in the first text section,"
1703 .ascii "immediately following the asterisk (*)."
1706 Each section has a @dfn{location counter} incremented by one for every
1707 byte assembled into that section. Because subsections are merely a
1708 convenience restricted to @code{_AS__} there is no concept of a subsection
1709 location counter. There is no way to directly manipulate a location
1710 counter---but the @code{.align} directive will change it, and any label
1711 definition will capture its current value. The location counter of the
1712 section that statements are being assembled into is said to be the
1713 @dfn{active} location counter.
1716 @section bss Section
1719 @cindex common variable storage
1720 The bss section is used for local common variable storage.
1721 You may allocate address space in the bss section, but you may
1722 not dictate data to load into it before your program executes. When
1723 your program starts running, all the contents of the bss
1724 section are zeroed bytes.
1726 Addresses in the bss section are allocated with special directives; you
1727 may not assemble anything directly into the bss section. Hence there
1728 are no bss subsections. @xref{Comm,,@code{.comm}},
1729 @pxref{Lcomm,,@code{.lcomm}}.
1735 Symbols are a central concept: the programmer uses symbols to name
1736 things, the linker uses symbols to link, and the debugger uses symbols
1740 @cindex debuggers, and symbol order
1741 @emph{Warning:} @code{_AS__} does not place symbols in the object file in
1742 the same order they were declared. This may break some debuggers.
1747 * Setting Symbols:: Giving Symbols Other Values
1748 * Symbol Names:: Symbol Names
1749 * Dot:: The Special Dot Symbol
1750 * Symbol Attributes:: Symbol Attributes
1757 A @dfn{label} is written as a symbol immediately followed by a colon
1758 @samp{:}. The symbol then represents the current value of the
1759 active location counter, and is, for example, a suitable instruction
1760 operand. You are warned if you use the same symbol to represent two
1761 different locations: the first definition overrides any other
1764 @node Setting Symbols
1765 @section Giving Symbols Other Values
1767 @cindex assigning values to symbols
1768 @cindex symbol values, assigning
1769 A symbol can be given an arbitrary value by writing a symbol, followed
1770 by an equals sign @samp{=}, followed by an expression
1771 (@pxref{Expressions}). This is equivalent to using the @code{.set}
1772 directive. @xref{Set,,@code{.set}}.
1775 @section Symbol Names
1777 @cindex symbol names
1778 @cindex names, symbol
1779 Symbol names begin with a letter or with one of
1786 (On most machines, you can also use @code{$} in symbol names; exceptions
1787 are noted in @ref{_MACH_DEP__}.)
1790 That character may be followed by any string of digits, letters,
1792 underscores and dollar signs.
1796 dollar signs (unless otherwise noted in @ref{_MACH_DEP__}),
1800 Case of letters is significant:
1801 @code{foo} is a different symbol name than @code{Foo}.
1804 For the AMD 29K family, @samp{?} is also allowed in the
1805 body of a symbol name, though not at its beginning.
1808 Each symbol has exactly one name. Each name in an assembly language
1809 program refers to exactly one symbol. You may use that symbol name any
1810 number of times in a program.
1812 @subheading Local Symbol Names
1814 @cindex local symbol names
1815 @cindex symbol names, local
1816 @cindex temporary symbol names
1817 @cindex symbol names, temporary
1818 Local symbols help compilers and programmers use names temporarily.
1819 There are ten local symbol names, which are re-used throughout the
1820 program. You may refer to them using the names @samp{0} @samp{1}
1821 @dots{} @samp{9}. To define a local symbol, write a label of the form
1822 @samp{@b{N}:} (where @b{N} represents any digit). To refer to the most
1823 recent previous definition of that symbol write @samp{@b{N}b}, using the
1824 same digit as when you defined the label. To refer to the next
1825 definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
1826 a choice of 10 forward references. The @samp{b} stands for
1827 ``backwards'' and the @samp{f} stands for ``forwards''.
1829 Local symbols are not emitted by the current GNU C compiler.
1831 There is no restriction on how you can use these labels, but
1832 remember that at any point in the assembly you can refer to at most
1833 10 prior local labels and to at most 10 forward local labels.
1835 Local symbol names are only a notation device. They are immediately
1836 transformed into more conventional symbol names before the assembler
1837 uses them. The symbol names stored in the symbol table, appearing in
1838 error messages and optionally emitted to the object file have these
1843 All local labels begin with @samp{L}. Normally both @code{_AS__} and
1844 @code{_LD__} forget symbols that start with @samp{L}. These labels are
1845 used for symbols you are never intended to see. If you give the
1846 @samp{-L} option then @code{_AS__} will retain these symbols in the
1847 object file. If you also instruct @code{_LD__} to retain these symbols,
1848 you may use them in debugging.
1851 If the label is written @samp{0:} then the digit is @samp{0}.
1852 If the label is written @samp{1:} then the digit is @samp{1}.
1853 And so on up through @samp{9:}.
1856 This unusual character is included so you don't accidentally invent
1857 a symbol of the same name. The character has ASCII value
1860 @item @emph{ordinal number}
1861 This is a serial number to keep the labels distinct. The first
1862 @samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
1863 number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
1867 For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th
1868 @code{3:} is named @code{L3@ctrl{A}44}.
1871 @section The Special Dot Symbol
1873 @cindex dot (symbol)
1874 @cindex @code{.} (symbol)
1875 @cindex current address
1876 @cindex location counter
1877 The special symbol @samp{.} refers to the current address that
1878 @code{_AS__} is assembling into. Thus, the expression @samp{melvin:
1879 .long .} will cause @code{melvin} to contain its own address.
1880 Assigning a value to @code{.} is treated the same as a @code{.org}
1881 directive. Thus, the expression @samp{.=.+4} is the same as saying
1889 @node Symbol Attributes
1890 @section Symbol Attributes
1892 @cindex symbol attributes
1893 @cindex attributes, symbol
1894 Every symbol has, as well as its name, the attributes ``Value'' and
1895 ``Type''. Depending on output format, symbols can also have auxiliary
1898 The detailed definitions are in _0__<a.out.h>_1__.
1901 If you use a symbol without defining it, @code{_AS__} assumes zero for
1902 all these attributes, and probably won't warn you. This makes the
1903 symbol an externally defined symbol, which is generally what you
1907 * Symbol Value:: Value
1908 * Symbol Type:: Type
1909 _if__(_AOUT__||_BOUT__)
1910 _if__(_GENERIC__||!_BOUT__)
1911 * a.out Symbols:: Symbol Attributes: @code{a.out}
1912 _fi__(_GENERIC__||!_BOUT__)
1913 _if__(_BOUT__&&!_GENERIC__)
1914 * a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
1915 _fi__(_BOUT__&&!_GENERIC__)
1916 _fi__(_AOUT__||_BOUT__)
1918 * COFF Symbols:: Symbol Attributes for COFF
1925 @cindex value of a symbol
1926 @cindex symbol value
1927 The value of a symbol is (usually) 32 bits. For a symbol which labels a
1928 location in the text, data, bss or absolute sections the value is the
1929 number of addresses from the start of that section to the label.
1930 Naturally for text, data and bss sections the value of a symbol changes
1931 as @code{_LD__} changes section base addresses during linking. Absolute
1932 symbols' values do not change during linking: that is why they are
1935 The value of an undefined symbol is treated in a special way. If it is
1936 0 then the symbol is not defined in this assembler source program, and
1937 @code{_LD__} will try to determine its value from other programs it is
1938 linked with. You make this kind of symbol simply by mentioning a symbol
1939 name without defining it. A non-zero value represents a @code{.comm}
1940 common declaration. The value is how much common storage to reserve, in
1941 bytes (addresses). The symbol refers to the first address of the
1947 @cindex type of a symbol
1949 The type attribute of a symbol contains relocation (section)
1950 information, any flag settings indicating that a symbol is external, and
1951 (optionally), other information for linkers and debuggers. The exact
1952 format depends on the object-code output format in use.
1954 _if__(_AOUT__||_BOUT__)
1956 _if__(_BOUT__&&!_GENERIC__)
1957 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
1959 @cindex @code{b.out} symbol attributes
1960 @cindex symbol attributes, @code{b.out}
1961 These symbol attributes appear only when @code{_AS__} is configured for
1962 one of the Berkeley-descended object output formats.
1963 _fi__(_BOUT__&&!_GENERIC__)
1964 _if__(_GENERIC__||!_BOUT__)
1965 @subsection Symbol Attributes: @code{a.out}
1966 _fi__(_GENERIC__||!_BOUT__)
1968 @cindex @code{a.out} symbol attributes
1969 @cindex symbol attributes, @code{a.out}
1972 * Symbol Desc:: Descriptor
1973 * Symbol Other:: Other
1977 @subsubsection Descriptor
1979 @cindex descriptor, of @code{a.out} symbol
1980 This is an arbitrary 16-bit value. You may establish a symbol's
1981 descriptor value by using a @code{.desc} statement
1982 (@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
1986 @subsubsection Other
1988 @cindex other attribute, of @code{a.out} symbol
1989 This is an arbitrary 8-bit value. It means nothing to @code{_AS__}.
1990 _fi__(_AOUT__||_BOUT__)
1994 @subsection Symbol Attributes for COFF
1996 @cindex COFF symbol attributes
1997 @cindex symbol attributes, COFF
1999 The COFF format supports a multitude of auxiliary symbol attributes;
2000 like the primary symbol attributes, they are set between @code{.def} and
2001 @code{.endef} directives.
2003 @subsubsection Primary Attributes
2005 @cindex primary attributes, COFF symbols
2006 The symbol name is set with @code{.def}; the value and type,
2007 respectively, with @code{.val} and @code{.type}.
2009 @subsubsection Auxiliary Attributes
2011 @cindex auxiliary attributes, COFF symbols
2012 The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl},
2013 @code{.size}, and @code{.tag} can generate auxiliary symbol table
2014 information for COFF.
2018 @chapter Expressions
2022 @cindex numeric values
2023 An @dfn{expression} specifies an address or numeric value.
2024 Whitespace may precede and/or follow an expression.
2027 * Empty Exprs:: Empty Expressions
2028 * Integer Exprs:: Integer Expressions
2032 @section Empty Expressions
2034 @cindex empty expressions
2035 @cindex expressions, empty
2036 An empty expression has no value: it is just whitespace or null.
2037 Wherever an absolute expression is required, you may omit the
2038 expression and @code{_AS__} will assume a value of (absolute) 0. This
2039 is compatible with other assemblers.
2042 @section Integer Expressions
2044 @cindex integer expressions
2045 @cindex expressions, integer
2046 An @dfn{integer expression} is one or more @emph{arguments} delimited
2047 by @emph{operators}.
2050 * Arguments:: Arguments
2051 * Operators:: Operators
2052 * Prefix Ops:: Prefix Operators
2053 * Infix Ops:: Infix Operators
2057 @subsection Arguments
2059 @cindex expression arguments
2060 @cindex arguments in expressions
2061 @cindex operands in expressions
2062 @cindex arithmetic operands
2063 @dfn{Arguments} are symbols, numbers or subexpressions. In other
2064 contexts arguments are sometimes called ``arithmetic operands''. In
2065 this manual, to avoid confusing them with the ``instruction operands'' of
2066 the machine language, we use the term ``argument'' to refer to parts of
2067 expressions only, reserving the word ``operand'' to refer only to machine
2068 instruction operands.
2070 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
2071 @var{section} is one of text, data, bss, absolute,
2072 or undefined. @var{NNN} is a signed, 2's complement 32 bit
2075 Numbers are usually integers.
2077 A number can be a flonum or bignum. In this case, you are warned
2078 that only the low order 32 bits are used, and @code{_AS__} pretends
2079 these 32 bits are an integer. You may write integer-manipulating
2080 instructions that act on exotic constants, compatible with other
2083 @cindex subexpressions
2084 Subexpressions are a left parenthesis @samp{(} followed by an integer
2085 expression, followed by a right parenthesis @samp{)}; or a prefix
2086 operator followed by an argument.
2089 @subsection Operators
2091 @cindex operators, in expressions
2092 @cindex arithmetic functions
2093 @cindex functions, in expressions
2094 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
2095 operators are followed by an argument. Infix operators appear
2096 between their arguments. Operators may be preceded and/or followed by
2100 @subsection Prefix Operator
2102 @cindex prefix operators
2103 @code{_AS__} has the following @dfn{prefix operators}. They each take
2104 one argument, which must be absolute.
2106 @c the tex/end tex stuff surrounding this small table is meant to make
2107 @c it align, on the printed page, with the similar table in the next
2108 @c section (which is inside an enumerate).
2110 \global\advance\leftskip by \itemindent
2115 @dfn{Negation}. Two's complement negation.
2117 @dfn{Complementation}. Bitwise not.
2121 \global\advance\leftskip by -\itemindent
2125 @subsection Infix Operators
2127 @cindex infix operators
2128 @cindex operators, permitted arguments
2129 @dfn{Infix operators} take two arguments, one on either side. Operators
2130 have precedence, but operations with equal precedence are performed left
2131 to right. Apart from @code{+} or @code{-}, both arguments must be
2132 absolute, and the result is absolute.
2135 @cindex operator precedence
2136 @cindex precedence of operators
2143 @dfn{Multiplication}.
2146 @dfn{Division}. Truncation is the same as the C operator @samp{/}
2153 @dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__}
2157 @dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__}
2161 Intermediate precedence
2166 @dfn{Bitwise Inclusive Or}.
2172 @dfn{Bitwise Exclusive Or}.
2175 @dfn{Bitwise Or Not}.
2183 @cindex addition, permitted arguments
2184 @cindex plus, permitted arguments
2185 @cindex arguments for addition
2186 @dfn{Addition}. If either argument is absolute, the result
2187 has the section of the other argument.
2188 If either argument is pass1 or undefined, the result is pass1.
2189 Otherwise @code{+} is illegal.
2192 @cindex subtraction, permitted arguments
2193 @cindex minus, permitted arguments
2194 @cindex arguments for subtraction
2195 @dfn{Subtraction}. If the right argument is absolute, the
2196 result has the section of the left argument.
2197 If either argument is pass1 the result is pass1.
2198 If either argument is undefined the result is difference section.
2199 If both arguments are in the same section, the result is absolute---provided
2200 that section is one of text, data or bss.
2201 Otherwise subtraction is illegal.
2205 The sense of the rule for addition is that it's only meaningful to add
2206 the @emph{offsets} in an address; you can only have a defined section in
2207 one of the two arguments.
2209 Similarly, you can't subtract quantities from two different sections.
2212 @chapter Assembler Directives
2214 @cindex directives, machine independent
2215 @cindex pseudo-ops, machine independent
2216 @cindex machine independent directives
2217 All assembler directives have names that begin with a period (@samp{.}).
2218 The rest of the name is letters, usually in lower case.
2220 This chapter discusses directives present regardless of the target
2221 machine configuration for the GNU assembler.
2223 @xref{_MACH_DEP__} for additional directives.
2227 * Abort:: @code{.abort}
2229 * coff-ABORT:: @code{.ABORT}
2231 _if__(_BOUT__&&!_COFF__)
2232 * bout-ABORT:: @code{.ABORT}
2233 _fi__(_BOUT__&&!_COFF__)
2234 * Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
2235 * App-File:: @code{.app-file @var{string}}
2236 * Ascii:: @code{.ascii "@var{string}"}@dots{}
2237 * Asciz:: @code{.asciz "@var{string}"}@dots{}
2238 * Byte:: @code{.byte @var{expressions}}
2239 * Comm:: @code{.comm @var{symbol} , @var{length} }
2240 * Data:: @code{.data @var{subsection}}
2241 _if__(_COFF__||_BOUT__)
2242 * Def:: @code{.def @var{name}}
2243 _fi__(_COFF__||_BOUT__)
2244 _if__(_AOUT__||_BOUT__)
2245 * Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
2246 _fi__(_AOUT__||_BOUT__)
2247 _if__(_COFF__||_BOUT__)
2249 _fi__(_COFF__||_BOUT__)
2250 * Double:: @code{.double @var{flonums}}
2251 * Eject:: @code{.eject}
2252 * Else:: @code{.else}
2253 _if__(_COFF__||_BOUT__)
2254 * Endef:: @code{.endef}
2255 _fi__(_COFF__||_BOUT__)
2256 * Endif:: @code{.endif}
2257 * Equ:: @code{.equ @var{symbol}, @var{expression}}
2258 * Extern:: @code{.extern}
2259 _if__(_GENERIC__||!_A29K__)
2260 * File:: @code{.file @var{string}}
2261 _fi__(_GENERIC__||!_A29K__)
2262 * Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
2263 * Float:: @code{.float @var{flonums}}
2264 * Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2265 * hword:: @code{.hword @var{expressions}}
2266 * Ident:: @code{.ident}
2267 * If:: @code{.if @var{absolute expression}}
2268 * Include:: @code{.include "@var{file}"}
2269 * Int:: @code{.int @var{expressions}}
2270 * Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
2271 * Lflags:: @code{.lflags}
2272 _if__(_GENERIC__||!_A29K__)
2273 * Line:: @code{.line @var{line-number}}
2274 _fi__(_GENERIC__||!_A29K__)
2275 * Ln:: @code{.ln @var{line-number}}
2276 * List:: @code{.list}
2277 * Long:: @code{.long @var{expressions}}
2279 * Lsym:: @code{.lsym @var{symbol}, @var{expression}}
2281 * Nolist:: @code{.nolist}
2282 * Octa:: @code{.octa @var{bignums}}
2283 * Org:: @code{.org @var{new-lc} , @var{fill}}
2284 * Psize:: @code{.psize @var{lines}, @var{columns}}
2285 * Quad:: @code{.quad @var{bignums}}
2286 * Sbttl:: @code{.sbttl "@var{subheading}"}
2287 _if__(_COFF__||_BOUT__)
2288 * Scl:: @code{.scl @var{class}}
2289 _fi__(_COFF__||_BOUT__)
2291 * Section:: @code{.section @var{name}, @var{subsection}}
2293 * Set:: @code{.set @var{symbol}, @var{expression}}
2294 * Short:: @code{.short @var{expressions}}
2295 * Single:: @code{.single @var{flonums}}
2296 _if__(_COFF__||_BOUT__)
2297 * Size:: @code{.size}
2298 _fi__(_COFF__||_BOUT__)
2299 * Space:: @code{.space @var{size} , @var{fill}}
2300 _if__(_GENERIC__||!_H8__)
2301 * Stab:: @code{.stabd, .stabn, .stabs}
2302 _fi__(_GENERIC__||!_H8__)
2303 _if__(_COFF__||_BOUT__)
2304 * Tag:: @code{.tag @var{structname}}
2305 _fi__(_COFF__||_BOUT__)
2306 * Text:: @code{.text @var{subsection}}
2307 * Title:: @code{.title "@var{heading}"}
2308 _if__(_COFF__||_BOUT__)
2309 * Type:: @code{.type @var{int}}
2310 * Val:: @code{.val @var{addr}}
2311 _fi__(_COFF__||_BOUT__)
2312 * Word:: @code{.word @var{expressions}}
2313 * Deprecated:: Deprecated Directives
2317 @section @code{.abort}
2319 @cindex @code{abort} directive
2320 @cindex stopping the assembly
2321 This directive stops the assembly immediately. It is for
2322 compatibility with other assemblers. The original idea was that the
2323 assembly language source would be piped into the assembler. If the sender
2324 of the source quit, it could use this directive tells @code{_AS__} to
2325 quit also. One day @code{.abort} will not be supported.
2329 @section @code{.ABORT}
2331 @cindex @code{ABORT} directive
2332 When producing COFF output, @code{_AS__} accepts this directive as a
2333 synonym for @samp{.abort}.
2339 @section @code{.ABORT}
2341 @cindex @code{ABORT} directive
2344 When producing @code{b.out} output, @code{_AS__} accepts this directive,
2349 @section @code{.align @var{abs-expr} , @var{abs-expr}}
2351 @cindex padding the location counter
2352 @cindex @code{align} directive
2353 Pad the location counter (in the current subsection) to a particular
2354 storage boundary. The first expression (which must be absolute) is the
2355 number of low-order zero bits the location counter will have after
2356 advancement. For example @samp{.align 3} will advance the location
2357 counter until it a multiple of 8. If the location counter is already a
2358 multiple of 8, no change is needed.
2360 The second expression (also absolute) gives the value to be stored in
2361 the padding bytes. It (and the comma) may be omitted. If it is
2362 omitted, the padding bytes are zero.
2365 @section @code{.app-file @var{string}}
2367 @cindex logical file name
2368 @cindex file name, logical
2369 @cindex @code{app-file} directive
2372 (which may also be spelled @samp{.file})
2374 tells @code{_AS__} that we are about to start a new
2375 logical file. @var{string} is the new file name. In general, the
2376 filename is recognized whether or not it is surrounded by quotes @samp{"};
2377 but if you wish to specify an empty file name is permitted,
2378 you must give the quotes--@code{""}. This statement may go away in
2379 future: it is only recognized to be compatible with old @code{_AS__}
2383 @section @code{.ascii "@var{string}"}@dots{}
2385 @cindex @code{ascii} directive
2386 @cindex string literals
2387 @code{.ascii} expects zero or more string literals (@pxref{Strings})
2388 separated by commas. It assembles each string (with no automatic
2389 trailing zero byte) into consecutive addresses.
2392 @section @code{.asciz "@var{string}"}@dots{}
2394 @cindex @code{asciz} directive
2395 @cindex zero-terminated strings
2396 @cindex null-terminated strings
2397 @code{.asciz} is just like @code{.ascii}, but each string is followed by
2398 a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
2401 @section @code{.byte @var{expressions}}
2403 @cindex @code{byte} directive
2404 @cindex integers, one byte
2405 @code{.byte} expects zero or more expressions, separated by commas.
2406 Each expression is assembled into the next byte.
2409 @section @code{.comm @var{symbol} , @var{length} }
2411 @cindex @code{comm} directive
2412 @cindex symbol, common
2413 @code{.comm} declares a named common area in the bss section. Normally
2414 @code{_LD__} reserves memory addresses for it during linking, so no partial
2415 program defines the location of the symbol. Use @code{.comm} to tell
2416 @code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__}
2417 will allocate space for each @code{.comm} symbol that is at least as
2418 long as the longest @code{.comm} request in any of the partial programs
2419 linked. @var{length} is an absolute expression.
2422 @section @code{.data @var{subsection}}
2424 @cindex @code{data} directive
2425 @code{.data} tells @code{_AS__} to assemble the following statements onto the
2426 end of the data subsection numbered @var{subsection} (which is an
2427 absolute expression). If @var{subsection} is omitted, it defaults
2430 _if__(_COFF__ || _BOUT__)
2432 @section @code{.def @var{name}}
2434 @cindex @code{def} directive
2435 @cindex COFF symbols, debugging
2436 @cindex debugging COFF symbols
2437 Begin defining debugging information for a symbol @var{name}; the
2438 definition extends until the @code{.endef} directive is encountered.
2441 This directive is only observed when @code{_AS__} is configured for COFF
2442 format output; when producing @code{b.out}, @samp{.def} is recognized,
2445 _fi__(_COFF__ || _BOUT__)
2447 _if__(_AOUT__||_BOUT__)
2449 @section @code{.desc @var{symbol}, @var{abs-expression}}
2451 @cindex @code{desc} directive
2452 @cindex COFF symbol descriptor
2453 @cindex symbol descriptor, COFF
2454 This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
2455 to the low 16 bits of an absolute expression.
2458 The @samp{.desc} directive is not available when @code{_AS__} is
2459 configured for COFF output; it is only for @code{a.out} or @code{b.out}
2460 object format. For the sake of compatibility, @code{_AS__} will accept
2461 it, but produce no output, when configured for COFF.
2463 _fi__(_AOUT__||_BOUT__)
2465 _if__(_COFF__ || _BOUT__)
2467 @section @code{.dim}
2469 @cindex @code{dim} directive
2470 @cindex COFF auxiliary symbol information
2471 @cindex auxiliary symbol information, COFF
2472 This directive is generated by compilers to include auxiliary debugging
2473 information in the symbol table. It is only permitted inside
2474 @code{.def}/@code{.endef} pairs.
2477 @samp{.dim} is only meaningful when generating COFF format output; when
2478 @code{_AS__} is generating @code{b.out}, it accepts this directive but
2481 _fi__(_COFF__ || _BOUT__)
2484 @section @code{.double @var{flonums}}
2486 @cindex @code{double} directive
2487 @cindex floating point numbers (double)
2488 @code{.double} expects zero or more flonums, separated by commas. It
2489 assembles floating point numbers.
2491 The exact kind of floating point numbers emitted depends on how
2492 @code{_AS__} is configured. @xref{_MACH_DEP__}.
2494 _if__((!_GENERIC__) && _IEEEFLOAT__)
2495 On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers
2496 in @sc{ieee} format.
2497 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2500 @section @code{.eject}
2502 @cindex @code{eject} directive
2503 @cindex new page, in listings
2504 @cindex page, in listings
2505 @cindex listing control: new page
2506 Force a page break at this point, when generating assembly listings.
2509 @section @code{.else}
2511 @cindex @code{else} directive
2512 @code{.else} is part of the @code{_AS__} support for conditional
2513 assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
2514 of code to be assembled if the condition for the preceding @code{.if}
2518 @node End, Endef, Else, Pseudo Ops
2519 @section @code{.end}
2521 @cindex @code{end} directive
2522 This doesn't do anything---but isn't an s_ignore, so I suspect it's
2523 meant to do something eventually (which is why it isn't documented here
2524 as "for compatibility with blah").
2527 _if__(_COFF__||_BOUT__)
2529 @section @code{.endef}
2531 @cindex @code{endef} directive
2532 This directive flags the end of a symbol definition begun with
2536 @samp{.endef} is only meaningful when generating COFF format output; if
2537 @code{_AS__} is configured to generate @code{b.out}, it accepts this
2538 directive but ignores it.
2540 _fi__(_COFF__||_BOUT__)
2543 @section @code{.endif}
2545 @cindex @code{endif} directive
2546 @code{.endif} is part of the @code{_AS__} support for conditional assembly;
2547 it marks the end of a block of code that is only assembled
2548 conditionally. @xref{If,,@code{.if}}.
2551 @section @code{.equ @var{symbol}, @var{expression}}
2553 @cindex @code{equ} directive
2554 @cindex assigning values to symbols
2555 @cindex symbols, assigning values to
2556 This directive sets the value of @var{symbol} to @var{expression}.
2557 It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
2560 @section @code{.extern}
2562 @cindex @code{extern} directive
2563 @code{.extern} is accepted in the source program---for compatibility
2564 with other assemblers---but it is ignored. @code{_AS__} treats
2565 all undefined symbols as external.
2567 _if__(_GENERIC__||!_A29K__)
2569 @section @code{.file @var{string}}
2571 @cindex @code{file} directive
2572 @cindex logical file name
2573 @cindex file name, logical
2574 @code{.file} (which may also be spelled @samp{.app-file}) tells
2575 @code{_AS__} that we are about to start a new logical file.
2576 @var{string} is the new file name. In general, the filename is
2577 recognized whether or not it is surrounded by quotes @samp{"}; but if
2578 you wish to specify an empty file name, you must give the
2579 quotes--@code{""}. This statement may go away in future: it is only
2580 recognized to be compatible with old @code{_AS__} programs.
2582 In some configurations of @code{_AS__}, @code{.file} has already been
2583 removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}.
2585 _fi__(_GENERIC__||!_A29K__)
2588 @section @code{.fill @var{repeat} , @var{size} , @var{value}}
2590 @cindex @code{fill} directive
2591 @cindex writing patterns in memory
2592 @cindex patterns, writing in memory
2593 @var{result}, @var{size} and @var{value} are absolute expressions.
2594 This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
2595 may be zero or more. @var{Size} may be zero or more, but if it is
2596 more than 8, then it is deemed to have the value 8, compatible with
2597 other people's assemblers. The contents of each @var{repeat} bytes
2598 is taken from an 8-byte number. The highest order 4 bytes are
2599 zero. The lowest order 4 bytes are @var{value} rendered in the
2600 byte-order of an integer on the computer @code{_AS__} is assembling for.
2601 Each @var{size} bytes in a repetition is taken from the lowest order
2602 @var{size} bytes of this number. Again, this bizarre behavior is
2603 compatible with other people's assemblers.
2605 @var{size} and @var{value} are optional.
2606 If the second comma and @var{value} are absent, @var{value} is
2607 assumed zero. If the first comma and following tokens are absent,
2608 @var{size} is assumed to be 1.
2611 @section @code{.float @var{flonums}}
2613 @cindex floating point numbers (single)
2614 @cindex @code{float} directive
2615 This directive assembles zero or more flonums, separated by commas. It
2616 has the same effect as @code{.single}.
2618 The exact kind of floating point numbers emitted depends on how
2619 @code{_AS__} is configured.
2622 _if__((!_GENERIC__) && _IEEEFLOAT__)
2623 On the _HOST__ family, @code{.float} emits 32-bit floating point numbers
2624 in @sc{ieee} format.
2625 _fi__((!_GENERIC__) && _IEEEFLOAT__)
2628 @section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
2630 @cindex @code{global} directive
2631 @cindex symbol, making visible to linker
2632 @code{.global} makes the symbol visible to @code{_LD__}. If you define
2633 @var{symbol} in your partial program, its value is made available to
2634 other partial programs that are linked with it. Otherwise,
2635 @var{symbol} will take its attributes from a symbol of the same name
2636 from another partial program it is linked with.
2638 Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
2639 compatibility with other assemblers.
2642 @section @code{.hword @var{expressions}}
2644 @cindex @code{hword} directive
2645 @cindex integers, 16-bit
2646 @cindex numbers, 16-bit
2647 @cindex sixteen bit integers
2648 This expects zero or more @var{expressions}, and emits
2649 a 16 bit number for each.
2652 This directive is a synonym for @samp{.short}; depending on the target
2653 architecture, it may also be a synonym for @samp{.word}.
2655 _if__( _W32__ && !_GENERIC__ )
2656 This directive is a synonym for @samp{.short}.
2657 _fi__( _W32__ && !_GENERIC__ )
2658 _if__(_W16__ && !_GENERIC__ )
2659 This directive is a synonym for both @samp{.short} and @samp{.word}.
2660 _fi__(_W16__ && !_GENERIC__ )
2662 _if__(_AOUT__||_BOUT__||_COFF__)
2664 @section @code{.ident}
2666 @cindex @code{ident} directive
2667 This directive is used by some assemblers to place tags in object files.
2668 @code{_AS__} simply accepts the directive for source-file
2669 compatibility with such assemblers, but does not actually emit anything
2671 _fi__(_AOUT__||_BOUT__||_COFF__)
2674 @section @code{.if @var{absolute expression}}
2676 @cindex conditional assembly
2677 @cindex @code{if} directive
2678 @code{.if} marks the beginning of a section of code which is only
2679 considered part of the source program being assembled if the argument
2680 (which must be an @var{absolute expression}) is non-zero. The end of
2681 the conditional section of code must be marked by @code{.endif}
2682 (@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
2683 alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}.
2685 The following variants of @code{.if} are also supported:
2687 @item .ifdef @var{symbol}
2688 @cindex @code{ifdef} directive
2689 Assembles the following section of code if the specified @var{symbol}
2694 @cindex @code{ifeqs} directive
2695 Not yet implemented.
2698 @item .ifndef @var{symbol}
2699 @itemx ifnotdef @var{symbol}
2700 @cindex @code{ifndef} directive
2701 @cindex @code{ifnotdef} directive
2702 Assembles the following section of code if the specified @var{symbol}
2703 has not been defined. Both spelling variants are equivalent.
2707 Not yet implemented.
2712 @section @code{.include "@var{file}"}
2714 @cindex @code{include} directive
2715 @cindex supporting files, including
2716 @cindex files, including
2717 This directive provides a way to include supporting files at specified
2718 points in your source program. The code from @var{file} is assembled as
2719 if it followed the point of the @code{.include}; when the end of the
2720 included file is reached, assembly of the original file continues. You
2721 can control the search paths used with the @samp{-I} command-line option
2722 (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
2726 @section @code{.int @var{expressions}}
2728 @cindex @code{int} directive
2729 _if__(_GENERIC__||!_H8__)
2730 @cindex integers, 32-bit
2731 _fi__(_GENERIC__||!_H8__)
2732 Expect zero or more @var{expressions}, of any section, separated by
2733 commas. For each expression, emit a
2734 _if__(_GENERIC__||!_H8__)
2736 _fi__(_GENERIC__||!_H8__)
2737 _if__(_H8__&&!_GENERIC__)
2739 _fi__(_H8__&&!_GENERIC__)
2740 number that will, at run
2741 time, be the value of that expression. The byte order of the
2742 expression depends on what kind of computer will run the program.
2745 @section @code{.lcomm @var{symbol} , @var{length}}
2747 @cindex @code{lcomm} directive
2748 @cindex local common symbols
2749 @cindex symbols, local common
2750 Reserve @var{length} (an absolute expression) bytes for a local common
2751 denoted by @var{symbol}. The section and value of @var{symbol} are
2752 those of the new local common. The addresses are allocated in the bss
2753 section, so at run-time the bytes will start off zeroed. @var{Symbol}
2754 is not declared global (@pxref{Global,,@code{.global}}), so is normally
2755 not visible to @code{_LD__}.
2758 @section @code{.lflags}
2760 @cindex @code{lflags} directive (ignored)
2761 @code{_AS__} accepts this directive, for compatibility with other
2762 assemblers, but ignores it.
2764 _if__(_GENERIC__ || !_A29K__)
2766 @section @code{.line @var{line-number}}
2768 @cindex @code{line} directive
2769 _fi__(_GENERIC__ || (!_A29K__))
2770 _if__(_A29K__ && (!_GENERIC__) && !_COFF__)
2772 @section @code{.ln @var{line-number}}
2774 @cindex @code{ln} directive
2775 _fi__(_A29K__ && (!_GENERIC__) && !_COFF__)
2776 @cindex logical line number
2777 _if__(_AOUT__||_BOUT__)
2778 Tell @code{_AS__} to change the logical line number. @var{line-number} must be
2779 an absolute expression. The next line will have that logical line
2780 number. So any other statements on the current line (after a statement
2786 _if__(! (_A29K__||_H8__) )
2788 _fi__(! (_A29K__||_H8__) )
2790 character @samp{@@})
2796 will be reported as on logical line number
2797 @var{line-number} @minus{} 1.
2798 One day this directive will be unsupported: it is used only
2799 for compatibility with existing assembler programs. @refill
2801 _if__(_GENERIC__ && _A29K__)
2802 @emph{Warning:} In the AMD29K configuration of _AS__, this command is
2803 only available with the name @code{.ln}, rather than as either
2804 @code{.line} or @code{.ln}.
2805 _fi__(_GENERIC__ && _A29K__)
2806 _fi__(_AOUT__||_BOUT__)
2807 _if__(_COFF__ && !_A29K__)
2809 Even though this is a directive associated with the @code{a.out} or
2810 @code{b.out} object-code formats, @code{_AS__} will still recognize it
2811 when producing COFF output, and will treat @samp{.line} as though it
2812 were the COFF @samp{.ln} @emph{if} it is found outside a
2813 @code{.def}/@code{.endef} pair.
2815 Inside a @code{.def}, @samp{.line} is, instead, one of the directives
2816 used by compilers to generate auxiliary symbol information for
2818 _fi__(_COFF__ && !_A29K__)
2820 _if__(_AOUT__&&(_GENERIC__||!_A29K__))
2822 @section @code{.ln @var{line-number}}
2824 @cindex @code{ln} directive
2825 @samp{.ln} is a synonym for @samp{.line}.
2826 _fi__(_AOUT__&&(_GENERIC__||!_A29K__))
2827 _if__(_COFF__&&!_AOUT__)
2829 @section @code{.ln @var{line-number}}
2831 @cindex @code{ln} directive
2832 Tell @code{_AS__} to change the logical line number. @var{line-number}
2833 must be an absolute expression. The next line will have that logical
2834 line number, so any other statements on the current line (after a
2835 statement separator character @code{;}) will be reported as on logical
2836 line number @var{line-number} @minus{} 1.
2839 This directive is accepted, but ignored, when @code{_AS__} is configured for
2840 @code{b.out}; its effect is only associated with COFF output format.
2842 _fi__(_COFF__&&!_AOUT__)
2845 @section @code{.list}
2847 @cindex @code{list} directive
2848 @cindex listing control, turning on
2849 Control (in conjunction with the @code{.nolist} directive) whether or
2850 not assembly listings are generated. These two directives maintain an
2851 internal counter (which is zero initially). @code{.list} increments the
2852 counter, and @code{.nolist} decrements it. Assembly listings are
2853 generated whenever the counter is greater than zero.
2855 By default, listings are disabled. When you enable them (with the
2856 @samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
2857 the initial value of the listing counter is one.
2860 @section @code{.long @var{expressions}}
2862 @cindex @code{long} directive
2863 @code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
2866 @c no one seems to know what this is for or whether this description is
2867 @c what it really ought to do
2869 @section @code{.lsym @var{symbol}, @var{expression}}
2871 @cindex @code{lsym} directive
2872 @cindex symbol, not referenced in assembly
2873 @code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
2874 the hash table, ensuring it cannot be referenced by name during the
2875 rest of the assembly. This sets the attributes of the symbol to be
2876 the same as the expression value:
2878 @var{other} = @var{descriptor} = 0
2879 @var{type} = @r{(section of @var{expression})}
2880 @var{value} = @var{expression}
2883 The new symbol is not flagged as external.
2887 @section @code{.nolist}
2889 @cindex @code{nolist} directive
2890 @cindex listing control, turning off
2891 Control (in conjunction with the @code{.list} directive) whether or
2892 not assembly listings are generated. These two directives maintain an
2893 internal counter (which is zero initially). @code{.list} increments the
2894 counter, and @code{.nolist} decrements it. Assembly listings are
2895 generated whenever the counter is greater than zero.
2898 @section @code{.octa @var{bignums}}
2900 @c FIXME: double size emitted for "octa" on i960, others? Or warn?
2901 @cindex @code{octa} directive
2902 @cindex integer, 16-byte
2903 @cindex sixteen byte integer
2904 This directive expects zero or more bignums, separated by commas. For each
2905 bignum, it emits a 16-byte integer.
2907 The term ``octa'' comes from contexts in which a ``word'' is two bytes;
2908 hence @emph{octa}-word for 16 bytes.
2911 @section @code{.org @var{new-lc} , @var{fill}}
2913 @cindex @code{org} directive
2914 @cindex location counter, advancing
2915 @cindex advancing location counter
2916 @cindex current address, advancing
2917 @code{.org} will advance the location counter of the current section to
2918 @var{new-lc}. @var{new-lc} is either an absolute expression or an
2919 expression with the same section as the current subsection. That is,
2920 you can't use @code{.org} to cross sections: if @var{new-lc} has the
2921 wrong section, the @code{.org} directive is ignored. To be compatible
2922 with former assemblers, if the section of @var{new-lc} is absolute,
2923 @code{_AS__} will issue a warning, then pretend the section of @var{new-lc}
2924 is the same as the current subsection.
2926 @code{.org} may only increase the location counter, or leave it
2927 unchanged; you cannot use @code{.org} to move the location counter
2930 @c double negative used below "not undefined" because this is a specific
2931 @c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
2932 @c section. pesch@cygnus.com 18feb91
2933 Because @code{_AS__} tries to assemble programs in one pass @var{new-lc}
2934 may not be undefined. If you really detest this restriction we eagerly await
2935 a chance to share your improved assembler.
2937 Beware that the origin is relative to the start of the section, not
2938 to the start of the subsection. This is compatible with other
2939 people's assemblers.
2941 When the location counter (of the current subsection) is advanced, the
2942 intervening bytes are filled with @var{fill} which should be an
2943 absolute expression. If the comma and @var{fill} are omitted,
2944 @var{fill} defaults to zero.
2947 @section @code{.psize @var{lines} , @var{columns}}
2949 @cindex @code{psize} directive
2950 @cindex listing control: paper size
2951 @cindex paper size, for listings
2952 Use this directive to declare the number of lines---and, optionally, the
2953 number of columns---to use for each page, when generating listings.
2955 If you don't use @code{.psize}, listings will use a default line-count
2956 of 60. You may omit the comma and @var{columns} specification; the
2957 default width is 200 columns.
2959 @code{_AS__} will generate formfeeds whenever the specified number of
2960 lines is exceeded (or whenever you explicitly request one, using
2963 If you specify @var{lines} as @code{0}, no formfeeds are generated save
2964 those explicitly specified with @code{.eject}.
2967 @section @code{.quad @var{bignums}}
2969 @cindex @code{quad} directive
2970 @code{.quad} expects zero or more bignums, separated by commas. For
2971 each bignum, it emits
2972 _if__(_GENERIC__||(!_I960__))
2973 an 8-byte integer. If the bignum won't fit in 8
2974 bytes, it prints a warning message; and just takes the lowest order 8
2975 bytes of the bignum.@refill
2976 @cindex eight-byte integer
2977 @cindex integer, 8-byte
2979 The term ``quad'' comes from contexts in which a ``word'' is two bytes;
2980 hence @emph{quad}-word for 8 bytes.
2981 _fi__(_GENERIC__||(!_I960__))
2982 _if__(_I960__&&(!_GENERIC__))
2983 a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
2984 warning message; and just takes the lowest order 16 bytes of the
2986 @cindex sixteen-byte integer
2987 @cindex integer, 16-byte
2988 _fi__(_I960__&&(!_GENERIC__))
2991 @section @code{.sbttl "@var{subheading}"}
2993 @cindex @code{sbttl} directive
2994 @cindex subtitles for listings
2995 @cindex listing control: subtitle
2996 Use @var{subheading} as the title (third line, immediately after the
2997 title line) when generating assembly listings.
2999 This directive affects subsequent pages, as well as the current page if
3000 it appears within ten lines of the top of a page.
3002 _if__(_COFF__||_BOUT__)
3004 @section @code{.scl @var{class}}
3006 @cindex @code{scl} directive
3007 @cindex symbol storage class (COFF)
3008 @cindex COFF symbol storage class
3009 Set the storage-class value for a symbol. This directive may only be
3010 used inside a @code{.def}/@code{.endef} pair. Storage class may flag
3011 whether a symbol is static or external, or it may record further
3012 symbolic debugging information.
3015 The @samp{.scl} directive is primarily associated with COFF output; when
3016 configured to generate @code{b.out} output format, @code{_AS__} will
3017 accept this directive but ignore it.
3019 _fi__(_COFF__||_BOUT__)
3023 @section @code{.section @var{name}, @var{subsection}}
3025 @cindex @code{section} directive
3026 @cindex named section (COFF)
3027 @cindex COFF named section
3028 Assemble the following code into end of subsection numbered
3029 @var{subsection} in the COFF named section @var{name}. If you omit
3030 @var{subsection}, @code{_AS__} uses subsection number zero.
3031 @samp{.section .text} is equivalent to the @code{.text} directive;
3032 @samp{.section .data} is equivalent to the @code{.data} directive.
3036 @section @code{.set @var{symbol}, @var{expression}}
3038 @cindex @code{set} directive
3039 @cindex symbol value, setting
3040 This directive sets the value of @var{symbol} to @var{expression}. This
3041 will change @var{symbol}'s value and type to conform to
3042 @var{expression}. If @var{symbol} was flagged as external, it remains
3043 flagged. (@xref{Symbol Attributes}.)
3045 You may @code{.set} a symbol many times in the same assembly.
3046 If the expression's section is unknowable during pass 1, a second
3047 pass over the source program will be forced. The second pass is
3048 currently not implemented. @code{_AS__} will abort with an error
3049 message if one is required.
3051 If you @code{.set} a global symbol, the value stored in the object
3052 file is the last value stored into it.
3055 @section @code{.short @var{expressions}}
3057 @cindex @code{short} directive
3058 _if__(_GENERIC__ || _W16__)
3059 @code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
3061 In some configurations, however, @code{.short} and @code{.word} generate
3062 numbers of different lengths; @pxref{_MACH_DEP__}.
3064 _fi__(_GENERIC__|| _W16__)
3065 _if__((!_GENERIC__) && _W32__)
3066 This expects zero or more @var{expressions}, and emits
3067 a 16 bit number for each.
3068 _fi__((!_GENERIC__) && _W32__)
3071 @section @code{.single @var{flonums}}
3073 @cindex @code{single} directive
3074 @cindex floating point numbers (single)
3075 This directive assembles zero or more flonums, separated by commas. It
3076 has the same effect as @code{.float}.
3078 The exact kind of floating point numbers emitted depends on how
3079 @code{_AS__} is configured. @xref{_MACH_DEP__}.
3081 _if__((!_GENERIC__) && _IEEEFLOAT__)
3082 On the _HOST__ family, @code{.single} emits 32-bit floating point
3083 numbers in @sc{ieee} format.
3084 _fi__((!_GENERIC__) && _IEEEFLOAT__)
3086 _if__(_COFF__||_BOUT__)
3088 @section @code{.size}
3090 @cindex @code{size} directive
3091 This directive is generated by compilers to include auxiliary debugging
3092 information in the symbol table. It is only permitted inside
3093 @code{.def}/@code{.endef} pairs.
3096 @samp{.size} is only meaningful when generating COFF format output; when
3097 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3100 _fi__(_COFF__||_BOUT__)
3103 _if__(_GENERIC__ || !_A29K__)
3104 @section @code{.space @var{size} , @var{fill}}
3106 @cindex @code{space} directive
3107 @cindex filling memory
3108 This directive emits @var{size} bytes, each of value @var{fill}. Both
3109 @var{size} and @var{fill} are absolute expressions. If the comma
3110 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3111 _fi__(_GENERIC__ || !_A29K__)
3115 @section @code{.space}
3116 @cindex @code{space} directive
3118 On the AMD 29K, this directive is ignored; it is accepted for
3119 compatibility with other AMD 29K assemblers.
3122 @emph{Warning:} In other versions of the GNU assembler, the directive
3123 @code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}.
3127 _if__(_GENERIC__||!_H8__)
3128 _if__(_AOUT__||_BOUT__||_COFF__)
3130 @section @code{.stabd, .stabn, .stabs}
3132 @cindex symbolic debuggers, information for
3133 @cindex @code{stab@var{x}} directives
3134 There are three directives that begin @samp{.stab}.
3135 All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
3136 The symbols are not entered in the @code{_AS__} hash table: they
3137 cannot be referenced elsewhere in the source file.
3138 Up to five fields are required:
3141 This is the symbol's name. It may contain any character except @samp{\000},
3142 so is more general than ordinary symbol names. Some debuggers used to
3143 code arbitrarily complex structures into symbol names using this field.
3145 An absolute expression. The symbol's type is set to the low 8
3146 bits of this expression.
3147 Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on
3150 An absolute expression.
3151 The symbol's ``other'' attribute is set to the low 8 bits of this expression.
3153 An absolute expression.
3154 The symbol's descriptor is set to the low 16 bits of this expression.
3156 An absolute expression which becomes the symbol's value.
3159 If a warning is detected while reading a @code{.stabd}, @code{.stabn},
3160 or @code{.stabs} statement, the symbol has probably already been created
3161 and you will get a half-formed symbol in your object file. This is
3162 compatible with earlier assemblers!
3165 @cindex @code{stabd} directive
3166 @item .stabd @var{type} , @var{other} , @var{desc}
3168 The ``name'' of the symbol generated is not even an empty string.
3169 It is a null pointer, for compatibility. Older assemblers used a
3170 null pointer so they didn't waste space in object files with empty
3173 The symbol's value is set to the location counter,
3174 relocatably. When your program is linked, the value of this symbol
3175 will be where the location counter was when the @code{.stabd} was
3178 @item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
3179 @cindex @code{stabn} directive
3180 The name of the symbol is set to the empty string @code{""}.
3182 @item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
3183 @cindex @code{stabs} directive
3184 All five fields are specified.
3186 _fi__(_AOUT__||_BOUT__||_COFF__)
3187 _fi__(_GENERIC__||!_H8__)
3189 _if__(_COFF__||_BOUT__)
3191 @section @code{.tag @var{structname}}
3193 @cindex COFF structure debugging
3194 @cindex structure debugging, COFF
3195 @cindex @code{tag} directive
3196 This directive is generated by compilers to include auxiliary debugging
3197 information in the symbol table. It is only permitted inside
3198 @code{.def}/@code{.endef} pairs. Tags are used to link structure
3199 definitions in the symbol table with instances of those structures.
3202 @samp{.tag} is only used when generating COFF format output; when
3203 @code{_AS__} is generating @code{b.out}, it accepts this directive but
3206 _fi__(_COFF__||_BOUT__)
3209 @section @code{.text @var{subsection}}
3211 @cindex @code{text} directive
3212 Tells @code{_AS__} to assemble the following statements onto the end of
3213 the text subsection numbered @var{subsection}, which is an absolute
3214 expression. If @var{subsection} is omitted, subsection number zero
3218 @section @code{.title "@var{heading}"}
3220 @cindex @code{title} directive
3221 @cindex listing control: title line
3222 Use @var{heading} as the title (second line, immediately after the
3223 source file name and pagenumber) when generating assembly listings.
3225 This directive affects subsequent pages, as well as the current page if
3226 it appears within ten lines of the top of a page.
3228 _if__(_COFF__||_BOUT__)
3230 @section @code{.type @var{int}}
3232 @cindex COFF symbol type
3233 @cindex symbol type, COFF
3234 @cindex @code{type} directive
3235 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3236 records the integer @var{int} as the type attribute of a symbol table entry.
3239 @samp{.type} is associated only with COFF format output; when
3240 @code{_AS__} is configured for @code{b.out} output, it accepts this
3241 directive but ignores it.
3243 _fi__(_COFF__||_BOUT__)
3245 _if__(_COFF__||_BOUT__)
3247 @section @code{.val @var{addr}}
3249 @cindex @code{val} directive
3250 @cindex COFF value attribute
3251 @cindex value attribute, COFF
3252 This directive, permitted only within @code{.def}/@code{.endef} pairs,
3253 records the address @var{addr} as the value attribute of a symbol table
3257 @samp{.val} is used only for COFF output; when @code{_AS__} is
3258 configured for @code{b.out}, it accepts this directive but ignores it.
3260 _fi__(_COFF__||_BOUT__)
3263 @section @code{.word @var{expressions}}
3265 @cindex @code{word} directive
3266 This directive expects zero or more @var{expressions}, of any section,
3267 separated by commas.
3268 _if__((!_GENERIC__) && _W32__)
3269 For each expression, @code{_AS__} emits a 32-bit number.
3270 _fi__((!_GENERIC__) && _W32__)
3271 _if__((!_GENERIC__) && _W16__)
3272 For each expression, @code{_AS__} emits a 16-bit number.
3273 _fi__((!_GENERIC__) && _W16__)
3276 The size of the number emitted, and its byte order,
3277 depends on what kind of computer will run the program.
3280 @c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
3281 @c happen---32-bit addressability, period; no long/short jumps.
3282 _if__(_GENERIC__ || _DIFFTABKLUG__)
3283 @cindex difference tables altered
3284 @cindex altered difference tables
3286 @emph{Warning: Special Treatment to support Compilers}
3290 Machines with a 32-bit address space, but that do less than 32-bit
3291 addressing, require the following special treatment. If the machine of
3292 interest to you does 32-bit addressing (or doesn't require it;
3293 @pxref{_MACH_DEP__}), you can ignore this issue.
3296 In order to assemble compiler output into something that will work,
3297 @code{_AS__} will occasionlly do strange things to @samp{.word} directives.
3298 Directives of the form @samp{.word sym1-sym2} are often emitted by
3299 compilers as part of jump tables. Therefore, when @code{_AS__} assembles a
3300 directive of the form @samp{.word sym1-sym2}, and the difference between
3301 @code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will
3302 create a @dfn{secondary jump table}, immediately before the next label.
3303 This secondary jump table will be preceded by a short-jump to the
3304 first byte after the secondary table. This short-jump prevents the flow
3305 of control from accidentally falling into the new table. Inside the
3306 table will be a long-jump to @code{sym2}. The original @samp{.word}
3307 will contain @code{sym1} minus the address of the long-jump to
3310 If there were several occurrences of @samp{.word sym1-sym2} before the
3311 secondary jump table, all of them will be adjusted. If there was a
3312 @samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
3313 long-jump to @code{sym4} will be included in the secondary jump table,
3314 and the @code{.word} directives will be adjusted to contain @code{sym3}
3315 minus the address of the long-jump to @code{sym4}; and so on, for as many
3316 entries in the original jump table as necessary.
3319 @emph{This feature may be disabled by compiling @code{_AS__} with the
3320 @samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
3321 assembly language programmers.
3323 _fi__(_GENERIC__ || _DIFFTABKLUG__)
3326 @section Deprecated Directives
3328 @cindex deprecated directives
3329 @cindex obsolescent directives
3330 One day these directives won't work.
3331 They are included for compatibility with older assemblers.
3340 @chapter Machine Dependent Features
3342 @cindex machine dependencies
3343 The machine instruction sets are (almost by definition) different on
3344 each machine where @code{_AS__} runs. Floating point representations
3345 vary as well, and @code{_AS__} often supports a few additional
3346 directives or command-line options for compatibility with other
3347 assemblers on a particular platform. Finally, some versions of
3348 @code{_AS__} support special pseudo-instructions for branch
3351 This chapter discusses most of these differences, though it does not
3352 include details on any machine's instruction set. For details on that
3353 subject, see the hardware manufacturer's manual.
3357 * Vax-Dependent:: VAX Dependent Features
3360 * AMD29K-Dependent:: AMD 29K Dependent Features
3363 * H8/300-Dependent:: Hitachi H8/300 Dependent Features
3366 * i960-Dependent:: Intel 80960 Dependent Features
3369 * M68K-Dependent:: M680x0 Dependent Features
3372 * Sparc-Dependent:: SPARC Dependent Features
3375 * Z8000-Dependent:: Z8000 Dependent Features
3378 * i386-Dependent:: 80386 Dependent Features
3387 _CHAPSEC__(0+_GENERIC__) VAX Dependent Features
3391 * Vax-Opts:: VAX Command-Line Options
3392 * VAX-float:: VAX Floating Point
3393 * VAX-directives:: Vax Machine Directives
3394 * VAX-opcodes:: VAX Opcodes
3395 * VAX-branch:: VAX Branch Improvement
3396 * VAX-operands:: VAX Operands
3397 * VAX-no:: Not Supported on VAX
3401 _CHAPSEC__(1+_GENERIC__) VAX Command-Line Options
3403 @cindex command-line options ignored, VAX
3404 @cindex VAX command-line options ignored
3405 The Vax version of @code{_AS__} accepts any of the following options,
3406 gives a warning message that the option was ignored and proceeds.
3407 These options are for compatibility with scripts designed for other
3408 people's assemblers.
3411 @item @kbd{-D} (Debug)
3412 @itemx @kbd{-S} (Symbol Table)
3413 @itemx @kbd{-T} (Token Trace)
3414 @cindex @code{-D}, ignored on VAX
3415 @cindex @code{-S}, ignored on VAX
3416 @cindex @code{-T}, ignored on VAX
3417 These are obsolete options used to debug old assemblers.
3419 @item @kbd{-d} (Displacement size for JUMPs)
3420 @cindex @code{-d}, VAX option
3421 This option expects a number following the @kbd{-d}. Like options
3422 that expect filenames, the number may immediately follow the
3423 @kbd{-d} (old standard) or constitute the whole of the command line
3424 argument that follows @kbd{-d} (GNU standard).
3426 @item @kbd{-V} (Virtualize Interpass Temporary File)
3427 @cindex @code{-V}, redundant on VAX
3428 Some other assemblers use a temporary file. This option
3429 commanded them to keep the information in active memory rather
3430 than in a disk file. @code{_AS__} always does this, so this
3431 option is redundant.
3433 @item @kbd{-J} (JUMPify Longer Branches)
3434 @cindex @code{-J}, ignored on VAX
3435 Many 32-bit computers permit a variety of branch instructions
3436 to do the same job. Some of these instructions are short (and
3437 fast) but have a limited range; others are long (and slow) but
3438 can branch anywhere in virtual memory. Often there are 3
3439 flavors of branch: short, medium and long. Some other
3440 assemblers would emit short and medium branches, unless told by
3441 this option to emit short and long branches.
3443 @item @kbd{-t} (Temporary File Directory)
3444 @cindex @code{-t}, ignored on VAX
3445 Some other assemblers may use a temporary file, and this option
3446 takes a filename being the directory to site the temporary
3447 file. @code{_AS__} does not use a temporary disk file, so this
3448 option makes no difference. @kbd{-t} needs exactly one
3452 @cindex VMS (VAX) options
3453 @cindex options for VAX/VMS
3454 @cindex VAX/VMS options
3455 @cindex @code{-h} option, VAX/VMS
3456 @cindex @code{-+} option, VAX/VMS
3457 @cindex Vax-11 C compatibility
3458 @cindex symbols with lowercase, VAX/VMS
3459 @c FIXME! look into "I think" below, correct if needed, delete.
3460 The Vax version of the assembler accepts two options when
3461 compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The
3462 @kbd{-h} option prevents @code{_AS__} from modifying the
3463 symbol-table entries for symbols that contain lowercase
3464 characters (I think). The @kbd{-+} option causes @code{_AS__} to
3465 print warning messages if the FILENAME part of the object file,
3466 or any symbol name is larger than 31 characters. The @kbd{-+}
3467 option also insertes some code following the @samp{_main}
3468 symbol so that the object file will be compatible with Vax-11
3472 _CHAPSEC__(1+_GENERIC__) VAX Floating Point
3474 @cindex VAX floating point
3475 @cindex floating point, VAX
3476 Conversion of flonums to floating point is correct, and
3477 compatible with previous assemblers. Rounding is
3478 towards zero if the remainder is exactly half the least significant bit.
3480 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
3483 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
3484 are rendered correctly. Again, rounding is towards zero in the
3487 @cindex @code{float} directive, VAX
3488 @cindex @code{double} directive, VAX
3489 The @code{.float} directive produces @code{f} format numbers.
3490 The @code{.double} directive produces @code{d} format numbers.
3492 @node VAX-directives
3493 _CHAPSEC__(1+_GENERIC__) Vax Machine Directives
3495 @cindex machine directives, VAX
3496 @cindex VAX machine directives
3497 The Vax version of the assembler supports four directives for
3498 generating Vax floating point constants. They are described in the
3501 @cindex wide floating point directives, VAX
3504 @cindex @code{dfloat} directive, VAX
3505 This expects zero or more flonums, separated by commas, and
3506 assembles Vax @code{d} format 64-bit floating point constants.
3509 @cindex @code{ffloat} directive, VAX
3510 This expects zero or more flonums, separated by commas, and
3511 assembles Vax @code{f} format 32-bit floating point constants.
3514 @cindex @code{gfloat} directive, VAX
3515 This expects zero or more flonums, separated by commas, and
3516 assembles Vax @code{g} format 64-bit floating point constants.
3519 @cindex @code{hfloat} directive, VAX
3520 This expects zero or more flonums, separated by commas, and
3521 assembles Vax @code{h} format 128-bit floating point constants.
3526 _CHAPSEC__(1+_GENERIC__) VAX Opcodes
3528 @cindex VAX opcode mnemonics
3529 @cindex opcode mnemonics, VAX
3530 @cindex mnemonics for opcodes, VAX
3531 All DEC mnemonics are supported. Beware that @code{case@dots{}}
3532 instructions have exactly 3 operands. The dispatch table that
3533 follows the @code{case@dots{}} instruction should be made with
3534 @code{.word} statements. This is compatible with all unix
3535 assemblers we know of.
3538 _CHAPSEC__(1+_GENERIC__) VAX Branch Improvement
3540 @cindex VAX branch improvement
3541 @cindex branch improvement, VAX
3542 @cindex pseudo-ops for branch, VAX
3543 Certain pseudo opcodes are permitted. They are for branch
3544 instructions. They expand to the shortest branch instruction that
3545 will reach the target. Generally these mnemonics are made by
3546 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
3547 This feature is included both for compatibility and to help
3548 compilers. If you don't need this feature, don't use these
3549 opcodes. Here are the mnemonics, and the code they can expand into.
3553 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
3555 @item (byte displacement)
3557 @item (word displacement)
3559 @item (long displacement)
3564 Unconditional branch.
3566 @item (byte displacement)
3568 @item (word displacement)
3570 @item (long displacement)
3574 @var{COND} may be any one of the conditional branches
3575 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
3576 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
3577 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
3578 @var{COND} may also be one of the bit tests
3579 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
3580 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
3581 @var{NOTCOND} is the opposite condition to @var{COND}.
3583 @item (byte displacement)
3584 @kbd{b@var{COND} @dots{}}
3585 @item (word displacement)
3586 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
3587 @item (long displacement)
3588 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
3591 @var{X} may be one of @code{b d f g h l w}.
3593 @item (word displacement)
3594 @kbd{@var{OPCODE} @dots{}}
3595 @item (long displacement)
3597 @var{OPCODE} @dots{}, foo ;
3604 @var{YYY} may be one of @code{lss leq}.
3606 @var{ZZZ} may be one of @code{geq gtr}.
3608 @item (byte displacement)
3609 @kbd{@var{OPCODE} @dots{}}
3610 @item (word displacement)
3612 @var{OPCODE} @dots{}, foo ;
3614 foo: brw @var{destination} ;
3617 @item (long displacement)
3619 @var{OPCODE} @dots{}, foo ;
3621 foo: jmp @var{destination} ;
3630 @item (byte displacement)
3631 @kbd{@var{OPCODE} @dots{}}
3632 @item (word displacement)
3634 @var{OPCODE} @dots{}, foo ;
3636 foo: brw @var{destination} ;
3639 @item (long displacement)
3641 @var{OPCODE} @dots{}, foo ;
3643 foo: jmp @var{destination} ;
3650 _CHAPSEC__(1+_GENERIC__) VAX Operands
3652 @cindex VAX operand notation
3653 @cindex operand notation, VAX
3654 @cindex immediate character, VAX
3655 @cindex VAX immediate character
3656 The immediate character is @samp{$} for Unix compatibility, not
3657 @samp{#} as DEC writes it.
3659 @cindex indirect character, VAX
3660 @cindex VAX indirect character
3661 The indirect character is @samp{*} for Unix compatibility, not
3662 @samp{@@} as DEC writes it.
3664 @cindex displacement sizing character, VAX
3665 @cindex VAX displacement sizing character
3666 The displacement sizing character is @samp{`} (an accent grave) for
3667 Unix compatibility, not @samp{^} as DEC writes it. The letter
3668 preceding @samp{`} may have either case. @samp{G} is not
3669 understood, but all other letters (@code{b i l s w}) are understood.
3671 @cindex register names, VAX
3672 @cindex VAX register names
3673 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
3674 pc}. Any case of letters will do.
3681 Any expression is permitted in an operand. Operands are comma
3684 @c There is some bug to do with recognizing expressions
3685 @c in operands, but I forget what it is. It is
3686 @c a syntax clash because () is used as an address mode
3687 @c and to encapsulate sub-expressions.
3690 _CHAPSEC__(1+_GENERIC__) Not Supported on VAX
3692 @cindex VAX bitfields not supported
3693 @cindex bitfields, not supported on VAX
3694 Vax bit fields can not be assembled with @code{_AS__}. Someone
3695 can add the required code if they really need it.
3700 @node AMD29K-Dependent
3702 _CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features
3704 @cindex AMD 29K support
3707 * AMD29K Options:: Options
3708 * AMD29K Syntax:: Syntax
3709 * AMD29K Floating Point:: Floating Point
3710 * AMD29K Directives:: AMD 29K Machine Directives
3711 * AMD29K Opcodes:: Opcodes
3714 @node AMD29K Options
3715 _CHAPSEC__(1+_GENERIC__) Options
3716 @cindex AMD 29K options (none)
3717 @cindex options for AMD29K (none)
3718 @code{_AS__} has no additional command-line options for the AMD
3722 _CHAPSEC__(1+_GENERIC__) Syntax
3724 * AMD29K-Chars:: Special Characters
3725 * AMD29K-Regs:: Register Names
3729 _CHAPSEC__(2+_GENERIC__) Special Characters
3731 @cindex line comment character, AMD 29K
3732 @cindex AMD 29K line comment character
3733 @samp{;} is the line comment character.
3735 @cindex line separator, AMD 29K
3736 @cindex AMD 29K line separator
3737 @cindex statement separator, AMD 29K
3738 @cindex AMD 29K statement separator
3739 @samp{@@} can be used instead of a newline to separate statements.
3741 @cindex identifiers, AMD 29K
3742 @cindex AMD 29K identifiers
3743 The character @samp{?} is permitted in identifiers (but may not begin
3747 _CHAPSEC__(2+_GENERIC__) Register Names
3749 @cindex AMD 29K register names
3750 @cindex register names, AMD 29K
3751 General-purpose registers are represented by predefined symbols of the
3752 form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}}
3753 (for local registers), where @var{nnn} represents a number between
3754 @code{0} and @code{127}, written with no leading zeros. The leading
3755 letters may be in either upper or lower case; for example, @samp{gr13}
3756 and @samp{LR7} are both valid register names.
3758 You may also refer to general-purpose registers by specifying the
3759 register number as the result of an expression (prefixed with @samp{%%}
3760 to flag the expression as a register number):
3765 ---where @var{expression} must be an absolute expression evaluating to a
3766 number between @code{0} and @code{255}. The range [0, 127] refers to
3767 global registers, and the range [128, 255] to local registers.
3769 @cindex special purpose registers, AMD 29K
3770 @cindex AMD 29K special purpose registers
3771 @cindex protected registers, AMD 29K
3772 @cindex AMD 29K protected registers
3773 In addition, @code{_AS__} understands the following protected
3774 special-purpose register names for the AMD 29K family:
3784 These unprotected special-purpose register names are also recognized:
3792 @node AMD29K Floating Point
3793 _CHAPSEC__(1+_GENERIC__) Floating Point
3795 @cindex floating point, AMD 29K (@sc{ieee})
3796 @cindex AMD 29K floating point (@sc{ieee})
3797 The AMD 29K family uses @sc{ieee} floating-point numbers.
3799 @node AMD29K Directives
3800 _CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives
3802 @cindex machine directives, AMD 29K
3803 @cindex AMD 29K machine directives
3805 @item .block @var{size} , @var{fill}
3806 @cindex @code{block} directive, AMD 29K
3807 This directive emits @var{size} bytes, each of value @var{fill}. Both
3808 @var{size} and @var{fill} are absolute expressions. If the comma
3809 and @var{fill} are omitted, @var{fill} is assumed to be zero.
3811 In other versions of the GNU assembler, this directive is called
3817 @cindex @code{cputype} directive, AMD 29K
3818 This directive is ignored; it is accepted for compatibility with other
3822 @cindex @code{file} directive, AMD 29K
3823 This directive is ignored; it is accepted for compatibility with other
3827 @emph{Warning:} in other versions of the GNU assembler, @code{.file} is
3828 used for the directive called @code{.app-file} in the AMD 29K support.
3832 @cindex @code{line} directive, AMD 29K
3833 This directive is ignored; it is accepted for compatibility with other
3837 @c since we're ignoring .lsym...
3838 @item .reg @var{symbol}, @var{expression}
3839 @cindex @code{reg} directive, AMD 29K
3840 @code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}.
3844 @cindex @code{sect} directive, AMD 29K
3845 This directive is ignored; it is accepted for compatibility with other
3848 @item .use @var{section name}
3849 @cindex @code{use} directive, AMD 29K
3850 Establishes the section and subsection for the following code;
3851 @var{section name} may be one of @code{.text}, @code{.data},
3852 @code{.data1}, or @code{.lit}. With one of the first three @var{section
3853 name} options, @samp{.use} is equivalent to the machine directive
3854 @var{section name}; the remaining case, @samp{.use .lit}, is the same as
3858 @node AMD29K Opcodes
3859 _CHAPSEC__(1+_GENERIC__) Opcodes
3861 @cindex AMD 29K opcodes
3862 @cindex opcodes for AMD 29K
3863 @code{_AS__} implements all the standard AMD 29K opcodes. No
3864 additional pseudo-instructions are needed on this family.
3866 For information on the 29K machine instruction set, see @cite{Am29000
3867 User's Manual}, Advanced Micro Devices, Inc.
3872 @node H8/300-Dependent
3874 _CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features
3876 @cindex H8/300 support
3878 * H8/300 Options:: Options
3879 * H8/300 Syntax:: Syntax
3880 * H8/300 Floating Point:: Floating Point
3881 * H8/300 Directives:: H8/300 Machine Directives
3882 * H8/300 Opcodes:: Opcodes
3885 @node H8/300 Options
3886 _CHAPSEC__(1+_GENERIC__) Options
3888 @cindex H8/300 options (none)
3889 @cindex options, H8/300 (none)
3890 @code{_AS__} has no additional command-line options for the Hitachi
3894 _CHAPSEC__(1+_GENERIC__) Syntax
3896 * H8/300-Chars:: Special Characters
3897 * H8/300-Regs:: Register Names
3898 * H8/300-Addressing:: Addressing Modes
3902 _CHAPSEC__(2+_GENERIC__) Special Characters
3904 @cindex line comment character, H8/300
3905 @cindex H8/300 line comment character
3906 @samp{;} is the line comment character.
3908 @cindex line separator, H8/300
3909 @cindex statement separator, H8/300
3910 @cindex H8/300 line separator
3911 @samp{$} can be used instead of a newline to separate statements.
3912 Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300.
3915 _CHAPSEC__(2+_GENERIC__) Register Names
3917 @cindex H8/300 registers
3918 @cindex registers, H8/300
3919 You can use predefined symbols of the form @samp{r@var{n}h} and
3920 @samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit
3921 general-purpose registers. @var{n} is a digit from @samp{0} to
3922 @samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid
3925 You can also use the eight predefined symbols @samp{r@var{n}} to refer
3926 to the H8/300 registers as 16-bit registers (you must use this form for
3929 The two control registers are called @code{pc} (program counter; a
3930 16-bit register) and @code{ccr} (condition code register; an 8-bit
3931 register). @code{r7} is used as the stack pointer, and can also be
3934 @node H8/300-Addressing
3935 _CHAPSEC__(2+_GENERIC__) Addressing Modes
3937 @cindex addressing modes, H8/300
3938 @cindex H8/300 addressing modes
3939 _AS__ understands the following addressing modes for the H8/300:
3947 @item @@(@var{d}, r@var{n})
3948 @itemx @@(@var{d}:16, r@var{n})
3949 Register indirect: 16-bit displacement @var{d} from register @var{n}.
3950 (You may specify the @samp{:16} for clarity if you wish, but it is not
3951 required and has no effect.)
3954 Register indirect with post-increment
3957 Register indirect with pre-decrement
3959 @item @code{@@}@var{aa}
3960 @itemx @code{@@}@var{aa}:8
3961 @itemx @code{@@}@var{aa}:16
3962 Absolute address @code{aa}. You may specify the @samp{:8} or @samp{:16}
3963 for clarity, if you wish; but @code{_AS__} neither requires this nor
3964 uses it---the address size required is taken from context.
3969 Immediate data @var{xx}. You may specify the @samp{:8} or @samp{:16}
3970 for clarity, if you wish; but @code{_AS__} neither requires this nor
3971 uses it---the data size required is taken from context.
3973 @item @code{@@}@code{@@}@var{aa}
3974 @itemx @code{@@}@code{@@}@var{aa}:8
3975 Memory indirect. You may specify the @samp{:8} for clarity, if you
3976 wish; but @code{_AS__} neither requires this nor uses it.
3979 @node H8/300 Floating Point
3980 _CHAPSEC__(1+_GENERIC__) Floating Point
3982 @cindex floating point, H8/300 (@sc{ieee})
3983 @cindex H8/300 floating point (@sc{ieee})
3984 The H8/300 family uses @sc{ieee} floating-point numbers.
3986 @node H8/300 Directives
3987 _CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives
3989 @cindex H8/300 machine directives (none)
3990 @cindex machine directives, H8/300 (none)
3991 @cindex @code{word} directive, H8/300
3992 @cindex @code{int} directive, H8/300
3993 @code{_AS__} has no machine-dependent directives for the H8/300.
3994 However, on this platform the @samp{.int} and @samp{.word} directives
3995 generate 16-bit numbers.
3997 @node H8/300 Opcodes
3998 _CHAPSEC__(1+_GENERIC__) Opcodes
4000 @cindex H8/300 opcode summary
4001 @cindex opcode summary, H8/300
4002 @cindex mnemonics, H8/300
4003 @cindex instruction summary, H8/300
4004 For detailed information on the H8/300 machine instruction set, see
4005 @cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025).
4007 @code{_AS__} implements all the standard H8/300 opcodes. No additional
4008 pseudo-instructions are needed on this family.
4010 The following table summarizes the opcodes and their arguments:
4011 @c kluge due to lack of group outside example
4015 Rs @r{source register}
4016 Rd @r{destination register}
4017 imm @r{immediate data}
4018 x:3 @r{a bit (as a number between 0 and 7)}
4019 d:8 @r{eight bit displacement from @code{pc}}
4020 d:16 @r{sixteen bit displacement from @code{Rs}}
4022 add.b Rs,Rd biand #x:3,Rd
4023 add.b #imm:8,Rd biand #x:3,@@Rd
4024 add.w Rs,Rd biand #x:3,@@aa:8
4025 adds #1,Rd bild #x:3,Rd
4026 adds #2,Rd bild #x:3,@@Rd
4027 addx #imm:8,Rd bild #x:3,@@aa:8
4028 addx Rs,Rd bior #x:3,Rd
4029 and #imm:8,Rd bior #x:3,@@Rd
4030 and Rs,Rd bior #x:3,@@aa:8
4031 andc #imm:8,ccr bist #x:3,Rd
4032 band #x:3,Rd bist #x:3,@@Rd
4033 band #x:3,@@Rd bist #x:3,@@aa:8
4034 bra d:8 bixor #x:3,Rd
4035 bt d:8 bixor #x:3,@@Rd
4036 brn d:8 bixor #x:3,@@aa:8
4038 bhi d:8 bld #x:3,@@Rd
4039 bls d:8 bld #x:3,@@aa:8
4040 bcc d:8 bnot #x:3,Rd
4041 bhs d:8 bnot #x:3,@@Rd
4042 bcs d:8 bnot #x:3,@@aa:8
4044 bne d:8 bnot Rs,@@Rd
4045 beq d:8 bnot Rs,@@aa:8
4047 bvs d:8 bor #x:3,@@Rd
4048 bpl d:8 bor #x:3,@@aa:8
4049 bmi d:8 bset #x:3,@@Rd
4050 bge d:8 bset #x:3,@@aa:8
4052 bgt d:8 bset Rs,@@Rd
4053 ble d:8 bset Rs,@@aa:8
4054 bclr #x:3,Rd bsr d:8
4055 bclr #x:3,@@Rd bst #x:3,Rd
4056 bclr #x:3,@@aa:8 bst #x:3,@@Rd
4057 bclr Rs,Rd bst #x:3,@@aa:8
4058 bclr Rs,@@Rd btst #x:3,Rd
4061 btst #x:3,@@Rd mov.w @@(d:16, Rs),Rd
4062 btst #x:3,@@aa:8 mov.w @@Rs+,Rd
4063 btst Rs,Rd mov.w @@aa:16,Rd
4064 btst Rs,@@Rd mov.w Rs,@@Rd
4065 btst Rs,@@aa:8 mov.w Rs,@@(d:16, Rd)
4066 bxor #x:3,Rd mov.w Rs,@@-Rd
4067 bxor #x:3,@@Rd mov.w Rs,@@aa:16
4068 bxor #x:3,@@aa:8 movfpe @@aa:16,Rd
4069 cmp.b #imm:8,Rd movtpe Rs,@@aa:16
4070 cmp.b Rs,Rd mulxu Rs,Rd
4075 divxu Rs,Rd or Rs,Rd
4076 eepmov orc #imm:8,ccr
4082 jsr @@aa:16 rotxr Rs
4087 mov.b #imm:8,Rd shll Rs
4088 mov.b @@Rs,Rd shlr Rs
4089 mov.b @@(d:16, Rs),Rd sleep
4090 mov.b @@Rs+,Rd stc ccr,Rd
4091 mov.b @@aa:16,Rd sub.b Rs,Rd
4092 mov.b @@aa:8,Rd sub.w Rs,Rd
4093 mov.b Rs,@@Rd subs #1,Rd
4094 mov.b Rs,@@(d:16, Rd) subs #2,Rd
4095 mov.b Rs,@@-Rd subx #imm:8,Rd
4096 mov.b Rs,@@aa:16 subx Rs,Rd
4097 mov.b Rs,@@aa:8 xor #imm:8,Rd
4098 mov.w Rs,Rd xor Rs,Rd
4099 mov.w #imm:16,Rd xorc #imm:8,ccr
4104 @cindex size suffixes, H8/300
4105 @cindex H8/300 size suffixes
4106 Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov},
4107 @code{sub}) are defined with variants using the suffixes @samp{.b} and
4108 @samp{.w} to specify the size of a memory operand. @code{_AS__}
4109 supports these suffixes, but does not require them; since one of the
4110 operands is always a register, @code{_AS__} can deduce the correct size.
4112 For example, since @code{r0} refers to a 16-bit register,
4115 @exdent is equivalent to
4119 If you use the size suffixes, @code{_AS__} will issue a warning if
4120 there's a mismatch between the suffix and the register size.
4125 @node i960-Dependent
4127 _CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features
4129 @cindex i960 support
4131 * Options-i960:: i960 Command-line Options
4132 * Floating Point-i960:: Floating Point
4133 * Directives-i960:: i960 Machine Directives
4134 * Opcodes for i960:: i960 Opcodes
4137 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
4138 @c long as they're not turned on for other machines than 960.
4142 _CHAPSEC__(1+_GENERIC__) i960 Command-line Options
4144 @cindex i960 options
4145 @cindex options, i960
4148 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
4149 @cindex i960 architecture options
4150 @cindex architecture options, i960
4151 @cindex @code{-A} options, i960
4152 Select the 80960 architecture. Instructions or features not supported
4153 by the selected architecture cause fatal errors.
4155 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
4156 @samp{-AMC}. Synonyms are provided for compatibility with other tools.
4158 If none of these options is specified, @code{_AS__} will generate code for any
4159 instruction or feature that is supported by @emph{some} version of the
4160 960 (even if this means mixing architectures!). In principle,
4161 @code{_AS__} will attempt to deduce the minimal sufficient processor
4162 type if none is specified; depending on the object code format, the
4163 processor type may be recorded in the object file. If it is critical
4164 that the @code{_AS__} output match a specific architecture, specify that
4165 architecture explicitly.
4168 @cindex @code{-b} option, i960
4169 @cindex branch recording, i960
4170 @cindex i960 branch recording
4171 Add code to collect information about conditional branches taken, for
4172 later optimization using branch prediction bits. (The conditional branch
4173 instructions have branch prediction bits in the CA, CB, and CC
4174 architectures.) If @var{BR} represents a conditional branch instruction,
4175 the following represents the code generated by the assembler when
4176 @samp{-b} is specified:
4179 call @var{increment routine}
4180 .word 0 # pre-counter
4182 call @var{increment routine}
4183 .word 0 # post-counter
4186 The counter following a branch records the number of times that branch
4187 was @emph{not} taken; the differenc between the two counters is the
4188 number of times the branch @emph{was} taken.
4190 @cindex @code{gbr960}, i960 postprocessor
4191 @cindex branch statistics table, i960
4192 A table of every such @code{Label} is also generated, so that the
4193 external postprocessor @code{gbr960} (supplied by Intel) can locate all
4194 the counters. This table is always labelled @samp{__BRANCH_TABLE__};
4195 this is a local symbol to permit collecting statistics for many separate
4196 object files. The table is word aligned, and begins with a two-word
4197 header. The first word, initialized to 0, is used in maintaining linked
4198 lists of branch tables. The second word is a count of the number of
4199 entries in the table, which follow immediately: each is a word, pointing
4200 to one of the labels illustrated above.
4204 @c END TEXI2ROFF-KILL
4206 +------------+------------+------------+ ... +------------+
4208 | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
4210 +------------+------------+------------+ ... +------------+
4212 __BRANCH_TABLE__ layout
4218 \line{\leftskip=0pt\hskip\tableindent
4219 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
4220 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
4221 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
4223 @c END TEXI2ROFF-KILL
4225 The first word of the header is used to locate multiple branch tables,
4226 since each object file may contain one. Normally the links are
4227 maintained with a call to an initialization routine, placed at the
4228 beginning of each function in the file. The GNU C compiler will
4229 generate these calls automatically when you give it a @samp{-b} option.
4230 For further details, see the documentation of @samp{gbr960}.
4233 @cindex @code{-norelax} option, i960
4234 Normally, Compare-and-Branch instructions with targets that require
4235 displacements greater than 13 bits (or that have external targets) are
4236 replaced with the corresponding compare (or @samp{chkbit}) and branch
4237 instructions. You can use the @samp{-norelax} option to specify that
4238 @code{_AS__} should generate errors instead, if the target displacement
4239 is larger than 13 bits.
4241 This option does not affect the Compare-and-Jump instructions; the code
4242 emitted for them is @emph{always} adjusted when necessary (depending on
4243 displacement size), regardless of whether you use @samp{-norelax}.
4246 @node Floating Point-i960
4247 _CHAPSEC__(1+_GENERIC__) Floating Point
4249 @cindex floating point, i960 (@sc{ieee})
4250 @cindex i960 floating point (@sc{ieee})
4251 @code{_AS__} generates @sc{ieee} floating-point numbers for the directives
4252 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
4254 @node Directives-i960
4255 _CHAPSEC__(1+_GENERIC__) i960 Machine Directives
4257 @cindex machine directives, i960
4258 @cindex i960 machine directives
4261 @cindex @code{bss} directive, i960
4262 @item .bss @var{symbol}, @var{length}, @var{align}
4263 Reserve @var{length} bytes in the bss section for a local @var{symbol},
4264 aligned to the power of two specified by @var{align}. @var{length} and
4265 @var{align} must be positive absolute expressions. This directive
4266 differs from @samp{.lcomm} only in that it permits you to specify
4267 an alignment. @xref{Lcomm,,@code{.lcomm}}.
4271 @item .extended @var{flonums}
4272 @cindex @code{extended} directive, i960
4273 @code{.extended} expects zero or more flonums, separated by commas; for
4274 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
4275 floating-point number.
4277 @item .leafproc @var{call-lab}, @var{bal-lab}
4278 @cindex @code{leafproc} directive, i960
4279 You can use the @samp{.leafproc} directive in conjunction with the
4280 optimized @code{callj} instruction to enable faster calls of leaf
4281 procedures. If a procedure is known to call no other procedures, you
4282 may define an entry point that skips procedure prolog code (and that does
4283 not depend on system-supplied saved context), and declare it as the
4284 @var{bal-lab} using @samp{.leafproc}. If the procedure also has an
4285 entry point that goes through the normal prolog, you can specify that
4286 entry point as @var{call-lab}.
4288 A @samp{.leafproc} declaration is meant for use in conjunction with the
4289 optimized call instruction @samp{callj}; the directive records the data
4290 needed later to choose between converting the @samp{callj} into a
4291 @code{bal} or a @code{call}.
4293 @var{call-lab} is optional; if only one argument is present, or if the
4294 two arguments are identical, the single argument is assumed to be the
4295 @code{bal} entry point.
4297 @item .sysproc @var{name}, @var{index}
4298 @cindex @code{sysproc} directive, i960
4299 The @samp{.sysproc} directive defines a name for a system procedure.
4300 After you define it using @samp{.sysproc}, you can use @var{name} to
4301 refer to the system procedure identified by @var{index} when calling
4302 procedures with the optimized call instruction @samp{callj}.
4304 Both arguments are required; @var{index} must be between 0 and 31
4308 @node Opcodes for i960
4309 _CHAPSEC__(1+_GENERIC__) i960 Opcodes
4311 @cindex opcodes, i960
4312 @cindex i960 opcodes
4313 All Intel 960 machine instructions are supported;
4314 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
4315 selecting the instruction subset for a particular 960
4316 architecture.@refill
4318 Some opcodes are processed beyond simply emitting a single corresponding
4319 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
4320 instructions with target displacements larger than 13 bits.
4323 * callj-i960:: @code{callj}
4324 * Compare-and-branch-i960:: Compare-and-Branch
4328 _CHAPSEC__(2+_GENERIC__) @code{callj}
4330 @cindex @code{callj}, i960 pseudo-opcode
4331 @cindex i960 @code{callj} pseudo-opcode
4332 You can write @code{callj} to have the assembler or the linker determine
4333 the most appropriate form of subroutine call: @samp{call},
4334 @samp{bal}, or @samp{calls}. If the assembly source contains
4335 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
4336 defining the operand---then @code{_AS__} will translate the
4337 @code{callj}; if not, it will simply emit the @code{callj}, leaving it
4338 for the linker to resolve.
4340 @node Compare-and-branch-i960
4341 _CHAPSEC__(2+_GENERIC__) Compare-and-Branch
4343 @cindex i960 compare/branch instructions
4344 @cindex compare/branch instructions, i960
4345 The 960 architectures provide combined Compare-and-Branch instructions
4346 that permit you to store the branch target in the lower 13 bits of the
4347 instruction word itself. However, if you specify a branch target far
4348 enough away that its address won't fit in 13 bits, the assembler can
4349 either issue an error, or convert your Compare-and-Branch instruction
4350 into separate instructions to do the compare and the branch.
4352 @cindex compare and jump expansions, i960
4353 @cindex i960 compare and jump expansions
4354 Whether @code{_AS__} gives an error or expands the instruction depends
4355 on two choices you can make: whether you use the @samp{-norelax} option,
4356 and whether you use a ``Compare and Branch'' instruction or a ``Compare
4357 and Jump'' instruction. The ``Jump'' instructions are @emph{always}
4358 expanded if necessary; the ``Branch'' instructions are expanded when
4359 necessary @emph{unless} you specify @code{-norelax}---in which case
4360 @code{_AS__} gives an error instead.
4362 These are the Compare-and-Branch instructions, their ``Jump'' variants,
4363 and the instruction pairs they may expand into:
4367 @c END TEXI2ROFF-KILL
4370 Branch Jump Expanded to
4371 ------ ------ ------------
4374 cmpibe cmpije cmpi; be
4375 cmpibg cmpijg cmpi; bg
4376 cmpibge cmpijge cmpi; bge
4377 cmpibl cmpijl cmpi; bl
4378 cmpible cmpijle cmpi; ble
4379 cmpibno cmpijno cmpi; bno
4380 cmpibne cmpijne cmpi; bne
4381 cmpibo cmpijo cmpi; bo
4382 cmpobe cmpoje cmpo; be
4383 cmpobg cmpojg cmpo; bg
4384 cmpobge cmpojge cmpo; bge
4385 cmpobl cmpojl cmpo; bl
4386 cmpoble cmpojle cmpo; ble
4387 cmpobne cmpojne cmpo; bne
4393 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
4394 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
4395 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
4396 bbc& & chkbit; bno\cr
4397 bbs& & chkbit; bo\cr
4398 cmpibe& cmpije& cmpi; be\cr
4399 cmpibg& cmpijg& cmpi; bg\cr
4400 cmpibge& cmpijge& cmpi; bge\cr
4401 cmpibl& cmpijl& cmpi; bl\cr
4402 cmpible& cmpijle& cmpi; ble\cr
4403 cmpibno& cmpijno& cmpi; bno\cr
4404 cmpibne& cmpijne& cmpi; bne\cr
4405 cmpibo& cmpijo& cmpi; bo\cr
4406 cmpobe& cmpoje& cmpo; be\cr
4407 cmpobg& cmpojg& cmpo; bg\cr
4408 cmpobge& cmpojge& cmpo; bge\cr
4409 cmpobl& cmpojl& cmpo; bl\cr
4410 cmpoble& cmpojle& cmpo; ble\cr
4411 cmpobne& cmpojne& cmpo; bne\cr}
4413 @c END TEXI2ROFF-KILL
4418 @node M68K-Dependent
4420 _CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features
4422 @cindex M680x0 support
4424 * M68K-Opts:: M680x0 Options
4425 * M68K-Syntax:: Syntax
4426 * M68K-Float:: Floating Point
4427 * M68K-Directives:: 680x0 Machine Directives
4428 * M68K-opcodes:: Opcodes
4432 _CHAPSEC__(1+_GENERIC__) M680x0 Options
4434 @cindex options, M680x0
4435 @cindex M680x0 options
4436 The Motorola 680x0 version of @code{_AS__} has two machine dependent options.
4437 One shortens undefined references from 32 to 16 bits, while the
4438 other is used to tell @code{_AS__} what kind of machine it is
4441 @cindex @code{-l} option, M680x0
4442 You can use the @kbd{-l} option to shorten the size of references to
4443 undefined symbols. If the @kbd{-l} option is not given, references to
4444 undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__}
4445 cannot know where these symbols will end up, @code{_AS__} can only allocate
4446 space for the linker to fill in later. Since @code{_AS__} doesn't know how
4447 far away these symbols will be, it allocates as much space as it can.)
4448 If this option is given, the references will only be one word wide (16
4449 bits). This may be useful if you want the object file to be as small as
4450 possible, and you know that the relevant symbols will be less than 17
4453 @cindex @code{-m68000} and related options
4454 @cindex architecture options, M680x0
4455 @cindex M680x0 architecture options
4456 The 680x0 version of @code{_AS__} is most frequently used to assemble
4457 programs for the Motorola MC68020 microprocessor. Occasionally it is
4458 used to assemble programs for the mostly similar, but slightly different
4459 MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options
4460 @samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010},
4461 @samp{-m68020}, and @samp{-mc68020} to tell it what processor is the
4465 _CHAPSEC__(1+_GENERIC__) Syntax
4467 @cindex M680x0 syntax
4468 @cindex syntax, M680x0
4469 @cindex M680x0 size modifiers
4470 @cindex size modifiers, M680x0
4471 The 680x0 version of @code{_AS__} uses syntax similar to the Sun assembler.
4472 Size modifiers are appended directly to the end of the opcode without an
4473 intervening period. For example, write @samp{movl} rather than
4477 If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow
4478 Sun-style local labels of the form @samp{1$} through @samp{$9}.
4481 In the following table @dfn{apc} stands for any of the address
4482 registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the
4483 Program Counter (@samp{pc}), or the zero-address relative to the
4484 program counter (@samp{zpc}).
4486 @cindex M680x0 addressing modes
4487 @cindex addressing modes, M680x0
4488 The following addressing modes are understood:
4491 @samp{#@var{digits}}
4494 @samp{d0} through @samp{d7}
4496 @item Address Register
4497 @samp{a0} through @samp{a7}
4499 @item Address Register Indirect
4500 @samp{a0@@} through @samp{a7@@}
4502 @item Address Register Postincrement
4503 @samp{a0@@+} through @samp{a7@@+}
4505 @item Address Register Predecrement
4506 @samp{a0@@-} through @samp{a7@@-}
4508 @item Indirect Plus Offset
4509 @samp{@var{apc}@@(@var{digits})}
4512 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4514 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})}
4517 @samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})}
4519 or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})}
4522 @samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4524 or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})}
4526 @item Memory Indirect
4527 @samp{@var{apc}@@(@var{digits})@@(@var{digits})}
4530 @samp{@var{symbol}}, or @samp{@var{digits}}
4532 @c pesch@cygnus.com: gnu, rich concur the following needs careful
4533 @c research before documenting.
4534 , or either of the above followed
4535 by @samp{:b}, @samp{:w}, or @samp{:l}.
4540 _CHAPSEC__(1+_GENERIC__) Floating Point
4542 @cindex floating point, M680x0
4543 @cindex M680x0 floating point
4544 @c FIXME is this "not too well tested" crud STILL true?
4545 The floating point code is not too well tested, and may have
4548 Packed decimal (P) format floating literals are not supported.
4549 Feel free to add the code!
4551 The floating point formats generated by directives are these.
4555 @cindex @code{float} directive, M680x0
4556 @code{Single} precision floating point constants.
4559 @cindex @code{double} directive, M680x0
4560 @code{Double} precision floating point constants.
4563 There is no directive to produce regions of memory holding
4564 extended precision numbers, however they can be used as
4565 immediate operands to floating-point instructions. Adding a
4566 directive to create extended precision numbers would not be
4567 hard, but it has not yet seemed necessary.
4569 @node M68K-Directives
4570 _CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives
4572 @cindex M680x0 directives
4573 @cindex directives, M680x0
4574 In order to be compatible with the Sun assembler the 680x0 assembler
4575 understands the following directives.
4579 @cindex @code{data1} directive, M680x0
4580 This directive is identical to a @code{.data 1} directive.
4583 @cindex @code{data2} directive, M680x0
4584 This directive is identical to a @code{.data 2} directive.
4587 @cindex @code{even} directive, M680x0
4588 This directive is identical to a @code{.align 1} directive.
4589 @c Is this true? does it work???
4592 @cindex @code{skip} directive, M680x0
4593 This directive is identical to a @code{.space} directive.
4597 _CHAPSEC__(1+_GENERIC__) Opcodes
4599 @cindex M680x0 opcodes
4600 @cindex opcodes, M680x0
4601 @cindex instruction set, M680x0
4602 @c pesch@cygnus.com: I don't see any point in the following
4603 @c paragraph. Bugs are bugs; how does saying this
4606 Danger: Several bugs have been found in the opcode table (and
4607 fixed). More bugs may exist. Be careful when using obscure
4612 * M68K-Branch:: Branch Improvement
4613 * M68K-Chars:: Special Characters
4617 _CHAPSEC__(2+_GENERIC__) Branch Improvement
4619 @cindex pseudo-opcodes, M680x0
4620 @cindex M680x0 pseudo-opcodes
4621 @cindex branch improvement, M680x0
4622 @cindex M680x0 branch improvement
4623 Certain pseudo opcodes are permitted for branch instructions.
4624 They expand to the shortest branch instruction that will reach the
4625 target. Generally these mnemonics are made by substituting @samp{j} for
4626 @samp{b} at the start of a Motorola mnemonic.
4628 The following table summarizes the pseudo-operations. A @code{*} flags
4629 cases that are more fully described after the table:
4633 +-------------------------------------------------
4635 Pseudo-Op |BYTE WORD LONG LONG non-PC relative
4636 +-------------------------------------------------
4637 jbsr |bsrs bsr bsrl jsr jsr
4638 jra |bras bra bral jmp jmp
4639 * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp
4640 * dbXX |dbXX dbXX dbXX; bra; jmpl
4641 * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp
4644 NX: negative of condition XX
4647 @center @code{*}---see full description below
4652 These are the simplest jump pseudo-operations; they always map to one
4653 particular machine instruction, depending on the displacement to the
4657 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
4658 where @var{XX} is a conditional branch or condition-code test. The full
4659 list of pseudo-ops in this family is:
4661 jhi jls jcc jcs jne jeq jvc
4662 jvs jpl jmi jge jlt jgt jle
4665 For the cases of non-PC relative displacements and long displacements on
4666 the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of
4667 @var{NX}, the opposite condition to @var{XX}. For example, for the
4668 non-PC relative case:
4680 The full family of pseudo-operations covered here is
4682 dbhi dbls dbcc dbcs dbne dbeq dbvc
4683 dbvs dbpl dbmi dbge dblt dbgt dble
4687 Other than for word and byte displacements, when the source reads
4688 @samp{db@var{XX} foo}, @code{_AS__} will emit
4697 This family includes
4699 fjne fjeq fjge fjlt fjgt fjle fjf
4700 fjt fjgl fjgle fjnge fjngl fjngle fjngt
4701 fjnle fjnlt fjoge fjogl fjogt fjole fjolt
4702 fjor fjseq fjsf fjsne fjst fjueq fjuge
4703 fjugt fjule fjult fjun
4706 For branch targets that are not PC relative, @code{_AS__} emits
4712 when it encounters @samp{fj@var{XX} foo}.
4717 _CHAPSEC__(2+_GENERIC__) Special Characters
4719 @cindex special characters, M680x0
4720 @cindex M680x0 immediate character
4721 @cindex immediate character, M680x0
4722 @cindex M680x0 line comment character
4723 @cindex line comment character, M680x0
4724 @cindex comments, M680x0
4725 The immediate character is @samp{#} for Sun compatibility. The
4726 line-comment character is @samp{|}. If a @samp{#} appears at the
4727 beginning of a line, it is treated as a comment unless it looks like
4728 @samp{# line file}, in which case it is treated normally.
4732 @c pesch@cygnus.com: conditionalize on something other than 0 when filled in.
4735 The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to
4736 specify thiat it is compiling for a 32032 processor, or a
4737 @kbd{-m32532} to specify that it is compiling for a 32532 option.
4738 The default (if neither is specified) is chosen when the assembler
4742 I don't know anything about the 32x32 syntax assembled by
4743 @code{_AS__}. Someone who undersands the processor (I've never seen
4744 one) and the possible syntaxes should write this section.
4746 @subsection Floating Point
4747 The 32x32 uses @sc{ieee} floating point numbers, but @code{_AS__} will only
4748 create single or double precision values. I don't know if the 32x32
4749 understands extended precision numbers.
4751 @subsection 32x32 Machine Directives
4752 The 32x32 has no machine dependent directives.
4757 @node Sparc-Dependent
4759 _CHAPSEC__(0+_GENERIC__) SPARC Dependent Features
4761 @cindex SPARC support
4763 * Sparc-Opts:: Options
4764 * Sparc-Float:: Floating Point
4765 * Sparc-Directives:: Sparc Machine Directives
4769 _CHAPSEC__(1+_GENERIC__) Options
4771 @cindex options for SPARC (none)
4772 @cindex SPARC options (none)
4773 The Sparc has no machine dependent options.
4776 @c FIXME: (sparc) Fill in "syntax" section!
4777 @c subsection syntax
4778 I don't know anything about Sparc syntax. Someone who does
4779 will have to write this section.
4783 _CHAPSEC__(1+_GENERIC__) Floating Point
4785 @cindex floating point, SPARC (@sc{ieee})
4786 @cindex SPARC floating point (@sc{ieee})
4787 The Sparc uses @sc{ieee} floating-point numbers.
4789 @node Sparc-Directives
4790 _CHAPSEC__(1+_GENERIC__) Sparc Machine Directives
4792 @cindex SPARC machine directives
4793 @cindex machine directives, SPARC
4794 The Sparc version of @code{_AS__} supports the following additional
4799 @cindex @code{common} directive, SPARC
4800 This must be followed by a symbol name, a positive number, and
4801 @code{"bss"}. This behaves somewhat like @code{.comm}, but the
4802 syntax is different.
4805 @cindex @code{half} directive, SPARC
4806 This is functionally identical to @code{.short}.
4809 @cindex @code{proc} directive, SPARC
4810 This directive is ignored. Any text following it on the same
4811 line is also ignored.
4814 @cindex @code{reserve} directive, SPARC
4815 This must be followed by a symbol name, a positive number, and
4816 @code{"bss"}. This behaves somewhat like @code{.lcomm}, but the
4817 syntax is different.
4820 @cindex @code{seg} directive, SPARC
4821 This must be followed by @code{"text"}, @code{"data"}, or
4822 @code{"data1"}. It behaves like @code{.text}, @code{.data}, or
4826 @cindex @code{skip} directive, SPARC
4827 This is functionally identical to the @code{.space} directive.
4830 @cindex @code{word} directive, SPARC
4831 On the Sparc, the .word directive produces 32 bit values,
4832 instead of the 16 bit values it produces on many other machines.
4838 @node i386-Dependent
4840 _CHAPSEC__(0+_GENERIC__) 80386 Dependent Features
4842 @cindex i386 support
4843 @cindex i80306 support
4845 * i386-Options:: Options
4846 * i386-Syntax:: AT&T Syntax versus Intel Syntax
4847 * i386-Opcodes:: Opcode Naming
4848 * i386-Regs:: Register Naming
4849 * i386-prefixes:: Opcode Prefixes
4850 * i386-Memory:: Memory References
4851 * i386-jumps:: Handling of Jump Instructions
4852 * i386-Float:: Floating Point
4853 * i386-Notes:: Notes
4857 _CHAPSEC__(1+_GENERIC__) Options
4859 @cindex options for i386 (none)
4860 @cindex i386 options (none)
4861 The 80386 has no machine dependent options.
4864 _CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax
4866 @cindex i386 syntax compatibility
4867 @cindex syntax compatibility, i386
4868 In order to maintain compatibility with the output of @code{_GCC__},
4869 @code{_AS__} supports AT&T System V/386 assembler syntax. This is quite
4870 different from Intel syntax. We mention these differences because
4871 almost all 80386 documents used only Intel syntax. Notable differences
4872 between the two syntaxes are:
4876 @cindex immediate operands, i386
4877 @cindex i386 immediate operands
4878 @cindex register operands, i386
4879 @cindex i386 register operands
4880 @cindex jump/call operands, i386
4881 @cindex i386 jump/call operands
4882 @cindex operand delimiters, i386
4883 AT&T immediate operands are preceded by @samp{$}; Intel immediate
4884 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
4885 AT&T register operands are preceded by @samp{%}; Intel register operands
4886 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
4887 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
4890 @cindex i386 source, destination operands
4891 @cindex source, destination operands; i386
4892 AT&T and Intel syntax use the opposite order for source and destination
4893 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
4894 @samp{source, dest} convention is maintained for compatibility with
4895 previous Unix assemblers.
4898 @cindex opcode suffixes, i386
4899 @cindex sizes operands, i386
4900 @cindex i386 size suffixes
4901 In AT&T syntax the size of memory operands is determined from the last
4902 character of the opcode name. Opcode suffixes of @samp{b}, @samp{w},
4903 and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit)
4904 memory references. Intel syntax accomplishes this by prefixes memory
4905 operands (@emph{not} the opcodes themselves) with @samp{byte ptr},
4906 @samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte
4907 ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax.
4910 @cindex return instructions, i386
4911 @cindex i386 jump, call, return
4912 Immediate form long jumps and calls are
4913 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
4915 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
4917 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
4918 @samp{ret far @var{stack-adjust}}.
4921 @cindex sections, i386
4922 @cindex i386 sections
4923 The AT&T assembler does not provide support for multiple section
4924 programs. Unix style systems expect all programs to be single sections.
4928 _CHAPSEC__(1+_GENERIC__) Opcode Naming
4930 @cindex i386 opcode naming
4931 @cindex opcode naming, i386
4932 Opcode names are suffixed with one character modifiers which specify the
4933 size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify
4934 byte, word, and long operands. If no suffix is specified by an
4935 instruction and it contains no memory operands then @code{_AS__} tries to
4936 fill in the missing suffix based on the destination register operand
4937 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
4938 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
4939 @samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix
4940 assembler which assumes that a missing opcode suffix implies long
4941 operand size. (This incompatibility does not affect compiler output
4942 since compilers always explicitly specify the opcode suffix.)
4944 Almost all opcodes have the same names in AT&T and Intel format. There
4945 are a few exceptions. The sign extend and zero extend instructions need
4946 two sizes to specify them. They need a size to sign/zero extend
4947 @emph{from} and a size to zero extend @emph{to}. This is accomplished
4948 by using two opcode suffixes in AT&T syntax. Base names for sign extend
4949 and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T
4950 syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode
4951 suffixes are tacked on to this base name, the @emph{from} suffix before
4952 the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for
4953 ``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes,
4954 thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word),
4955 and @samp{wl} (from word to long).
4957 @cindex conversion instructions, i386
4958 @cindex i386 conversion instructions
4959 The Intel-syntax conversion instructions
4963 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
4966 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
4969 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
4972 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
4976 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in
4977 AT&T naming. @code{_AS__} accepts either naming for these instructions.
4979 @cindex jump instructions, i386
4980 @cindex call instructions, i386
4981 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
4982 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
4986 _CHAPSEC__(1+_GENERIC__) Register Naming
4988 @cindex i386 registers
4989 @cindex registers, i386
4990 Register operands are always prefixes with @samp{%}. The 80386 registers
4995 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
4996 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
4997 frame pointer), and @samp{%esp} (the stack pointer).
5000 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
5001 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
5004 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
5005 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
5006 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
5007 @samp{%cx}, and @samp{%dx})
5010 the 6 section registers @samp{%cs} (code section), @samp{%ds}
5011 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
5015 the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and
5019 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
5020 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
5023 the 2 test registers @samp{%tr6} and @samp{%tr7}.
5026 the 8 floating point register stack @samp{%st} or equivalently
5027 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
5028 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
5032 _CHAPSEC__(1+_GENERIC__) Opcode Prefixes
5034 @cindex i386 opcode prefixes
5035 @cindex opcode prefixes, i386
5036 @cindex prefixes, i386
5037 Opcode prefixes are used to modify the following opcode. They are used
5038 to repeat string instructions, to provide section overrides, to perform
5039 bus lock operations, and to give operand and address size (16-bit
5040 operands are specified in an instruction by prefixing what would
5041 normally be 32-bit operands with a ``operand size'' opcode prefix).
5042 Opcode prefixes are usually given as single-line instructions with no
5043 operands, and must directly precede the instruction they act upon. For
5044 example, the @samp{scas} (scan string) instruction is repeated with:
5050 Here is a list of opcode prefixes:
5054 @cindex section override prefixes, i386
5055 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
5056 @samp{fs}, @samp{gs}. These are automatically added by specifying
5057 using the @var{section}:@var{memory-operand} form for memory references.
5060 @cindex size prefixes, i386
5061 Operand/Address size prefixes @samp{data16} and @samp{addr16}
5062 change 32-bit operands/addresses into 16-bit operands/addresses. Note
5063 that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes)
5064 are not supported (yet).
5067 @cindex bus lock prefixes, i386
5068 @cindex inhibiting interrupts, i386
5069 The bus lock prefix @samp{lock} inhibits interrupts during
5070 execution of the instruction it precedes. (This is only valid with
5071 certain instructions; see a 80386 manual for details).
5074 @cindex coprocessor wait, i386
5075 The wait for coprocessor prefix @samp{wait} waits for the
5076 coprocessor to complete the current instruction. This should never be
5077 needed for the 80386/80387 combination.
5080 @cindex repeat prefixes, i386
5081 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
5082 to string instructions to make them repeat @samp{%ecx} times.
5086 _CHAPSEC__(1+_GENERIC__) Memory References
5088 @cindex i386 memory references
5089 @cindex memory references, i386
5090 An Intel syntax indirect memory reference of the form
5093 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
5097 is translated into the AT&T syntax
5100 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
5104 where @var{base} and @var{index} are the optional 32-bit base and
5105 index registers, @var{disp} is the optional displacement, and
5106 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
5107 to calculate the address of the operand. If no @var{scale} is
5108 specified, @var{scale} is taken to be 1. @var{section} specifies the
5109 optional section register for the memory operand, and may override the
5110 default section register (see a 80386 manual for section register
5111 defaults). Note that section overrides in AT&T syntax @emph{must} have
5112 be preceded by a @samp{%}. If you specify a section override which
5113 coincides with the default section register, @code{_AS__} will @emph{not}
5114 output any section register override prefixes to assemble the given
5115 instruction. Thus, section overrides can be specified to emphasize which
5116 section register is used for a given memory operand.
5118 Here are some examples of Intel and AT&T style memory references:
5121 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
5122 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
5123 missing, and the default section is used (@samp{%ss} for addressing with
5124 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
5126 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
5127 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
5128 @samp{foo}. All other fields are missing. The section register here
5129 defaults to @samp{%ds}.
5131 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
5132 This uses the value pointed to by @samp{foo} as a memory operand.
5133 Note that @var{base} and @var{index} are both missing, but there is only
5134 @emph{one} @samp{,}. This is a syntactic exception.
5136 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
5137 This selects the contents of the variable @samp{foo} with section
5138 register @var{section} being @samp{%gs}.
5141 Absolute (as opposed to PC relative) call and jump operands must be
5142 prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will
5143 always choose PC relative addressing for jump/call labels.
5145 Any instruction that has a memory operand @emph{must} specify its size (byte,
5146 word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l},
5150 _CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions
5152 @cindex jump optimization, i386
5153 @cindex i386 jump optimization
5154 Jump instructions are always optimized to use the smallest possible
5155 displacements. This is accomplished by using byte (8-bit) displacement
5156 jumps whenever the target is sufficiently close. If a byte displacement
5157 is insufficient a long (32-bit) displacement is used. We do not support
5158 word (16-bit) displacement jumps (i.e. prefixing the jump instruction
5159 with the @samp{addr16} opcode prefix), since the 80386 insists upon masking
5160 @samp{%eip} to 16 bits after the word displacement is added.
5162 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
5163 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in
5164 byte displacements, so that it is possible that use of these
5165 instructions (@code{_GCC__} does not use them) will cause the assembler to
5166 print an error message (and generate incorrect code). The AT&T 80386
5167 assembler tries to get around this problem by expanding @samp{jcxz foo} to
5176 _CHAPSEC__(1+_GENERIC__) Floating Point
5178 @cindex i386 floating point
5179 @cindex floating point, i386
5180 All 80387 floating point types except packed BCD are supported.
5181 (BCD support may be added without much difficulty). These data
5182 types are 16-, 32-, and 64- bit integers, and single (32-bit),
5183 double (64-bit), and extended (80-bit) precision floating point.
5184 Each supported type has an opcode suffix and a constructor
5185 associated with it. Opcode suffixes specify operand's data
5186 types. Constructors build these data types into memory.
5190 @cindex @code{float} directive, i386
5191 @cindex @code{single} directive, i386
5192 @cindex @code{double} directive, i386
5193 @cindex @code{tfloat} directive, i386
5194 Floating point constructors are @samp{.float} or @samp{.single},
5195 @samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats.
5196 These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}.
5197 @samp{t} stands for temporary real, and that the 80387 only supports
5198 this format via the @samp{fldt} (load temporary real to stack top) and
5199 @samp{fstpt} (store temporary real and pop stack) instructions.
5202 @cindex @code{word} directive, i386
5203 @cindex @code{long} directive, i386
5204 @cindex @code{int} directive, i386
5205 @cindex @code{quad} directive, i386
5206 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
5207 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding
5208 opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q}
5209 (quad). As with the temporary real format the 64-bit @samp{q} format is
5210 only present in the @samp{fildq} (load quad integer to stack top) and
5211 @samp{fistpq} (store quad integer and pop stack) instructions.
5214 Register to register operations do not require opcode suffixes,
5215 so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}.
5217 @cindex i386 @code{fwait} instruction
5218 @cindex @code{fwait instruction}, i386
5219 Since the 80387 automatically synchronizes with the 80386 @samp{fwait}
5220 instructions are almost never needed (this is not the case for the
5221 80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses
5222 the @samp{fwait} instruction whenever it is implicitly selected by one
5223 of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and
5224 @samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}}
5225 instructions are made equivalent to @samp{f@dots{}} instructions. If
5226 @samp{fwait} is desired it must be explicitly coded.
5229 _CHAPSEC__(1+_GENERIC__) Notes
5231 @cindex i386 @code{mul}, @code{imul} instructions
5232 @cindex @code{mul} instruction, i386
5233 @cindex @code{imul} instruction, i386
5234 There is some trickery concerning the @samp{mul} and @samp{imul}
5235 instructions that deserves mention. The 16-, 32-, and 64-bit expanding
5236 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
5237 for @samp{imul}) can be output only in the one operand form. Thus,
5238 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
5239 the expanding multiply would clobber the @samp{%edx} register, and this
5240 would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the
5241 64-bit product in @samp{%edx:%eax}.
5243 We have added a two operand form of @samp{imul} when the first operand
5244 is an immediate mode expression and the second operand is a register.
5245 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
5246 example, can be done with @samp{imul $69, %eax} rather than @samp{imul
5252 @node Z8000-Dependent
5254 _CHAPSEC__(0+_GENERIC__) Z8000 Dependent Features
5256 @cindex Z8000 support
5257 The Z8000 _AS__ supports both members of the Z8000 family: the
5258 unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
5261 When the assembler is in unsegmented mode (specified with the
5262 @code{unsegm} directive), an address will take up one word (16 bit)
5263 sized register. When the assembler is in segmented mode (specified with
5264 the @code{segm} directive), a 24-bit address takes up a long (32 bit)
5265 register. @xref{Z8000 Directives,,Assembler Directives for the Z8000},
5266 for a list of other Z8000 specific assembler directives.
5269 * Z8000 Options:: No special command-line options for Z8000
5270 * Z8000 Syntax:: Assembler syntax for the Z8000
5271 * Z8000 Directives:: Special directives for the Z8000
5272 * Z8000 Opcodes:: Opcodes
5276 _CHAPSEC__(1+_GENERIC__) Options
5278 @cindex Z8000 options
5279 @cindex options, Z8000
5280 @code{_AS__} has no additional command-line options for the Zilog
5284 _CHAPSEC__(1+_GENERIC__) Syntax
5286 * Z8000-Chars:: Special Characters
5287 * Z8000-Regs:: Register Names
5288 * Z8000-Addressing:: Addressing Modes
5292 _CHAPSEC__(2+_GENERIC__) Special Characters
5294 @cindex line comment character, Z8000
5295 @cindex Z8000 line comment character
5296 @samp{!} is the line comment character.
5298 @cindex line separator, Z8000
5299 @cindex statement separator, Z8000
5300 @cindex Z8000 line separator
5301 You can use @samp{;} instead of a newline to separate statements.
5304 _CHAPSEC__(2+_GENERIC__) Register Names
5306 @cindex Z8000 registers
5307 @cindex registers, Z8000
5308 The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
5309 to different sized groups of registers by register number, with the
5310 prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and
5311 @samp{rq} for 64 bit registers. You can also refer to the contents of
5312 the first eight (of the sixteen 16 bit registers) by bytes. They are
5313 named @samp{r@var{n}h} and @samp{r@var{n}l}.
5316 @exdent @emph{byte registers}
5317 r0l r0h r1h r1l r2h r2l r3h r3l
5318 r4h r4l r5h r5l r6h r6l r7h r7l
5320 @exdent @emph{word registers}
5321 r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
5323 @exdent @emph{long word registers}
5324 rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
5326 @exdent @emph{quad word registers}
5330 @node Z8000-Addressing
5331 _CHAPSEC__(2+_GENERIC__) Addressing Modes
5333 @cindex addressing modes, Z8000
5334 @cindex Z800 addressing modes
5335 _AS__ understands the following addressing modes for the Z8000:
5345 Direct: the 16 bit or 24 bit address (depending on whether the assembler
5346 is in segmented or unsegmented mode) of the operand is in the instruction.
5348 @item address(r@var{n})
5349 Indexed: the 16 or 24 bit address is added to the 16 bit register to produce
5350 the final address in memory of the operand.
5352 @item r@var{n}(#@var{imm})
5353 Base Address: the 16 or 24 bit register is added to the 16 bit sign
5354 extended immediate displacement to produce the final address in memory
5357 @item r@var{n}(r@var{m})
5358 Base Index: the 16 or 24 bit register r@var{n} is added to the sign
5359 extended 16 bit index register r@var{m} to produce the final address in
5360 memory of the operand.
5363 Immediate data @var{xx}.
5366 @node Z8000 Directives
5367 _CHAPSEC__(1+_GENERIC__) Assembler Directives for the Z8000
5369 @cindex Z8000 directives
5370 @cindex directives, Z8000
5371 The Z8000 port of _AS__ includes these additional assembler directives,
5372 for compatibility with other Z8000 assemblers:
5377 Generates code for the segmented Z8001.
5381 Generates code for the unsegmented Z8002.
5385 Synonym for @code{.file}
5389 Synonum for @code{.global}
5393 Synonym for @code{.word}
5397 Synonym for @code{.long}
5401 Synonym for @code{.byte}
5405 Assemble a string. @code{sval} expects one string literal, delimited by
5406 single quotes. It assembles each byte of the string into consecutive
5407 addresses. You can use the escape sequence @samp{%@var{xx}} (where
5408 @var{xx} represents a two-digit hexadecimal number) to represent the
5409 character whose @sc{ascii} value is @var{xx}. Use this feature to
5410 describe single quote and other characters that may not appear in string
5411 literals as themselves. For example, the C statement @w{@samp{char *a =
5412 "he said \"it's 50% off\"";}} is represented in Z8000 assembly language
5413 (shown with the assembler output in hex at the left) as
5417 @let@nonarrowing=@comment
5420 68652073 sval 'he said %22it%27s 50%25 off%22%00'
5433 synonym for @code{.section}
5437 synonym for @code{.space}
5441 synonym for @code{.align 1}
5445 _CHAPSEC__(1+_GENERIC__) Opcodes
5447 @cindex Z8000 opcode summary
5448 @cindex opcode summary, Z8000
5449 @cindex mnemonics, Z8000
5450 @cindex instruction summary, Z8000
5451 For detailed information on the Z8000 machine instruction set, see
5452 @cite{Z8000 Technical Manual}.
5454 The following table summarizes the opcodes and their arguments:
5457 @let@nonarrowing=@comment
5461 rs @r{16 bit source register}
5462 rd @r{16 bit destination register}
5463 rbs @r{8 bit source register}
5464 rbd @r{8 bit destination register}
5465 rrs @r{32 bit source register}
5466 rrd @r{32 bit destination register}
5467 rqs @r{64 bit source register}
5468 rqd @r{64 bit destination register}
5469 addr @r{16/24 bit address}
5470 imm @r{immediate data}
5472 adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc
5473 adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc
5474 add rd,@@rs clrb rbd dab rbd
5475 add rd,addr com @@rd dbjnz rbd,disp7
5476 add rd,addr(rs) com addr dec @@rd,imm4m1
5477 add rd,imm16 com addr(rd) dec addr(rd),imm4m1
5478 add rd,rs com rd dec addr,imm4m1
5479 addb rbd,@@rs comb @@rd dec rd,imm4m1
5480 addb rbd,addr comb addr decb @@rd,imm4m1
5481 addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
5482 addb rbd,imm8 comb rbd decb addr,imm4m1
5483 addb rbd,rbs comflg flags decb rbd,imm4m1
5484 addl rrd,@@rs cp @@rd,imm16 di i2
5485 addl rrd,addr cp addr(rd),imm16 div rrd,@@rs
5486 addl rrd,addr(rs) cp addr,imm16 div rrd,addr
5487 addl rrd,imm32 cp rd,@@rs div rrd,addr(rs)
5488 addl rrd,rrs cp rd,addr div rrd,imm16
5489 and rd,@@rs cp rd,addr(rs) div rrd,rs
5490 and rd,addr cp rd,imm16 divl rqd,@@rs
5491 and rd,addr(rs) cp rd,rs divl rqd,addr
5492 and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs)
5493 and rd,rs cpb addr(rd),imm8 divl rqd,imm32
5494 andb rbd,@@rs cpb addr,imm8 divl rqd,rrs
5495 andb rbd,addr cpb rbd,@@rs djnz rd,disp7
5496 andb rbd,addr(rs) cpb rbd,addr ei i2
5497 andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs
5498 andb rbd,rbs cpb rbd,imm8 ex rd,addr
5499 bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs)
5500 bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs
5501 bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs
5502 bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr
5503 bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs)
5504 bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs
5505 bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8
5506 bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8
5507 bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8
5508 bitb rbd,rs cpl rrd,@@rs ext8f imm8
5509 bpt cpl rrd,addr exts rrd
5510 call @@rd cpl rrd,addr(rs) extsb rd
5511 call addr cpl rrd,imm32 extsl rqd
5512 call addr(rd) cpl rrd,rrs halt
5513 calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs
5514 clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16
5515 clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs
5516 clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16
5517 clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1
5518 clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1
5519 inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
5520 inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
5521 incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
5522 incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs
5523 incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
5524 incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs)
5525 ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32
5526 indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs
5527 inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd
5528 inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr
5529 iret ldib @@rd,@@rs,rr neg addr(rd)
5530 jp cc,@@rd ldir @@rd,@@rs,rr neg rd
5531 jp cc,addr ldirb @@rd,@@rs,rr negb @@rd
5532 jp cc,addr(rd) ldk rd,imm4 negb addr
5533 jr cc,disp8 ldl @@rd,rrs negb addr(rd)
5534 ld @@rd,imm16 ldl addr(rd),rrs negb rbd
5535 ld @@rd,rs ldl addr,rrs nop
5536 ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs
5537 ld addr(rd),rs ldl rd(rx),rrs or rd,addr
5538 ld addr,imm16 ldl rrd,@@rs or rd,addr(rs)
5539 ld addr,rs ldl rrd,addr or rd,imm16
5540 ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
5541 ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs
5542 ld rd,@@rs ldl rrd,rrs orb rbd,addr
5543 ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
5544 ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
5545 ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs
5546 ld rd,rs ldm addr(rd),rs,n out @@rd,rs
5547 ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
5548 ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs
5549 lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
5550 lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra
5551 lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba
5552 lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra
5553 ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra
5554 ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs
5555 ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs
5556 ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs
5557 ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs
5558 ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs
5559 ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs
5560 ldb rbd,@@rs mbit popl addr,@@rs
5561 ldb rbd,addr mreq rd popl rrd,@@rs
5562 ldb rbd,addr(rs) mres push @@rd,@@rs
5563 ldb rbd,imm8 mset push @@rd,addr
5564 ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs)
5565 ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16
5566 push @@rd,rs set addr,imm4 subl rrd,imm32
5567 pushl @@rd,@@rs set rd,imm4 subl rrd,rrs
5568 pushl @@rd,addr set rd,rs tcc cc,rd
5569 pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd
5570 pushl @@rd,rrs setb addr(rd),imm4 test @@rd
5571 res @@rd,imm4 setb addr,imm4 test addr
5572 res addr(rd),imm4 setb rbd,imm4 test addr(rd)
5573 res addr,imm4 setb rbd,rs test rd
5574 res rd,imm4 setflg imm4 testb @@rd
5575 res rd,rs sinb rbd,imm16 testb addr
5576 resb @@rd,imm4 sinb rd,imm16 testb addr(rd)
5577 resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd
5578 resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd
5579 resb rbd,imm4 sinib @@rd,@@rs,ra testl addr
5580 resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd)
5581 resflg imm4 sla rd,imm8 testl rrd
5582 ret cc slab rbd,imm8 trdb @@rd,@@rs,rba
5583 rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba
5584 rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr
5585 rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr
5586 rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr
5587 rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr
5588 rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr
5589 rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr
5590 rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd
5591 rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr
5592 rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd)
5593 rsvd36 sra rd,imm8 tset rd
5594 rsvd38 srab rbd,imm8 tsetb @@rd
5595 rsvd78 sral rrd,imm8 tsetb addr
5596 rsvd7e srl rd,imm8 tsetb addr(rd)
5597 rsvd9d srlb rbd,imm8 tsetb rbd
5598 rsvd9f srll rrd,imm8 xor rd,@@rs
5599 rsvdb9 sub rd,@@rs xor rd,addr
5600 rsvdbf sub rd,addr xor rd,addr(rs)
5601 sbc rd,rs sub rd,addr(rs) xor rd,imm16
5602 sbcb rbd,rbs sub rd,imm16 xor rd,rs
5603 sc imm8 sub rd,rs xorb rbd,@@rs
5604 sda rd,rs subb rbd,@@rs xorb rbd,addr
5605 sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
5606 sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
5607 sdl rd,rs subb rbd,imm8 xorb rbd,rbs
5608 sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
5609 sdll rrd,rs subl rrd,@@rs
5610 set @@rd,imm4 subl rrd,addr
5611 set addr(rd),imm4 subl rrd,addr(rs)
5619 @c pesch@cygnus.com: we ignore the following chapters, since internals are
5620 @c changing rapidly. These may need to be moved to another
5621 @c book anyhow, if we adopt the model of user/modifier
5624 @chapter Maintaining the Assembler
5625 [[this chapter is still being built]]
5628 We had these goals, in descending priority:
5631 For every program composed by a compiler, @code{_AS__} should emit
5632 ``correct'' code. This leaves some latitude in choosing addressing
5633 modes, order of @code{relocation_info} structures in the object
5636 @item Speed, for usual case.
5637 By far the most common use of @code{_AS__} will be assembling compiler
5640 @item Upward compatibility for existing assembler code.
5641 Well @dots{} we don't support Vax bit fields but everything else
5642 seems to be upward compatible.
5645 The code should be maintainable with few surprises. (JF: ha!)
5649 We assumed that disk I/O was slow and expensive while memory was
5650 fast and access to memory was cheap. We expect the in-memory data
5651 structures to be less than 10 times the size of the emitted object
5652 file. (Contrast this with the C compiler where in-memory structures
5653 might be 100 times object file size!)
5657 Try to read the source file from disk only one time. For other
5658 reasons, we keep large chunks of the source file in memory during
5659 assembly so this is not a problem. Also the assembly algorithm
5660 should only scan the source text once if the compiler composed the
5661 text according to a few simple rules.
5663 Emit the object code bytes only once. Don't store values and then
5666 Build the object file in memory and do direct writes to disk of
5670 RMS suggested a one-pass algorithm which seems to work well. By not
5671 parsing text during a second pass considerable time is saved on
5672 large programs (@emph{e.g.} the sort of C program @code{yacc} would
5675 It happened that the data structures needed to emit relocation
5676 information to the object file were neatly subsumed into the data
5677 structures that do backpatching of addresses after pass 1.
5679 Many of the functions began life as re-usable modules, loosely
5680 connected. RMS changed this to gain speed. For example, input
5681 parsing routines which used to work on pre-sanitized strings now
5682 must parse raw data. Hence they have to import knowledge of the
5683 assemblers' comment conventions @emph{etc}.
5685 @section Deprecated Feature(?)s
5686 We have stopped supporting some features:
5689 @code{.org} statements must have @b{defined} expressions.
5691 Vax Bit fields (@kbd{:} operator) are entirely unsupported.
5694 It might be a good idea to not support these features in a future release:
5697 @kbd{#} should begin a comment, even in column 1.
5699 Why support the logical line & file concept any more?
5701 Subsections are a good candidate for flushing.
5702 Depends on which compilers need them I guess.
5705 @section Bugs, Ideas, Further Work
5706 Clearly the major improvement is DON'T USE A TEXT-READING
5707 ASSEMBLER for the back end of a compiler. It is much faster to
5708 interpret binary gobbledygook from a compiler's tables than to
5709 ask the compiler to write out human-readable code just so the
5710 assembler can parse it back to binary.
5712 Assuming you use @code{_AS__} for human written programs: here are
5716 Document (here) @code{APP}.
5718 Take advantage of knowing no spaces except after opcode
5719 to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces:
5720 only keep space/tabs at begin of line or between 2
5723 Put pointers in this documentation to @file{a.out} documentation.
5725 Split the assembler into parts so it can gobble direct binary
5726 from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text
5727 just so @code{_AS__} can parse it back to binary.
5729 Rewrite hash functions: I want a more modular, faster library.
5731 Clean up LOTS of code.
5733 Include all the non-@file{.c} files in the maintenance chapter.
5737 Implement flonum short literals.
5739 Change all talk of expression operands to expression quantities,
5740 or perhaps to expression arguments.
5744 Whenever a @code{.text} or @code{.data} statement is seen, we close
5745 of the current frag with an imaginary @code{.fill 0}. This is
5746 because we only have one obstack for frags, and we can't grow new
5747 frags for a new subsection, then go back to the old subsection and
5748 append bytes to the old frag. All this nonsense goes away if we
5749 give each subsection its own obstack. It makes code simpler in
5750 about 10 places, but nobody has bothered to do it because C compiler
5751 output rarely changes subsections (compared to ending frags with
5752 relaxable addresses, which is common).
5756 @c The following files in the @file{_AS__} directory
5757 @c are symbolic links to other files, of
5758 @c the same name, in a different directory.
5761 @c @file{atof_generic.c}
5763 @c @file{atof_vax.c}
5765 @c @file{flonum_const.c}
5767 @c @file{flonum_copy.c}
5769 @c @file{flonum_get.c}
5771 @c @file{flonum_multip.c}
5773 @c @file{flonum_normal.c}
5775 @c @file{flonum_print.c}
5778 Here is a list of the source files in the @file{_AS__} directory.
5782 This contains the pre-processing phase, which deletes comments,
5783 handles whitespace, etc. This was recently re-written, since app
5784 used to be a separate program, but RMS wanted it to be inline.
5787 This is a subroutine to append a string to another string returning a
5788 pointer just after the last @code{char} appended. (JF: All these
5789 little routines should probably all be put in one file.)
5792 Here you will find the main program of the assembler @code{_AS__}.
5795 This is a branch office of @file{read.c}. This understands
5796 expressions, arguments. Inside @code{_AS__}, arguments are called
5797 (expression) @emph{operands}. This is confusing, because we also talk
5798 (elsewhere) about instruction @emph{operands}. Also, expression
5799 operands are called @emph{quantities} explicitly to avoid confusion
5800 with instruction operands. What a mess.
5803 This implements the @b{frag} concept. Without frags, finding the
5804 right size for branch instructions would be a lot harder.
5807 This contains the symbol table, opcode table @emph{etc.} hashing
5811 This is a table of values of digits, for use in atoi() type
5812 functions. Could probably be flushed by using calls to strtol(), or
5816 This contains Operating system dependent source file reading
5817 routines. Since error messages often say where we are in reading
5818 the source file, they live here too. Since @code{_AS__} is intended to
5819 run under GNU and Unix only, this might be worth flushing. Anyway,
5820 almost all C compilers support stdio.
5823 This deals with calling the pre-processor (if needed) and feeding the
5824 chunks back to the rest of the assembler the right way.
5827 This contains operating system independent parts of fatal and
5828 warning message reporting. See @file{append.c} above.
5831 This contains operating system dependent functions that write an
5832 object file for @code{_AS__}. See @file{input-file.c} above.
5835 This implements all the directives of @code{_AS__}. This also deals
5836 with passing input lines to the machine dependent part of the
5840 This is a C library function that isn't in most C libraries yet.
5841 See @file{append.c} above.
5844 This implements subsections.
5847 This implements symbols.
5850 This contains the code to perform relaxation, and to write out
5851 the object file. It is mostly operating system independent, but
5852 different OSes have different object file formats in any case.
5855 This implements @code{malloc()} or bust. See @file{append.c} above.
5858 This implements @code{realloc()} or bust. See @file{append.c} above.
5860 @item atof-generic.c
5861 The following files were taken from a machine-independent subroutine
5862 library for manipulating floating point numbers and very large
5865 @file{atof-generic.c} turns a string into a flonum internal format
5866 floating-point number.
5868 @item flonum-const.c
5869 This contains some potentially useful floating point numbers in
5873 This copies a flonum.
5875 @item flonum-multip.c
5876 This multiplies two flonums together.
5879 This copies a bignum.
5883 Here is a table of all the machine-specific files (this includes
5884 both source and header files). Typically, there is a
5885 @var{machine}.c file, a @var{machine}-opcode.h file, and an
5886 atof-@var{machine}.c file. The @var{machine}-opcode.h file should
5887 be identical to the one used by GDB (which uses it for disassembly.)
5892 This contains code to turn a flonum into a ieee literal constant.
5893 This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}.
5896 This is the opcode-table for the i386 version of the assembler.
5899 This contains all the code for the i386 version of the assembler.
5902 This defines constants and macros used by the i386 version of the assembler.
5905 generic 68020 header file. To be linked to m68k.h on a
5906 non-sun3, non-hpux system.
5909 68010 header file for Sun2 workstations. Not well tested. To be linked
5910 to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the
5914 68020 header file for Sun3 workstations. To be linked to m68k.h before
5915 compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the
5919 68020 header file for a HPUX (system 5?) box. Which box, which
5920 version of HPUX, etc? I don't know.
5923 A hard- or symbolic- link to one of @file{m-generic.h},
5924 @file{m-hpux.h} or @file{m-sun3.h} depending on which kind of
5925 680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the
5929 Opcode table for 68020. This is now a link to the opcode table
5930 in the @code{GDB} source directory.
5933 All the mc680x0 code, in one huge, slow-to-compile file.
5936 This contains the code for the ns32032/ns32532 version of the
5939 @item ns32k-opcode.h
5940 This contains the opcode table for the ns32032/ns32532 version
5944 Vax specific file for describing Vax operands and other Vax-ish things.
5950 Vax specific parts of @code{_AS__}. Also includes the former files
5951 @file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}.
5954 Turns a flonum into a Vax constant.
5957 This file contains the special code needed to put out a VMS
5958 style object file for the Vax.
5962 Here is a list of the header files in the source directory.
5963 (Warning: This section may not be very accurate. I didn't
5964 write the header files; I just report them.) Also note that I
5965 think many of these header files could be cleaned up or
5971 This describes the structures used to create the binary header data
5972 inside the object file. Perhaps we should use the one in
5973 @file{/usr/include}?
5976 This defines all the globally useful things, and pulls in _0__<stdio.h>_1__
5977 and _0__<assert.h>_1__.
5980 This defines macros useful for dealing with bignums.
5983 Structure and macros for dealing with expression()
5986 This defines the structure for dealing with floating point
5987 numbers. It #includes @file{bignum.h}.
5990 This contains macro for appending a byte to the current frag.
5993 Structures and function definitions for the hashing functions.
5996 Function headers for the input-file.c functions.
5999 structures and function headers for things defined in the
6000 machine dependent part of the assembler.
6003 This is the GNU systemwide include file for manipulating obstacks.
6004 Since nobody is running under real GNU yet, we include this file.
6007 Macros and function headers for reading in source files.
6009 @item struct-symbol.h
6010 Structure definition and macros for dealing with the _AS__
6011 internal form of a symbol.
6014 structure definition for dealing with the numbered subsections
6015 of the text and data sections.
6018 Macros and function headers for dealing with symbols.
6021 Structure for doing section fixups.
6024 @c ~subsection Test Directory
6025 @c (Note: The test directory seems to have disappeared somewhere
6026 @c along the line. If you want it, you'll probably have to find a
6027 @c REALLY OLD dump tape~dots{})
6029 @c The ~file{test/} directory is used for regression testing.
6030 @c After you modify ~@code{_AS__}, you can get a quick go/nogo
6031 @c confidence test by running the new ~@code{_AS__} over the source
6032 @c files in this directory. You use a shell script ~file{test/do}.
6034 @c The tests in this suite are evolving. They are not comprehensive.
6035 @c They have, however, caught hundreds of bugs early in the debugging
6036 @c cycle of ~@code{_AS__}. Most test statements in this suite were naturally
6037 @c selected: they were used to demonstrate actual ~@code{_AS__} bugs rather
6038 @c than being written ~i{a prioi}.
6040 @c Another testing suggestion: over 30 bugs have been found simply by
6041 @c running examples from this manual through ~@code{_AS__}.
6042 @c Some examples in this manual are selected
6043 @c to distinguish boundary conditions; they are good for testing ~@code{_AS__}.
6045 @c ~subsubsection Regression Testing
6046 @c Each regression test involves assembling a file and comparing the
6047 @c actual output of ~@code{_AS__} to ``known good'' output files. Both
6048 @c the object file and the error/warning message file (stderr) are
6049 @c inspected. Optionally the ~@code{_AS__} exit status may be checked.
6050 @c Discrepencies are reported. Each discrepency means either that
6051 @c you broke some part of ~@code{_AS__} or that the ``known good'' files
6052 @c are now out of date and should be changed to reflect the new
6053 @c definition of ``good''.
6055 @c Each regression test lives in its own directory, in a tree
6056 @c rooted in the directory ~file{test/}. Each such directory
6057 @c has a name ending in ~file{.ret}, where `ret' stands for
6058 @c REgression Test. The ~file{.ret} ending allows ~code{find
6059 @c (1)} to find all regression tests in the tree, without
6060 @c needing to list them explicitly.
6062 @c Any ~file{.ret} directory must contain a file called
6063 @c ~file{input} which is the source file to assemble. During
6064 @c testing an object file ~file{output} is created, as well as
6065 @c a file ~file{stdouterr} which contains the output to both
6066 @c stderr and stderr. If there is a file ~file{output.good} in
6067 @c the directory, and if ~file{output} contains exactly the
6068 @c same data as ~file{output.good}, the file ~file{output} is
6069 @c deleted. Likewise ~file{stdouterr} is removed if it exactly
6070 @c matches a file ~file{stdouterr.good}. If file
6071 @c ~file{status.good} is present, containing a decimal number
6072 @c before a newline, the exit status of ~@code{_AS__} is compared
6073 @c to this number. If the status numbers are not equal, a file
6074 @c ~file{status} is written to the directory, containing the
6075 @c actual status as a decimal number followed by newline.
6077 @c Should any of the ~file{*.good} files fail to match their corresponding
6078 @c actual files, this is noted by a 1-line message on the screen during
6079 @c the regression test, and you can use ~@code{find (1)} to find any
6080 @c files named ~file{status}, ~file {output} or ~file{stdouterr}.
6084 @chapter Teaching the Assembler about a New Machine
6086 This chapter describes the steps required in order to make the
6087 assembler work with another machine's assembly language. This
6088 chapter is not complete, and only describes the steps in the
6089 broadest terms. You should look at the source for the
6090 currently supported machine in order to discover some of the
6091 details that aren't mentioned here.
6093 You should create a new file called @file{@var{machine}.c}, and
6094 add the appropriate lines to the file @file{Makefile} so that
6095 you can compile your new version of the assembler. This should
6096 be straighforward; simply add lines similar to the ones there
6097 for the four current versions of the assembler.
6099 If you want to be compatible with GDB, (and the current
6100 machine-dependent versions of the assembler), you should create
6101 a file called @file{@var{machine}-opcode.h} which should
6102 contain all the information about the names of the machine
6103 instructions, their opcodes, and what addressing modes they
6104 support. If you do this right, the assembler and GDB can share
6105 this file, and you'll only have to write it once. Note that
6106 while you're writing @code{_AS__}, you may want to use an
6107 independent program (if you have access to one), to make sure
6108 that @code{_AS__} is emitting the correct bytes. Since @code{_AS__}
6109 and @code{GDB} share the opcode table, an incorrect opcode
6110 table entry may make invalid bytes look OK when you disassemble
6111 them with @code{GDB}.
6113 @section Functions You will Have to Write
6115 Your file @file{@var{machine}.c} should contain definitions for
6116 the following functions and variables. It will need to include
6117 some header files in order to use some of the structures
6118 defined in the machine-independent part of the assembler. The
6119 needed header files are mentioned in the descriptions of the
6120 functions that will need them.
6125 This long integer holds the value to place at the beginning of
6126 the @file{a.out} file. It is usually @samp{OMAGIC}, except on
6127 machines that store additional information in the magic-number.
6129 @item char comment_chars[];
6130 This character array holds the values of the characters that
6131 start a comment anywhere in a line. Comments are stripped off
6132 automatically by the machine independent part of the
6133 assembler. Note that the @samp{/*} will always start a
6134 comment, and that only @samp{*/} will end a comment started by
6137 @item char line_comment_chars[];
6138 This character array holds the values of the chars that start a
6139 comment only if they are the first (non-whitespace) character
6140 on a line. If the character @samp{#} does not appear in this
6141 list, you may get unexpected results. (Various
6142 machine-independent parts of the assembler treat the comments
6143 @samp{#APP} and @samp{#NO_APP} specially, and assume that lines
6144 that start with @samp{#} are comments.)
6146 @item char EXP_CHARS[];
6147 This character array holds the letters that can separate the
6148 mantissa and the exponent of a floating point number. Typical
6149 values are @samp{e} and @samp{E}.
6151 @item char FLT_CHARS[];
6152 This character array holds the letters that--when they appear
6153 immediately after a leading zero--indicate that a number is a
6154 floating-point number. (Sort of how 0x indicates that a
6155 hexadecimal number follows.)
6157 @item pseudo_typeS md_pseudo_table[];
6158 (@var{pseudo_typeS} is defined in @file{md.h})
6159 This array contains a list of the machine_dependent directives
6160 the assembler must support. It contains the name of each
6161 pseudo op (Without the leading @samp{.}), a pointer to a
6162 function to be called when that directive is encountered, and
6163 an integer argument to be passed to that function.
6165 @item void md_begin(void)
6166 This function is called as part of the assembler's
6167 initialization. It should do any initialization required by
6168 any of your other routines.
6170 @item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR)
6171 This routine is called once for each option on the command line
6172 that the machine-independent part of @code{_AS__} does not
6173 understand. This function should return non-zero if the option
6174 pointed to by @var{optionPTR} is a valid option. If it is not
6175 a valid option, this routine should return zero. The variables
6176 @var{argcPTR} and @var{argvPTR} are provided in case the option
6177 requires a filename or something similar as an argument. If
6178 the option is multi-character, @var{optionPTR} should be
6179 advanced past the end of the option, otherwise every letter in
6180 the option will be treated as a separate single-character
6183 @item void md_assemble(char *string)
6184 This routine is called for every machine-dependent
6185 non-directive line in the source file. It does all the real
6186 work involved in reading the opcode, parsing the operands,
6187 etc. @var{string} is a pointer to a null-terminated string,
6188 that comprises the input line, with all excess whitespace and
6191 @item void md_number_to_chars(char *outputPTR,long value,int nbytes)
6192 This routine is called to turn a C long int, short int, or char
6193 into the series of bytes that represents that number on the
6194 target machine. @var{outputPTR} points to an array where the
6195 result should be stored; @var{value} is the value to store; and
6196 @var{nbytes} is the number of bytes in 'value' that should be
6199 @item void md_number_to_imm(char *outputPTR,long value,int nbytes)
6200 This routine is called to turn a C long int, short int, or char
6201 into the series of bytes that represent an immediate value on
6202 the target machine. It is identical to the function @code{md_number_to_chars},
6203 except on NS32K machines.@refill
6205 @item void md_number_to_disp(char *outputPTR,long value,int nbytes)
6206 This routine is called to turn a C long int, short int, or char
6207 into the series of bytes that represent an displacement value on
6208 the target machine. It is identical to the function @code{md_number_to_chars},
6209 except on NS32K machines.@refill
6211 @item void md_number_to_field(char *outputPTR,long value,int nbytes)
6212 This routine is identical to @code{md_number_to_chars},
6213 except on NS32K machines.
6215 @item void md_ri_to_chars(struct relocation_info *riPTR,ri)
6216 (@code{struct relocation_info} is defined in @file{a.out.h})
6217 This routine emits the relocation info in @var{ri}
6218 in the appropriate bit-pattern for the target machine.
6219 The result should be stored in the location pointed
6220 to by @var{riPTR}. This routine may be a no-op unless you are
6221 attempting to do cross-assembly.
6223 @item char *md_atof(char type,char *outputPTR,int *sizePTR)
6224 This routine turns a series of digits into the appropriate
6225 internal representation for a floating-point number.
6226 @var{type} is a character from @var{FLT_CHARS[]} that describes
6227 what kind of floating point number is wanted; @var{outputPTR}
6228 is a pointer to an array that the result should be stored in;
6229 and @var{sizePTR} is a pointer to an integer where the size (in
6230 bytes) of the result should be stored. This routine should
6231 return an error message, or an empty string (not (char *)0) for
6234 @item int md_short_jump_size;
6235 This variable holds the (maximum) size in bytes of a short (16
6236 bit or so) jump created by @code{md_create_short_jump()}. This
6237 variable is used as part of the broken-word feature, and isn't
6238 needed if the assembler is compiled with
6239 @samp{-DWORKING_DOT_WORD}.
6241 @item int md_long_jump_size;
6242 This variable holds the (maximum) size in bytes of a long (32
6243 bit or so) jump created by @code{md_create_long_jump()}. This
6244 variable is used as part of the broken-word feature, and isn't
6245 needed if the assembler is compiled with
6246 @samp{-DWORKING_DOT_WORD}.
6248 @item void md_create_short_jump(char *resultPTR,long from_addr,
6249 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6250 This function emits a jump from @var{from_addr} to @var{to_addr} in
6251 the array of bytes pointed to by @var{resultPTR}. If this creates a
6252 type of jump that must be relocated, this function should call
6253 @code{fix_new()} with @var{frag} and @var{to_symbol}. The jump
6254 emitted by this function may be smaller than @var{md_short_jump_size},
6255 but it must never create a larger one.
6256 (If it creates a smaller jump, the extra bytes of memory will not be
6257 used.) This function is used as part of the broken-word feature,
6258 and isn't needed if the assembler is compiled with
6259 @samp{-DWORKING_DOT_WORD}.@refill
6261 @item void md_create_long_jump(char *ptr,long from_addr,
6262 @code{long to_addr,fragS *frag,symbolS *to_symbol)}
6263 This function is similar to the previous function,
6264 @code{md_create_short_jump()}, except that it creates a long
6265 jump instead of a short one. This function is used as part of
6266 the broken-word feature, and isn't needed if the assembler is
6267 compiled with @samp{-DWORKING_DOT_WORD}.
6269 @item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type)
6270 This function does the initial setting up for relaxation. This
6271 includes forcing references to still-undefined symbols to the
6272 appropriate addressing modes.
6274 @item relax_typeS md_relax_table[];
6275 (relax_typeS is defined in md.h)
6276 This array describes the various machine dependent states a
6277 frag may be in before relaxation. You will need one group of
6278 entries for each type of addressing mode you intend to relax.
6280 @item void md_convert_frag(fragS *fragPTR)
6281 (@var{fragS} is defined in @file{as.h})
6282 This routine does the required cleanup after relaxation.
6283 Relaxation has changed the type of the frag to a type that can
6284 reach its destination. This function should adjust the opcode
6285 of the frag to use the appropriate addressing mode.
6286 @var{fragPTR} points to the frag to clean up.
6288 @item void md_end(void)
6289 This function is called just before the assembler exits. It
6290 need not free up memory unless the operating system doesn't do
6291 it automatically on exit. (In which case you'll also have to
6292 track down all the other places where the assembler allocates
6293 space but never frees it.)
6297 @section External Variables You will Need to Use
6299 You will need to refer to or change the following external variables
6300 from within the machine-dependent part of the assembler.
6303 @item extern char flagseen[];
6304 This array holds non-zero values in locations corresponding to
6305 the options that were on the command line. Thus, if the
6306 assembler was called with @samp{-W}, @var{flagseen['W']} would
6309 @item extern fragS *frag_now;
6310 This pointer points to the current frag--the frag that bytes
6311 are currently being added to. If nothing else, you will need
6312 to pass it as an argument to various machine-independent
6313 functions. It is maintained automatically by the
6314 frag-manipulating functions; you should never have to change it
6317 @item extern LITTLENUM_TYPE generic_bignum[];
6318 (@var{LITTLENUM_TYPE} is defined in @file{bignum.h}.
6319 This is where @dfn{bignums}--numbers larger than 32 bits--are
6320 returned when they are encountered in an expression. You will
6321 need to use this if you need to implement directives (or
6322 anything else) that must deal with these large numbers.
6323 @code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in
6324 @file{as.h}, and have a positive @code{X_add_number}. The
6325 @code{X_add_number} of a @code{bignum} is the number of
6326 @code{LITTLENUMS} in @var{generic_bignum} that the number takes
6329 @item extern FLONUM_TYPE generic_floating_point_number;
6330 (@var{FLONUM_TYPE} is defined in @file{flonum.h}.
6331 The is where @dfn{flonums}--floating-point numbers within
6332 expressions--are returned. @code{Flonums} are of @code{segT}
6333 @code{SEG_BIG}, and have a negative @code{X_add_number}.
6334 @code{Flonums} are returned in a generic format. You will have
6335 to write a routine to turn this generic format into the
6336 appropriate floating-point format for your machine.
6338 @item extern int need_pass_2;
6339 If this variable is non-zero, the assembler has encountered an
6340 expression that cannot be assembled in a single pass. Since
6341 the second pass isn't implemented, this flag means that the
6342 assembler is punting, and is only looking for additional syntax
6343 errors. (Or something like that.)
6345 @item extern segT now_seg;
6346 This variable holds the value of the section the assembler is
6347 currently assembling into.
6351 @section External functions will you need
6353 You will find the following external functions useful (or
6354 indispensable) when you're writing the machine-dependent part
6359 @item char *frag_more(int bytes)
6360 This function allocates @var{bytes} more bytes in the current
6361 frag (or starts a new frag, if it can't expand the current frag
6362 any more.) for you to store some object-file bytes in. It
6363 returns a pointer to the bytes, ready for you to store data in.
6365 @item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel)
6366 This function stores a relocation fixup to be acted on later.
6367 @var{frag} points to the frag the relocation belongs in;
6368 @var{where} is the location within the frag where the relocation begins;
6369 @var{size} is the size of the relocation, and is usually 1 (a single byte),
6370 2 (sixteen bits), or 4 (a longword).
6371 The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s)
6372 at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the
6373 location is subtracted from the result. A relocation entry is also added
6374 to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or
6375 @var{offset} may be NULL.@refill
6377 @item char *frag_var(relax_stateT type, int max_chars, int var,
6378 @code{relax_substateT subtype, symbolS *symbol, char *opcode)}
6379 This function creates a machine-dependent frag of type @var{type}
6380 (usually @code{rs_machine_dependent}).
6381 @var{max_chars} is the maximum size in bytes that the frag may grow by;
6382 @var{var} is the current size of the variable end of the frag;
6383 @var{subtype} is the sub-type of the frag. The sub-type is used to index into
6384 @var{md_relax_table[]} during @code{relaxation}.
6385 @var{symbol} is the symbol whose value should be used to when relax-ing this frag.
6386 @var{opcode} points into a byte whose value may have to be modified if the
6387 addressing mode used by this frag changes. It typically points into the
6388 @var{fr_literal[]} of the previous frag, and is used to point to a location
6389 that @code{md_convert_frag()}, may have to change.@refill
6391 @item void frag_wane(fragS *fragPTR)
6392 This function is useful from within @code{md_convert_frag}. It
6393 changes a frag to type rs_fill, and sets the variable-sized
6394 piece of the frag to zero. The frag will never change in size
6397 @item segT expression(expressionS *retval)
6398 (@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h})
6399 This function parses the string pointed to by the external char
6400 pointer @var{input_line_pointer}, and returns the section-type
6401 of the expression. It also stores the results in the
6402 @var{expressionS} pointed to by @var{retval}.
6403 @var{input_line_pointer} is advanced to point past the end of
6404 the expression. (@var{input_line_pointer} is used by other
6405 parts of the assembler. If you modify it, be sure to restore
6406 it to its original value.)
6408 @item as_warn(char *message,@dots{})
6409 If warning messages are disabled, this function does nothing.
6410 Otherwise, it prints out the current file name, and the current
6411 line number, then uses @code{fprintf} to print the
6412 @var{message} and any arguments it was passed.
6414 @item as_bad(char *message,@dots{})
6415 This function should be called when @code{_AS__} encounters
6416 conditions that are bad enough that @code{_AS__} should not
6417 produce an object file, but should continue reading input and
6418 printing warning and bad error messages.
6420 @item as_fatal(char *message,@dots{})
6421 This function prints out the current file name and line number,
6422 prints the word @samp{FATAL:}, then uses @code{fprintf} to
6423 print the @var{message} and any arguments it was passed. Then
6424 the assembler exits. This function should only be used for
6425 serious, unrecoverable errors.
6427 @item void float_const(int float_type)
6428 This function reads floating-point constants from the current
6429 input line, and calls @code{md_atof} to assemble them. It is
6430 useful as the function to call for the directives
6431 @samp{.single}, @samp{.double}, @samp{.float}, etc.
6432 @var{float_type} must be a character from @var{FLT_CHARS}.
6434 @item void demand_empty_rest_of_line(void);
6435 This function can be used by machine-dependent directives to
6436 make sure the rest of the input line is empty. It prints a
6437 warning message if there are additional characters on the line.
6439 @item long int get_absolute_expression(void)
6440 This function can be used by machine-dependent directives to
6441 read an absolute number from the current input line. It
6442 returns the result. If it isn't given an absolute expression,
6443 it prints a warning message and returns zero.
6448 @section The concept of Frags
6450 This assembler works to optimize the size of certain addressing
6451 modes. (e.g. branch instructions) This means the size of many
6452 pieces of object code cannot be determined until after assembly
6453 is finished. (This means that the addresses of symbols cannot be
6454 determined until assembly is finished.) In order to do this,
6455 @code{_AS__} stores the output bytes as @dfn{frags}.
6457 Here is the definition of a frag (from @file{as.h})
6463 relax_stateT fr_type;
6464 relax_substateT fr_substate;
6465 unsigned long fr_address;
6467 struct symbol *fr_symbol;
6469 struct frag *fr_next;
6476 is the size of the fixed-size piece of the frag.
6479 is the maximum (?) size of the variable-sized piece of the frag.
6482 is the type of the frag.
6487 rs_machine_dependent
6490 This stores the type of machine-dependent frag this is. (what
6491 kind of addressing mode is being used, and what size is being
6495 @var{fr_address} is only valid after relaxation is finished.
6496 Before relaxation, the only way to store an address is (pointer
6497 to frag containing the address) plus (offset into the frag).
6500 This contains a number, whose meaning depends on the type of
6502 for machine_dependent frags, this contains the offset from
6503 fr_symbol that the frag wants to go to. Thus, for branch
6504 instructions it is usually zero. (unless the instruction was
6505 @samp{jba foo+12} or something like that.)
6508 for machine_dependent frags, this points to the symbol the frag
6512 This points to the location in the frag (or in a previous frag)
6513 of the opcode for the instruction that caused this to be a frag.
6514 @var{fr_opcode} is needed if the actual opcode must be changed
6515 in order to use a different form of the addressing mode.
6516 (For example, if a conditional branch only comes in size tiny,
6517 a large-size branch could be implemented by reversing the sense
6518 of the test, and turning it into a tiny branch over a large jump.
6519 This would require changing the opcode.)
6521 @var{fr_literal} is a variable-size array that contains the
6522 actual object bytes. A frag consists of a fixed size piece of
6523 object data, (which may be zero bytes long), followed by a
6524 piece of object data whose size may not have been determined
6525 yet. Other information includes the type of the frag (which
6526 controls how it is relaxed),
6529 This is the next frag in the singly-linked list. This is
6530 usually only needed by the machine-independent part of
6537 @unnumbered GNU GENERAL PUBLIC LICENSE
6541 @cindex copying @code{_AS__}
6542 @center Version 2, June 1991
6545 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
6546 675 Mass Ave, Cambridge, MA 02139, USA
6548 Everyone is permitted to copy and distribute verbatim copies
6549 of this license document, but changing it is not allowed.
6552 @unnumberedsec Preamble
6554 The licenses for most software are designed to take away your
6555 freedom to share and change it. By contrast, the GNU General Public
6556 License is intended to guarantee your freedom to share and change free
6557 software---to make sure the software is free for all its users. This
6558 General Public License applies to most of the Free Software
6559 Foundation's software and to any other program whose authors commit to
6560 using it. (Some other Free Software Foundation software is covered by
6561 the GNU Library General Public License instead.) You can apply it to
6564 When we speak of free software, we are referring to freedom, not
6565 price. Our General Public Licenses are designed to make sure that you
6566 have the freedom to distribute copies of free software (and charge for
6567 this service if you wish), that you receive source code or can get it
6568 if you want it, that you can change the software or use pieces of it
6569 in new free programs; and that you know you can do these things.
6571 To protect your rights, we need to make restrictions that forbid
6572 anyone to deny you these rights or to ask you to surrender the rights.
6573 These restrictions translate to certain responsibilities for you if you
6574 distribute copies of the software, or if you modify it.
6576 For example, if you distribute copies of such a program, whether
6577 gratis or for a fee, you must give the recipients all the rights that
6578 you have. You must make sure that they, too, receive or can get the
6579 source code. And you must show them these terms so they know their
6582 We protect your rights with two steps: (1) copyright the software, and
6583 (2) offer you this license which gives you legal permission to copy,
6584 distribute and/or modify the software.
6586 Also, for each author's protection and ours, we want to make certain
6587 that everyone understands that there is no warranty for this free
6588 software. If the software is modified by someone else and passed on, we
6589 want its recipients to know that what they have is not the original, so
6590 that any problems introduced by others will not reflect on the original
6591 authors' reputations.
6593 Finally, any free program is threatened constantly by software
6594 patents. We wish to avoid the danger that redistributors of a free
6595 program will individually obtain patent licenses, in effect making the
6596 program proprietary. To prevent this, we have made it clear that any
6597 patent must be licensed for everyone's free use or not licensed at all.
6599 The precise terms and conditions for copying, distribution and
6600 modification follow.
6603 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6606 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6611 This License applies to any program or other work which contains
6612 a notice placed by the copyright holder saying it may be distributed
6613 under the terms of this General Public License. The ``Program'', below,
6614 refers to any such program or work, and a ``work based on the Program''
6615 means either the Program or any derivative work under copyright law:
6616 that is to say, a work containing the Program or a portion of it,
6617 either verbatim or with modifications and/or translated into another
6618 language. (Hereinafter, translation is included without limitation in
6619 the term ``modification''.) Each licensee is addressed as ``you''.
6621 Activities other than copying, distribution and modification are not
6622 covered by this License; they are outside its scope. The act of
6623 running the Program is not restricted, and the output from the Program
6624 is covered only if its contents constitute a work based on the
6625 Program (independent of having been made by running the Program).
6626 Whether that is true depends on what the Program does.
6629 You may copy and distribute verbatim copies of the Program's
6630 source code as you receive it, in any medium, provided that you
6631 conspicuously and appropriately publish on each copy an appropriate
6632 copyright notice and disclaimer of warranty; keep intact all the
6633 notices that refer to this License and to the absence of any warranty;
6634 and give any other recipients of the Program a copy of this License
6635 along with the Program.
6637 You may charge a fee for the physical act of transferring a copy, and
6638 you may at your option offer warranty protection in exchange for a fee.
6641 You may modify your copy or copies of the Program or any portion
6642 of it, thus forming a work based on the Program, and copy and
6643 distribute such modifications or work under the terms of Section 1
6644 above, provided that you also meet all of these conditions:
6648 You must cause the modified files to carry prominent notices
6649 stating that you changed the files and the date of any change.
6652 You must cause any work that you distribute or publish, that in
6653 whole or in part contains or is derived from the Program or any
6654 part thereof, to be licensed as a whole at no charge to all third
6655 parties under the terms of this License.
6658 If the modified program normally reads commands interactively
6659 when run, you must cause it, when started running for such
6660 interactive use in the most ordinary way, to print or display an
6661 announcement including an appropriate copyright notice and a
6662 notice that there is no warranty (or else, saying that you provide
6663 a warranty) and that users may redistribute the program under
6664 these conditions, and telling the user how to view a copy of this
6665 License. (Exception: if the Program itself is interactive but
6666 does not normally print such an announcement, your work based on
6667 the Program is not required to print an announcement.)
6670 These requirements apply to the modified work as a whole. If
6671 identifiable sections of that work are not derived from the Program,
6672 and can be reasonably considered independent and separate works in
6673 themselves, then this License, and its terms, do not apply to those
6674 sections when you distribute them as separate works. But when you
6675 distribute the same sections as part of a whole which is a work based
6676 on the Program, the distribution of the whole must be on the terms of
6677 this License, whose permissions for other licensees extend to the
6678 entire whole, and thus to each and every part regardless of who wrote it.
6680 Thus, it is not the intent of this section to claim rights or contest
6681 your rights to work written entirely by you; rather, the intent is to
6682 exercise the right to control the distribution of derivative or
6683 collective works based on the Program.
6685 In addition, mere aggregation of another work not based on the Program
6686 with the Program (or with a work based on the Program) on a volume of
6687 a storage or distribution medium does not bring the other work under
6688 the scope of this License.
6691 You may copy and distribute the Program (or a work based on it,
6692 under Section 2) in object code or executable form under the terms of
6693 Sections 1 and 2 above provided that you also do one of the following:
6697 Accompany it with the complete corresponding machine-readable
6698 source code, which must be distributed under the terms of Sections
6699 1 and 2 above on a medium customarily used for software interchange; or,
6702 Accompany it with a written offer, valid for at least three
6703 years, to give any third party, for a charge no more than your
6704 cost of physically performing source distribution, a complete
6705 machine-readable copy of the corresponding source code, to be
6706 distributed under the terms of Sections 1 and 2 above on a medium
6707 customarily used for software interchange; or,
6710 Accompany it with the information you received as to the offer
6711 to distribute corresponding source code. (This alternative is
6712 allowed only for noncommercial distribution and only if you
6713 received the program in object code or executable form with such
6714 an offer, in accord with Subsection b above.)
6717 The source code for a work means the preferred form of the work for
6718 making modifications to it. For an executable work, complete source
6719 code means all the source code for all modules it contains, plus any
6720 associated interface definition files, plus the scripts used to
6721 control compilation and installation of the executable. However, as a
6722 special exception, the source code distributed need not include
6723 anything that is normally distributed (in either source or binary
6724 form) with the major components (compiler, kernel, and so on) of the
6725 operating system on which the executable runs, unless that component
6726 itself accompanies the executable.
6728 If distribution of executable or object code is made by offering
6729 access to copy from a designated place, then offering equivalent
6730 access to copy the source code from the same place counts as
6731 distribution of the source code, even though third parties are not
6732 compelled to copy the source along with the object code.
6735 You may not copy, modify, sublicense, or distribute the Program
6736 except as expressly provided under this License. Any attempt
6737 otherwise to copy, modify, sublicense or distribute the Program is
6738 void, and will automatically terminate your rights under this License.
6739 However, parties who have received copies, or rights, from you under
6740 this License will not have their licenses terminated so long as such
6741 parties remain in full compliance.
6744 You are not required to accept this License, since you have not
6745 signed it. However, nothing else grants you permission to modify or
6746 distribute the Program or its derivative works. These actions are
6747 prohibited by law if you do not accept this License. Therefore, by
6748 modifying or distributing the Program (or any work based on the
6749 Program), you indicate your acceptance of this License to do so, and
6750 all its terms and conditions for copying, distributing or modifying
6751 the Program or works based on it.
6754 Each time you redistribute the Program (or any work based on the
6755 Program), the recipient automatically receives a license from the
6756 original licensor to copy, distribute or modify the Program subject to
6757 these terms and conditions. You may not impose any further
6758 restrictions on the recipients' exercise of the rights granted herein.
6759 You are not responsible for enforcing compliance by third parties to
6763 If, as a consequence of a court judgment or allegation of patent
6764 infringement or for any other reason (not limited to patent issues),
6765 conditions are imposed on you (whether by court order, agreement or
6766 otherwise) that contradict the conditions of this License, they do not
6767 excuse you from the conditions of this License. If you cannot
6768 distribute so as to satisfy simultaneously your obligations under this
6769 License and any other pertinent obligations, then as a consequence you
6770 may not distribute the Program at all. For example, if a patent
6771 license would not permit royalty-free redistribution of the Program by
6772 all those who receive copies directly or indirectly through you, then
6773 the only way you could satisfy both it and this License would be to
6774 refrain entirely from distribution of the Program.
6776 If any portion of this section is held invalid or unenforceable under
6777 any particular circumstance, the balance of the section is intended to
6778 apply and the section as a whole is intended to apply in other
6781 It is not the purpose of this section to induce you to infringe any
6782 patents or other property right claims or to contest validity of any
6783 such claims; this section has the sole purpose of protecting the
6784 integrity of the free software distribution system, which is
6785 implemented by public license practices. Many people have made
6786 generous contributions to the wide range of software distributed
6787 through that system in reliance on consistent application of that
6788 system; it is up to the author/donor to decide if he or she is willing
6789 to distribute software through any other system and a licensee cannot
6792 This section is intended to make thoroughly clear what is believed to
6793 be a consequence of the rest of this License.
6796 If the distribution and/or use of the Program is restricted in
6797 certain countries either by patents or by copyrighted interfaces, the
6798 original copyright holder who places the Program under this License
6799 may add an explicit geographical distribution limitation excluding
6800 those countries, so that distribution is permitted only in or among
6801 countries not thus excluded. In such case, this License incorporates
6802 the limitation as if written in the body of this License.
6805 The Free Software Foundation may publish revised and/or new versions
6806 of the General Public License from time to time. Such new versions will
6807 be similar in spirit to the present version, but may differ in detail to
6808 address new problems or concerns.
6810 Each version is given a distinguishing version number. If the Program
6811 specifies a version number of this License which applies to it and ``any
6812 later version'', you have the option of following the terms and conditions
6813 either of that version or of any later version published by the Free
6814 Software Foundation. If the Program does not specify a version number of
6815 this License, you may choose any version ever published by the Free Software
6819 If you wish to incorporate parts of the Program into other free
6820 programs whose distribution conditions are different, write to the author
6821 to ask for permission. For software which is copyrighted by the Free
6822 Software Foundation, write to the Free Software Foundation; we sometimes
6823 make exceptions for this. Our decision will be guided by the two goals
6824 of preserving the free status of all derivatives of our free software and
6825 of promoting the sharing and reuse of software generally.
6828 @heading NO WARRANTY
6835 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
6836 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
6837 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
6838 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
6839 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6840 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
6841 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
6842 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
6843 REPAIR OR CORRECTION.
6846 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
6847 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
6848 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
6849 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
6850 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
6851 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
6852 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
6853 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
6854 POSSIBILITY OF SUCH DAMAGES.
6858 @heading END OF TERMS AND CONDITIONS
6861 @center END OF TERMS AND CONDITIONS
6865 @unnumberedsec Applying These Terms to Your New Programs
6867 If you develop a new program, and you want it to be of the greatest
6868 possible use to the public, the best way to achieve this is to make it
6869 free software which everyone can redistribute and change under these terms.
6871 To do so, attach the following notices to the program. It is safest
6872 to attach them to the start of each source file to most effectively
6873 convey the exclusion of warranty; and each file should have at least
6874 the ``copyright'' line and a pointer to where the full notice is found.
6877 @var{one line to give the program's name and an idea of what it does.}
6878 Copyright (C) 19@var{yy} @var{name of author}
6880 This program is free software; you can redistribute it and/or
6881 modify it under the terms of the GNU General Public License
6882 as published by the Free Software Foundation; either version 2
6883 of the License, or (at your option) any later version.
6885 This program is distributed in the hope that it will be useful,
6886 but WITHOUT ANY WARRANTY; without even the implied warranty of
6887 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6888 GNU General Public License for more details.
6890 You should have received a copy of the GNU General Public License
6891 along with this program; if not, write to the
6892 Free Software Foundation, Inc., 675 Mass Ave,
6893 Cambridge, MA 02139, USA.
6896 Also add information on how to contact you by electronic and paper mail.
6898 If the program is interactive, make it output a short notice like this
6899 when it starts in an interactive mode:
6902 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
6903 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
6904 type `show w'. This is free software, and you are welcome
6905 to redistribute it under certain conditions; type `show c'
6909 The hypothetical commands @samp{show w} and @samp{show c} should show
6910 the appropriate parts of the General Public License. Of course, the
6911 commands you use may be called something other than @samp{show w} and
6912 @samp{show c}; they could even be mouse-clicks or menu items---whatever
6915 You should also get your employer (if you work as a programmer) or your
6916 school, if any, to sign a ``copyright disclaimer'' for the program, if
6917 necessary. Here is a sample; alter the names:
6920 Yoyodyne, Inc., hereby disclaims all copyright interest in
6921 the program `Gnomovision' (which makes passes at compilers)
6922 written by James Hacker.
6924 @var{signature of Ty Coon}, 1 April 1989
6925 Ty Coon, President of Vice
6928 This General Public License does not permit incorporating your program into
6929 proprietary programs. If your program is a subroutine library, you may
6930 consider it more useful to permit linking proprietary applications with the
6931 library. If this is what you want to do, use the GNU Library General
6932 Public License instead of this License.