1 This is Info file as.info, produced by Makeinfo-1.55 from the input
5 * As:: The GNU assembler.
8 This file documents the GNU Assembler "as".
10 Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided also
18 that the section entitled "GNU General Public License" is included
19 exactly as in the original, and provided that the entire resulting
20 derived work is distributed under the terms of a permission notice
21 identical to this one.
23 Permission is granted to copy and distribute translations of this
24 manual into another language, under the above conditions for modified
25 versions, except that the section entitled "GNU General Public License"
26 may be included in a translation approved by the Free Software
27 Foundation instead of in the original English.
30 File: as.info, Node: Top, Next: Overview, Prev: (DIR), Up: (DIR)
35 This file is a user guide to the GNU assembler `as'.
40 * Invoking:: Command-Line Options
42 * Sections:: Sections and Relocation
44 * Expressions:: Expressions
45 * Pseudo Ops:: Assembler Directives
46 * Machine Dependencies:: Machine Dependent Features
48 * Copying:: GNU GENERAL PUBLIC LICENSE
50 * Acknowledgements:: Who Did What
55 File: as.info, Node: Overview, Next: Invoking, Prev: Top, Up: Top
60 Here is a brief summary of how to invoke `as'. For details, *note
61 Comand-Line Options: Invoking..
63 as [ -a[dhlns] ] [ -D ] [ -f ]
64 [ -I PATH ] [ -K ] [ -L ]
65 [ -o OBJFILE ] [ -R ] [ -v ] [ -w ]
66 [ -Av6 | -Av7 | -Av8 | -Asparclite | -bump ]
67 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
69 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
73 Turn on listings; `-ad', omit debugging pseudo-ops from listing,
74 `-ah', include high-level source, `-al', assembly listing, `-an',
75 no forms processing, `-as', symbols. These options may be
76 combined; *e.g.*, `-aln' for assembly listing without forms
77 processing. By itself, `-a' defaults to `-ahls' -- that is, all
81 This option is accepted only for script compatibility with calls to
82 other assemblers; it has no effect on `as'.
85 "fast"--skip whitespace and comment preprocessing (assume source is
89 Add PATH to the search list for `.include' directives
92 Issue warnings when difference tables altered for long
96 Keep (in symbol table) local symbols, starting with `L'
99 Name the object-file output from `as'
102 Fold data section into text section
105 Announce `as' version
108 Suppress warning messages
111 Standard input, or source files to assemble.
113 The following options are available when as is configured for the
114 Intel 80960 processor.
116 `-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC'
117 Specify which variant of the 960 architecture is the target.
120 Add code to collect statistics about branches taken.
123 Do not alter compare-and-branch instructions for long
124 displacements; error if necessary.
126 The following options are available when as is configured for the
127 Motorola 68000 series.
130 Shorten references to undefined symbols, to one word instead of
133 `-m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040'
134 `| -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32'
135 Specify what processor in the 68000 family is the target. The
136 default is normally the 68020, but this can be changed at
139 `-m68881 | -m68882 | -mno-68881 | -mno-68882'
140 The target machine does (or does not) have a floating-point
141 coprocessor. The default is to assume a coprocessor for 68020,
142 68030, and cpu32. Although the basic 68000 is not compatible with
143 the 68881, a combination of the two can be specified, since it's
144 possible to do emulation of the coprocessor instructions with the
147 `-m68851 | -mno-68851'
148 The target machine does (or does not) have a memory-management
149 unit coprocessor. The default is to assume an MMU for 68020 and
152 The following options are available when `as' is configured for the
155 `-Av6 | -Av7 | -Av8 | -Asparclite'
156 Explicitly select a variant of the SPARC architecture.
159 Warn when the assembler switches to another architecture.
163 * Manual:: Structure of this Manual
164 * GNU Assembler:: as, the GNU Assembler
165 * Object Formats:: Object File Formats
166 * Command Line:: Command Line
167 * Input Files:: Input Files
168 * Object:: Output (Object) File
169 * Errors:: Error and Warning Messages
172 File: as.info, Node: Manual, Next: GNU Assembler, Up: Overview
174 Structure of this Manual
175 ========================
177 This manual is intended to describe what you need to know to use GNU
178 `as'. We cover the syntax expected in source files, including notation
179 for symbols, constants, and expressions; the directives that `as'
180 understands; and of course how to invoke `as'.
182 This manual also describes some of the machine-dependent features of
183 various flavors of the assembler.
185 On the other hand, this manual is *not* intended as an introduction
186 to programming in assembly language--let alone programming in general!
187 In a similar vein, we make no attempt to introduce the machine
188 architecture; we do *not* describe the instruction set, standard
189 mnemonics, registers or addressing modes that are standard to a
190 particular architecture. You may want to consult the manufacturer's
191 machine architecture manual for this information.
194 File: as.info, Node: GNU Assembler, Next: Object Formats, Prev: Manual, Up: Overview
196 as, the GNU Assembler
197 =====================
199 GNU `as' is really a family of assemblers. If you use (or have
200 used) the GNU assembler on one architecture, you should find a fairly
201 similar environment when you use it on another architecture. Each
202 version has much in common with the others, including object file
203 formats, most assembler directives (often called "pseudo-ops") and
206 `as' is primarily intended to assemble the output of the GNU C
207 compiler `gcc' for use by the linker `ld'. Nevertheless, we've tried
208 to make `as' assemble correctly everything that other assemblers for
209 the same machine would assemble. Any exceptions are documented
210 explicitly (*note Machine Dependencies::.). This doesn't mean `as'
211 always uses the same syntax as another assembler for the same
212 architecture; for example, we know of several incompatible versions of
213 680x0 assembly language syntax.
215 Unlike older assemblers, `as' is designed to assemble a source
216 program in one pass of the source file. This has a subtle impact on the
217 `.org' directive (*note `.org': Org.).
220 File: as.info, Node: Object Formats, Next: Command Line, Prev: GNU Assembler, Up: Overview
225 The GNU assembler can be configured to produce several alternative
226 object file formats. For the most part, this does not affect how you
227 write assembly language programs; but directives for debugging symbols
228 are typically different in different file formats. *Note Symbol
229 Attributes: Symbol Attributes.
232 File: as.info, Node: Command Line, Next: Input Files, Prev: Object Formats, Up: Overview
237 After the program name `as', the command line may contain options
238 and file names. Options may appear in any order, and may be before,
239 after, or between file names. The order of file names is significant.
241 `--' (two hyphens) by itself names the standard input file
242 explicitly, as one of the files for `as' to assemble.
244 Except for `--' any command line argument that begins with a hyphen
245 (`-') is an option. Each option changes the behavior of `as'. No
246 option changes the way another option works. An option is a `-'
247 followed by one or more letters; the case of the letter is important.
248 All options are optional.
250 Some options expect exactly one file name to follow them. The file
251 name may either immediately follow the option's letter (compatible with
252 older assemblers) or it may be the next command argument (GNU
253 standard). These two command lines are equivalent:
255 as -o my-object-file.o mumble.s
256 as -omy-object-file.o mumble.s
259 File: as.info, Node: Input Files, Next: Object, Prev: Command Line, Up: Overview
264 We use the phrase "source program", abbreviated "source", to
265 describe the program input to one run of `as'. The program may be in
266 one or more files; how the source is partitioned into files doesn't
267 change the meaning of the source.
269 The source program is a concatenation of the text in all the files,
270 in the order specified.
272 Each time you run `as' it assembles exactly one source program. The
273 source program is made up of one or more files. (The standard input is
276 You give `as' a command line that has zero or more input file names.
277 The input files are read (from left file name to right). A command
278 line argument (in any position) that has no special meaning is taken to
279 be an input file name.
281 If you give `as' no file names it attempts to read one input file
282 from the `as' standard input, which is normally your terminal. You may
283 have to type ctl-D to tell `as' there is no more program to assemble.
285 Use `--' if you need to explicitly name the standard input file in
288 If the source is empty, `as' will produce a small, empty object file.
290 Filenames and Line-numbers
291 --------------------------
293 There are two ways of locating a line in the input file (or files)
294 and either may be used in reporting error messages. One way refers to
295 a line number in a physical file; the other refers to a line number in a
296 "logical" file. *Note Error and Warning Messages: Errors.
298 "Physical files" are those files named in the command line given to
301 "Logical files" are simply names declared explicitly by assembler
302 directives; they bear no relation to physical files. Logical file names
303 help error messages reflect the original source file, when `as' source
304 is itself synthesized from other files. *Note `.app-file': App-File.
307 File: as.info, Node: Object, Next: Errors, Prev: Input Files, Up: Overview
312 Every time you run `as' it produces an output file, which is your
313 assembly language program translated into numbers. This file is the
314 object file, named `b.out', if `as' is configured for the Intel 80960,
315 or unless you tell `as' to give it another name by using the `-o'
316 option. Conventionally, object file names end with `.o'. The default
317 name of `a.out' is used for historical reasons: older assemblers were
318 capable of assembling self-contained programs directly into a runnable
319 program. (For some formats, this isn't currently possible, but it can
320 be done for `a.out' format.)
322 The object file is meant for input to the linker `ld'. It contains
323 assembled program code, information to help `ld' integrate the
324 assembled program into a runnable file, and (optionally) symbolic
325 information for the debugger.
328 File: as.info, Node: Errors, Prev: Object, Up: Overview
330 Error and Warning Messages
331 ==========================
333 `as' may write warnings and error messages to the standard error
334 file (usually your terminal). This should not happen when a compiler
335 runs `as' automatically. Warnings report an assumption made so that
336 `as' could keep assembling a flawed program; errors report a grave
337 problem that stops the assembly.
339 Warning messages have the format
341 file_name:NNN:Warning Message Text
343 (where NNN is a line number). If a logical file name has been given
344 (*note `.app-file': App-File.) it is used for the filename, otherwise
345 the name of the current input file is used. If a logical line number
346 was given (*note `.line': Line.) then it is used to calculate the
347 number printed, otherwise the actual line in the current source file is
348 printed. The message text is intended to be self explanatory (in the
349 grand Unix tradition).
351 Error messages have the format
352 file_name:NNN:FATAL:Error Message Text
353 The file name and line number are derived as for warning messages.
354 The actual message text may be rather less explanatory because many of
355 them aren't supposed to happen.
358 File: as.info, Node: Invoking, Next: Syntax, Prev: Overview, Up: Top
363 This chapter describes command-line options available in *all*
364 versions of the GNU assembler; *note Machine Dependencies::., for
365 options specific to particular machine architectures.
367 If you are invoking `as' via the GNU C compiler (version 2), you can
368 use the `-Wa' option to pass arguments through to the assembler. The
369 assembler arguments must be separated from each other (and the `-Wa')
370 by commas. For example:
372 gcc -c -g -O -Wa,-alh,-L file.c
374 will cause a listing to be emitted to standard output with high-level
377 Many compiler command-line options, such as `-R' and many
378 machine-specific options, will be automatically be passed to the
379 assembler by the compiler, so usually you do not need to use this `-Wa'
384 * a:: -a[dhlns] enable listings
385 * D:: -D for compatibility
386 * f:: -f to work faster
387 * I:: -I for .include search path
389 * K:: -K for difference tables
391 * L:: -L to retain local labels
392 * o:: -o to name the object file
393 * R:: -R to join data and text sections
394 * v:: -v to announce version
395 * W:: -W to suppress warnings
398 File: as.info, Node: a, Next: D, Up: Invoking
400 Enable Listings: `-a[dhlns]'
401 ============================
403 These options enable listing output from the assembler. By itself,
404 `-a' requests high-level, assembly, and symbols listing. Other letters
405 may be used to select specific options for the list: `-ah' requests a
406 high-level language listing, `-al' requests an output-program assembly
407 listing, and `-as' requests a symbol table listing. High-level
408 listings require that a compiler debugging option like `-g' be used,
409 and that assembly listings (`-al') be requested also.
411 The `-ad' option may be used to omit debugging pseudo-ops from the
414 Once you have specified one of these options, you can further control
415 listing output and its appearance using the directives `.list',
416 `.nolist', `.psize', `.eject', `.title', and `.sbttl'. The `-an'
417 option turns off all forms processing. If you do not request listing
418 output with one of the `-a' options, the listing-control directives
421 The letters after `-a' may be combined into one option, *e.g.*,
425 File: as.info, Node: D, Next: f, Prev: a, Up: Invoking
430 This option has no effect whatsoever, but it is accepted to make it
431 more likely that scripts written for other assemblers will also work
435 File: as.info, Node: f, Next: I, Prev: D, Up: Invoking
440 `-f' should only be used when assembling programs written by a
441 (trusted) compiler. `-f' stops the assembler from doing whitespace and
442 comment pre-processing on the input file(s) before assembling them.
443 *Note Pre-processing: Pre-processing.
445 *Warning:* if the files actually need to be pre-processed (if they
446 contain comments, for example), `as' will not work correctly if
450 File: as.info, Node: I, Next: K, Prev: f, Up: Invoking
452 `.include' search path: `-I' PATH
453 =================================
455 Use this option to add a PATH to the list of directories `as' will
456 search for files specified in `.include' directives (*note `.include':
457 Include.). You may use `-I' as many times as necessary to include a
458 variety of paths. The current working directory is always searched
459 first; after that, `as' searches any `-I' directories in the same order
460 as they were specified (left to right) on the command line.
463 File: as.info, Node: K, Next: L, Prev: I, Up: Invoking
465 Difference Tables: `-K'
466 =======================
468 `as' sometimes alters the code emitted for directives of the form
469 `.word SYM1-SYM2'; *note `.word': Word.. You can use the `-K' option
470 if you want a warning issued when this is done.
473 File: as.info, Node: L, Next: o, Prev: K, Up: Invoking
475 Include Local Labels: `-L'
476 ==========================
478 Labels beginning with `L' (upper case only) are called "local
479 labels". *Note Symbol Names::. Normally you don't see such labels when
480 debugging, because they are intended for the use of programs (like
481 compilers) that compose assembler programs, not for your notice.
482 Normally both `as' and `ld' discard such labels, so you don't normally
485 This option tells `as' to retain those `L...' symbols in the object
486 file. Usually if you do this you also tell the linker `ld' to preserve
487 symbols whose names begin with `L'.
490 File: as.info, Node: o, Next: R, Prev: L, Up: Invoking
492 Name the Object File: `-o'
493 ==========================
495 There is always one object file output when you run `as'. By
496 default it has the name `a.out' (or `b.out', for Intel 960 targets
497 only). You use this option (which takes exactly one filename) to give
498 the object file a different name.
500 Whatever the object file is called, `as' will overwrite any existing
501 file of the same name.
504 File: as.info, Node: R, Next: v, Prev: o, Up: Invoking
506 Join Data and Text Sections: `-R'
507 =================================
509 `-R' tells `as' to write the object file as if all data-section data
510 lives in the text section. This is only done at the very last moment:
511 your binary data are the same, but data section parts are relocated
512 differently. The data section part of your object file is zero bytes
513 long because all its bytes are appended to the text section. (*Note
514 Sections and Relocation: Sections.)
516 When you specify `-R' it would be possible to generate shorter
517 address displacements (because we don't have to cross between text and
518 data section). We refrain from doing this simply for compatibility with
519 older versions of `as'. In future, `-R' may work this way.
521 When `as' is configured for COFF output, this option is only useful
522 if you use sections named `.text' and `.data'.
525 File: as.info, Node: v, Next: W, Prev: R, Up: Invoking
527 Announce Version: `-v'
528 ======================
530 You can find out what version of as is running by including the
531 option `-v' (which you can also spell as `-version') on the command
535 File: as.info, Node: W, Prev: v, Up: Invoking
537 Suppress Warnings: `-W'
538 =======================
540 `as' should never give a warning or error message when assembling
541 compiler output. But programs written by people often cause `as' to
542 give a warning that a particular assumption was made. All such
543 warnings are directed to the standard error file. If you use this
544 option, no warnings are issued. This option only affects the warning
545 messages: it does not change any particular of how `as' assembles your
546 file. Errors, which stop the assembly, are still reported.
549 File: as.info, Node: Syntax, Next: Sections, Prev: Invoking, Up: Top
554 This chapter describes the machine-independent syntax allowed in a
555 source file. `as' syntax is similar to what many other assemblers use;
556 it is inspired by the BSD 4.2 assembler, except that `as' does not
557 assemble Vax bit-fields.
561 * Pre-processing:: Pre-processing
562 * Whitespace:: Whitespace
563 * Comments:: Comments
564 * Symbol Intro:: Symbols
565 * Statements:: Statements
566 * Constants:: Constants
569 File: as.info, Node: Pre-processing, Next: Whitespace, Up: Syntax
574 The `as' internal pre-processor:
575 * adjusts and removes extra whitespace. It leaves one space or tab
576 before the keywords on a line, and turns any other whitespace on
577 the line into a single space.
579 * removes all comments, replacing them with a single space, or an
580 appropriate number of newlines.
582 * converts character constants into the appropriate numeric values.
584 Note that it does not do macro processing, include file handling, or
585 anything else you may get from your C compiler's pre-processor. You can
586 do include file processing with the `.include' directive (*note
587 `.include': Include.). Other "CPP" style pre-processing can be done
588 with the GNU C compiler, by giving the input file a `.S' suffix; see
589 the compiler documentation for details.
591 Excess whitespace, comments, and character constants cannot be used
592 in the portions of the input text that are not pre-processed.
594 If the first line of an input file is `#NO_APP' or the `-f' option
595 is given, the input file will not be pre-processed. Within such an
596 input file, parts of the file can be pre-processed by putting a line
597 that says `#APP' before the text that should be pre-processed, and
598 putting a line that says `#NO_APP' after them. This feature is mainly
599 intend to support `asm' statements in compilers whose output normally
600 does not need to be pre-processed.
603 File: as.info, Node: Whitespace, Next: Comments, Prev: Pre-processing, Up: Syntax
608 "Whitespace" is one or more blanks or tabs, in any order.
609 Whitespace is used to separate symbols, and to make programs neater for
610 people to read. Unless within character constants (*note Character
611 Constants: Characters.), any whitespace means the same as exactly one
615 File: as.info, Node: Comments, Next: Symbol Intro, Prev: Whitespace, Up: Syntax
620 There are two ways of rendering comments to `as'. In both cases the
621 comment is equivalent to one space.
623 Anything from `/*' through the next `*/' is a comment. This means
624 you may not nest these comments.
627 The only way to include a newline ('\n') in a comment
628 is to use this sort of comment.
631 /* This sort of comment does not nest. */
633 Anything from the "line comment" character to the next newline is
634 considered a comment and is ignored. The line comment character is `#'
635 on the Vax; `#' on the i960; `!' on the SPARC; `|' on the 680x0; `;'
636 for the AMD 29K family; `;' for the H8/300 family; `!' for the H8/500
637 family; `!' for the Hitachi SH; `!' for the Z8000; see *Note Machine
640 On some machines there are two different line comment characters.
641 One will only begin a comment if it is the first non-whitespace
642 character on a line, while the other will always begin a comment.
644 To be compatible with past assemblers, a special interpretation is
645 given to lines that begin with `#'. Following the `#' an absolute
646 expression (*note Expressions::.) is expected: this will be the
647 logical line number of the next line. Then a string (*Note Strings::.)
648 is allowed: if present it is a new logical file name. The rest of the
649 line, if any, should be whitespace.
651 If the first non-whitespace characters on the line are not numeric,
652 the line is ignored. (Just like a comment.)
653 # This is an ordinary comment.
654 # 42-6 "new_file_name" # New logical file name
655 # This is logical line # 36.
656 This feature is deprecated, and may disappear from future versions
660 File: as.info, Node: Symbol Intro, Next: Statements, Prev: Comments, Up: Syntax
665 A "symbol" is one or more characters chosen from the set of all
666 letters (both upper and lower case), digits and the three characters
667 `_.$'. On most machines, you can also use `$' in symbol names;
668 exceptions are noted in *Note Machine Dependencies::. No symbol may
669 begin with a digit. Case is significant. There is no length limit:
670 all characters are significant. Symbols are delimited by characters
671 not in that set, or by the beginning of a file (since the source
672 program must end with a newline, the end of a file is not a possible
673 symbol delimiter). *Note Symbols::.
676 File: as.info, Node: Statements, Next: Constants, Prev: Symbol Intro, Up: Syntax
681 A "statement" ends at a newline character (`\n') or line separator
682 character. (The line separator is usually `;', unless this conflicts
683 with the comment character; *note Machine Dependencies::..) The
684 newline or separator character is considered part of the preceding
685 statement. Newlines and separators within character constants are an
686 exception: they don't end statements.
688 It is an error to end any statement with end-of-file: the last
689 character of any input file should be a newline.
691 You may write a statement on more than one line if you put a
692 backslash (`\') immediately in front of any newlines within the
693 statement. When `as' reads a backslashed newline both characters are
694 ignored. You can even put backslashed newlines in the middle of symbol
695 names without changing the meaning of your source program.
697 An empty statement is allowed, and may include whitespace. It is
700 A statement begins with zero or more labels, optionally followed by a
701 key symbol which determines what kind of statement it is. The key
702 symbol determines the syntax of the rest of the statement. If the
703 symbol begins with a dot `.' then the statement is an assembler
704 directive: typically valid for any computer. If the symbol begins with
705 a letter the statement is an assembly language "instruction": it will
706 assemble into a machine language instruction. Different versions of
707 `as' for different computers will recognize different instructions. In
708 fact, the same symbol may represent a different instruction in a
709 different computer's assembly language.
711 A label is a symbol immediately followed by a colon (`:').
712 Whitespace before a label or after a colon is permitted, but you may not
713 have whitespace between a label's symbol and its colon. *Note Labels::.
715 label: .directive followed by something
716 another_label: # This is an empty statement.
717 instruction operand_1, operand_2, ...
720 File: as.info, Node: Constants, Prev: Statements, Up: Syntax
725 A constant is a number, written so that its value is known by
726 inspection, without knowing any context. Like this:
727 .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
728 .ascii "Ring the bell\7" # A string constant.
729 .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
730 .float 0f-314159265358979323846264338327\
731 95028841971.693993751E-40 # - pi, a flonum.
735 * Characters:: Character Constants
736 * Numbers:: Number Constants
739 File: as.info, Node: Characters, Next: Numbers, Up: Constants
744 There are two kinds of character constants. A "character" stands
745 for one character in one byte and its value may be used in numeric
746 expressions. String constants (properly called string *literals*) are
747 potentially many bytes and their values may not be used in arithmetic
756 File: as.info, Node: Strings, Next: Chars, Up: Characters
761 A "string" is written between double-quotes. It may contain
762 double-quotes or null characters. The way to get special characters
763 into a string is to "escape" these characters: precede them with a
764 backslash `\' character. For example `\\' represents one backslash:
765 the first `\' is an escape which tells `as' to interpret the second
766 character literally as a backslash (which prevents `as' from
767 recognizing the second `\' as an escape character). The complete list
771 Mnemonic for backspace; for ASCII this is octal code 010.
774 Mnemonic for FormFeed; for ASCII this is octal code 014.
777 Mnemonic for newline; for ASCII this is octal code 012.
780 Mnemonic for carriage-Return; for ASCII this is octal code 015.
783 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
785 `\ DIGIT DIGIT DIGIT'
786 An octal character code. The numeric code is 3 octal digits. For
787 compatibility with other Unix systems, 8 and 9 are accepted as
788 digits: for example, `\008' has the value 010, and `\009' the
792 Represents one `\' character.
795 Represents one `"' character. Needed in strings to represent this
796 character, because an unescaped `"' would end the string.
799 Any other character when escaped by `\' will give a warning, but
800 assemble as if the `\' was not present. The idea is that if you
801 used an escape sequence you clearly didn't want the literal
802 interpretation of the following character. However `as' has no
803 other interpretation, so `as' knows it is giving you the wrong
804 code and warns you of the fact.
806 Which characters are escapable, and what those escapes represent,
807 varies widely among assemblers. The current set is what we think the
808 BSD 4.2 assembler recognizes, and is a subset of what most C compilers
809 recognize. If you are in doubt, don't use an escape sequence.
812 File: as.info, Node: Chars, Prev: Strings, Up: Characters
817 A single character may be written as a single quote immediately
818 followed by that character. The same escapes apply to characters as to
819 strings. So if you want to write the character backslash, you must
820 write `'\\' where the first `\' escapes the second `\'. As you can
821 see, the quote is an acute accent, not a grave accent. A newline
822 immediately following an acute accent is taken as a literal character
823 and does not count as the end of a statement. The value of a character
824 constant in a numeric expression is the machine's byte-wide code for
825 that character. `as' assumes your character code is ASCII: `'A' means
826 65, `'B' means 66, and so on.
829 File: as.info, Node: Numbers, Prev: Characters, Up: Constants
834 `as' distinguishes three kinds of numbers according to how they are
835 stored in the target machine. *Integers* are numbers that would fit
836 into an `int' in the C language. *Bignums* are integers, but they are
837 stored in more than 32 bits. *Flonums* are floating point numbers,
842 * Integers:: Integers
847 File: as.info, Node: Integers, Next: Bignums, Up: Numbers
852 A binary integer is `0b' or `0B' followed by zero or more of the
855 An octal integer is `0' followed by zero or more of the octal digits
858 A decimal integer starts with a non-zero digit followed by zero or
859 more digits (`0123456789').
861 A hexadecimal integer is `0x' or `0X' followed by one or more
862 hexadecimal digits chosen from `0123456789abcdefABCDEF'.
864 Integers have the usual values. To denote a negative integer, use
865 the prefix operator `-' discussed under expressions (*note Prefix
866 Operators: Prefix Ops.).
869 File: as.info, Node: Bignums, Next: Flonums, Prev: Integers, Up: Numbers
874 A "bignum" has the same syntax and semantics as an integer except
875 that the number (or its negative) takes more than 32 bits to represent
876 in binary. The distinction is made because in some places integers are
877 permitted while bignums are not.
880 File: as.info, Node: Flonums, Prev: Bignums, Up: Numbers
885 A "flonum" represents a floating point number. The translation is
886 indirect: a decimal floating point number from the text is converted by
887 `as' to a generic binary floating point number of more than sufficient
888 precision. This generic floating point number is converted to a
889 particular computer's floating point format (or formats) by a portion
890 of `as' specialized to that computer.
892 A flonum is written by writing (in order)
895 * A letter, to tell `as' the rest of the number is a flonum. `e' is
896 recommended. Case is not important.
898 On the H8/300, H8/500, Hitachi SH, and AMD 29K architectures, the
899 letter must be one of the letters `DFPRSX' (in upper or lower
902 On the Intel 960 architecture, the letter must be one of the
903 letters `DFT' (in upper or lower case).
905 * An optional sign: either `+' or `-'.
907 * An optional "integer part": zero or more decimal digits.
909 * An optional "fractional part": `.' followed by zero or more
912 * An optional exponent, consisting of:
916 * Optional sign: either `+' or `-'.
918 * One or more decimal digits.
920 At least one of the integer part or the fractional part must be
921 present. The floating point number has the usual base-10 value.
923 `as' does all processing using integers. Flonums are computed
924 independently of any floating point hardware in the computer running
928 File: as.info, Node: Sections, Next: Symbols, Prev: Syntax, Up: Top
930 Sections and Relocation
931 ***********************
935 * Secs Background:: Background
936 * Ld Sections:: ld Sections
937 * As Sections:: as Internal Sections
938 * Sub-Sections:: Sub-Sections
942 File: as.info, Node: Secs Background, Next: Ld Sections, Up: Sections
947 Roughly, a section is a range of addresses, with no gaps; all data
948 "in" those addresses is treated the same for some particular purpose.
949 For example there may be a "read only" section.
951 The linker `ld' reads many object files (partial programs) and
952 combines their contents to form a runnable program. When `as' emits an
953 object file, the partial program is assumed to start at address 0.
954 `ld' will assign the final addresses the partial program occupies, so
955 that different partial programs don't overlap. This is actually an
956 over-simplification, but it will suffice to explain how `as' uses
959 `ld' moves blocks of bytes of your program to their run-time
960 addresses. These blocks slide to their run-time addresses as rigid
961 units; their length does not change and neither does the order of bytes
962 within them. Such a rigid unit is called a *section*. Assigning
963 run-time addresses to sections is called "relocation". It includes the
964 task of adjusting mentions of object-file addresses so they refer to
965 the proper run-time addresses. For the H8/300 and H8/500, and for the
966 Hitachi SH, `as' pads sections if needed to ensure they end on a word
967 (sixteen bit) boundary.
969 An object file written by `as' has at least three sections, any of
970 which may be empty. These are named "text", "data" and "bss" sections.
972 When it generates COFF output, `as' can also generate whatever other
973 named sections you specify using the `.section' directive (*note
974 `.section': Section.). If you don't use any directives that place
975 output in the `.text' or `.data' sections, these sections will still
976 exist, but will be empty.
978 Within the object file, the text section starts at address `0', the
979 data section follows, and the bss section follows the data section.
981 To let `ld' know which data will change when the sections are
982 relocated, and how to change that data, `as' also writes to the object
983 file details of the relocation needed. To perform relocation `ld' must
984 know, each time an address in the object file is mentioned:
985 * Where in the object file is the beginning of this reference to an
988 * How long (in bytes) is this reference?
990 * Which section does the address refer to? What is the numeric
992 (ADDRESS) - (START-ADDRESS OF SECTION)?
994 * Is the reference to an address "Program-Counter relative"?
996 In fact, every address `as' ever uses is expressed as
997 (SECTION) + (OFFSET INTO SECTION)
999 Further, every expression `as' computes is of this section-relative
1000 nature. "Absolute expression" means an expression with section
1001 "absolute" (*note Ld Sections::.). A "pass1 expression" means an
1002 expression with section "pass1" (*note as Internal Sections: As
1003 Sections.). In this manual we use the notation {SECNAME N} to mean
1004 "offset N into section SECNAME".
1006 Apart from text, data and bss sections you need to know about the
1007 "absolute" section. When `ld' mixes partial programs, addresses in the
1008 absolute section remain unchanged. For example, address `{absolute 0}'
1009 is "relocated" to run-time address 0 by `ld'. Although two partial
1010 programs' data sections will not overlap addresses after linking, *by
1011 definition* their absolute sections will overlap. Address `{absolute
1012 239}' in one partial program will always be the same address when the
1013 program is running as address `{absolute 239}' in any other partial
1016 The idea of sections is extended to the "undefined" section. Any
1017 address whose section is unknown at assembly time is by definition
1018 rendered {undefined U}--where U will be filled in later. Since numbers
1019 are always defined, the only way to generate an undefined address is to
1020 mention an undefined symbol. A reference to a named common block would
1021 be such a symbol: its value is unknown at assembly time so it has
1022 section *undefined*.
1024 By analogy the word *section* is used to describe groups of sections
1025 in the linked program. `ld' puts all partial programs' text sections
1026 in contiguous addresses in the linked program. It is customary to
1027 refer to the *text section* of a program, meaning all the addresses of
1028 all partial program's text sections. Likewise for data and bss
1031 Some sections are manipulated by `ld'; others are invented for use
1032 of `as' and have no meaning except during assembly.
1035 File: as.info, Node: Ld Sections, Next: As Sections, Prev: Secs Background, Up: Sections
1040 `ld' deals with just four kinds of sections, summarized below.
1045 These sections hold your program. `as' and `ld' treat them as
1046 separate but equal sections. Anything you can say of one section
1047 is true another. When the program is running, however, it is
1048 customary for the text section to be unalterable. The text
1049 section is often shared among processes: it will contain
1050 instructions, constants and the like. The data section of a
1051 running program is usually alterable: for example, C variables
1052 would be stored in the data section.
1055 This section contains zeroed bytes when your program begins
1056 running. It is used to hold unitialized variables or common
1057 storage. The length of each partial program's bss section is
1058 important, but because it starts out containing zeroed bytes there
1059 is no need to store explicit zero bytes in the object file. The
1060 bss section was invented to eliminate those explicit zeros from
1064 Address 0 of this section is always "relocated" to runtime address
1065 0. This is useful if you want to refer to an address that `ld'
1066 must not change when relocating. In this sense we speak of
1067 absolute addresses being "unrelocatable": they don't change during
1071 This "section" is a catch-all for address references to objects
1072 not in the preceding sections.
1074 An idealized example of three relocatable sections follows. The
1075 example uses the traditional section names `.text' and `.data'. Memory
1076 addresses are on the horizontal axis.
1079 partial program # 1: |ttttt|dddd|00|
1086 partial program # 2: |TTT|DDD|000|
1089 +--+---+-----+--+----+---+-----+~~
1090 linked program: | |TTT|ttttt| |dddd|DDD|00000|
1091 +--+---+-----+--+----+---+-----+~~
1096 File: as.info, Node: As Sections, Next: Sub-Sections, Prev: Ld Sections, Up: Sections
1098 as Internal Sections
1099 ====================
1101 These sections are meant only for the internal use of `as'. They
1102 have no meaning at run-time. You don't really need to know about these
1103 sections for most purposes; but they can be mentioned in `as' warning
1104 messages, so it might be helpful to have an idea of their meanings to
1105 `as'. These sections are used to permit the value of every expression
1106 in your assembly language program to be a section-relative address.
1108 ASSEMBLER-INTERNAL-LOGIC-ERROR!
1109 An internal assembler logic error has been found. This means
1110 there is a bug in the assembler.
1113 The assembler stores complex expression internally as combinations
1114 of symbols. When it needs to represent an expression as a symbol,
1115 it puts it in the expr section.
1118 File: as.info, Node: Sub-Sections, Next: bss, Prev: As Sections, Up: Sections
1123 Assembled bytes conventionally fall into two sections: text and data.
1124 You may have separate groups of data in named sections that you want to
1125 end up near to each other in the object file, even though they are not
1126 contiguous in the assembler source. `as' allows you to use
1127 "subsections" for this purpose. Within each section, there can be
1128 numbered subsections with values from 0 to 8192. Objects assembled
1129 into the same subsection will be grouped with other objects in the same
1130 subsection when they are all put into the object file. For example, a
1131 compiler might want to store constants in the text section, but might
1132 not want to have them interspersed with the program being assembled.
1133 In this case, the compiler could issue a `.text 0' before each section
1134 of code being output, and a `.text 1' before each group of constants
1137 Subsections are optional. If you don't use subsections, everything
1138 will be stored in subsection number zero.
1140 Each subsection is zero-padded up to a multiple of four bytes.
1141 (Subsections may be padded a different amount on different flavors of
1144 Subsections appear in your object file in numeric order, lowest
1145 numbered to highest. (All this to be compatible with other people's
1146 assemblers.) The object file contains no representation of subsections;
1147 `ld' and other programs that manipulate object files will see no trace
1148 of them. They just see all your text subsections as a text section,
1149 and all your data subsections as a data section.
1151 To specify which subsection you want subsequent statements assembled
1152 into, use a numeric argument to specify it, in a `.text EXPRESSION' or
1153 a `.data EXPRESSION' statement. When generating COFF output, you can
1154 also use an extra subsection argument with arbitrary named sections:
1155 `.section NAME, EXPRESSION'. EXPRESSION should be an absolute
1156 expression. (*Note Expressions::.) If you just say `.text' then
1157 `.text 0' is assumed. Likewise `.data' means `.data 0'. Assembly
1158 begins in `text 0'. For instance:
1159 .text 0 # The default subsection is text 0 anyway.
1160 .ascii "This lives in the first text subsection. *"
1162 .ascii "But this lives in the second text subsection."
1164 .ascii "This lives in the data section,"
1165 .ascii "in the first data subsection."
1167 .ascii "This lives in the first text section,"
1168 .ascii "immediately following the asterisk (*)."
1170 Each section has a "location counter" incremented by one for every
1171 byte assembled into that section. Because subsections are merely a
1172 convenience restricted to `as' there is no concept of a subsection
1173 location counter. There is no way to directly manipulate a location
1174 counter--but the `.align' directive will change it, and any label
1175 definition will capture its current value. The location counter of the
1176 section that statements are being assembled into is said to be the
1177 "active" location counter.
1180 File: as.info, Node: bss, Prev: Sub-Sections, Up: Sections
1185 The bss section is used for local common variable storage. You may
1186 allocate address space in the bss section, but you may not dictate data
1187 to load into it before your program executes. When your program starts
1188 running, all the contents of the bss section are zeroed bytes.
1190 Addresses in the bss section are allocated with special directives;
1191 you may not assemble anything directly into the bss section. Hence
1192 there are no bss subsections. *Note `.comm': Comm, *note `.lcomm':
1196 File: as.info, Node: Symbols, Next: Expressions, Prev: Sections, Up: Top
1201 Symbols are a central concept: the programmer uses symbols to name
1202 things, the linker uses symbols to link, and the debugger uses symbols
1205 *Warning:* `as' does not place symbols in the object file in the
1206 same order they were declared. This may break some debuggers.
1211 * Setting Symbols:: Giving Symbols Other Values
1212 * Symbol Names:: Symbol Names
1213 * Dot:: The Special Dot Symbol
1214 * Symbol Attributes:: Symbol Attributes
1217 File: as.info, Node: Labels, Next: Setting Symbols, Up: Symbols
1222 A "label" is written as a symbol immediately followed by a colon
1223 `:'. The symbol then represents the current value of the active
1224 location counter, and is, for example, a suitable instruction operand.
1225 You are warned if you use the same symbol to represent two different
1226 locations: the first definition overrides any other definitions.
1229 File: as.info, Node: Setting Symbols, Next: Symbol Names, Prev: Labels, Up: Symbols
1231 Giving Symbols Other Values
1232 ===========================
1234 A symbol can be given an arbitrary value by writing a symbol,
1235 followed by an equals sign `=', followed by an expression (*note
1236 Expressions::.). This is equivalent to using the `.set' directive.
1240 File: as.info, Node: Symbol Names, Next: Dot, Prev: Setting Symbols, Up: Symbols
1245 Symbol names begin with a letter or with one of `._'. On most
1246 machines, you can also use `$' in symbol names; exceptions are noted in
1247 *Note Machine Dependencies::. That character may be followed by any
1248 string of digits, letters, dollar signs (unless otherwise noted in
1249 *Note Machine Dependencies::), and underscores. For the AMD 29K
1250 family, `?' is also allowed in the body of a symbol name, though not at
1253 Case of letters is significant: `foo' is a different symbol name
1256 Each symbol has exactly one name. Each name in an assembly language
1257 program refers to exactly one symbol. You may use that symbol name any
1258 number of times in a program.
1263 Local symbols help compilers and programmers use names temporarily.
1264 There are ten local symbol names, which are re-used throughout the
1265 program. You may refer to them using the names `0' `1' ... `9'. To
1266 define a local symbol, write a label of the form `N:' (where N
1267 represents any digit). To refer to the most recent previous definition
1268 of that symbol write `Nb', using the same digit as when you defined the
1269 label. To refer to the next definition of a local label, write
1270 `Nf'--where N gives you a choice of 10 forward references. The `b'
1271 stands for "backwards" and the `f' stands for "forwards".
1273 Local symbols are not emitted by the current GNU C compiler.
1275 There is no restriction on how you can use these labels, but
1276 remember that at any point in the assembly you can refer to at most 10
1277 prior local labels and to at most 10 forward local labels.
1279 Local symbol names are only a notation device. They are immediately
1280 transformed into more conventional symbol names before the assembler
1281 uses them. The symbol names stored in the symbol table, appearing in
1282 error messages and optionally emitted to the object file have these
1286 All local labels begin with `L'. Normally both `as' and `ld'
1287 forget symbols that start with `L'. These labels are used for
1288 symbols you are never intended to see. If you give the `-L'
1289 option then `as' will retain these symbols in the object file. If
1290 you also instruct `ld' to retain these symbols, you may use them
1294 If the label is written `0:' then the digit is `0'. If the label
1295 is written `1:' then the digit is `1'. And so on up through `9:'.
1298 This unusual character is included so you don't accidentally invent
1299 a symbol of the same name. The character has ASCII value `\001'.
1302 This is a serial number to keep the labels distinct. The first
1303 `0:' gets the number `1'; The 15th `0:' gets the number `15';
1304 *etc.*. Likewise for the other labels `1:' through `9:'.
1306 For instance, the first `1:' is named `L
\ 1A1', the 44th `3:' is named
1310 File: as.info, Node: Dot, Next: Symbol Attributes, Prev: Symbol Names, Up: Symbols
1312 The Special Dot Symbol
1313 ======================
1315 The special symbol `.' refers to the current address that `as' is
1316 assembling into. Thus, the expression `melvin: .long .' will cause
1317 `melvin' to contain its own address. Assigning a value to `.' is
1318 treated the same as a `.org' directive. Thus, the expression `.=.+4'
1319 is the same as saying `.space 4'.