This is Info file as.info, produced by Makeinfo-1.55 from the input file as.texinfo. START-INFO-DIR-ENTRY * As:: The GNU assembler. END-INFO-DIR-ENTRY This file documents the GNU Assembler "as". Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: as.info, Node: Symbol Attributes, Prev: Dot, Up: Symbols Symbol Attributes ================= Every symbol has, as well as its name, the attributes "Value" and "Type". Depending on output format, symbols can also have auxiliary attributes. If you use a symbol without defining it, `as' assumes zero for all these attributes, and probably won't warn you. This makes the symbol an externally defined symbol, which is generally what you would want. * Menu: * Symbol Value:: Value * Symbol Type:: Type * a.out Symbols:: Symbol Attributes: `a.out' * COFF Symbols:: Symbol Attributes for COFF  File: as.info, Node: Symbol Value, Next: Symbol Type, Up: Symbol Attributes Value ----- The value of a symbol is (usually) 32 bits. For a symbol which labels a location in the text, data, bss or absolute sections the value is the number of addresses from the start of that section to the label. Naturally for text, data and bss sections the value of a symbol changes as `ld' changes section base addresses during linking. Absolute symbols' values do not change during linking: that is why they are called absolute. The value of an undefined symbol is treated in a special way. If it is 0 then the symbol is not defined in this assembler source program, and `ld' will try to determine its value from other programs it is linked with. You make this kind of symbol simply by mentioning a symbol name without defining it. A non-zero value represents a `.comm' common declaration. The value is how much common storage to reserve, in bytes (addresses). The symbol refers to the first address of the allocated storage.  File: as.info, Node: Symbol Type, Next: a.out Symbols, Prev: Symbol Value, Up: Symbol Attributes Type ---- The type attribute of a symbol contains relocation (section) information, any flag settings indicating that a symbol is external, and (optionally), other information for linkers and debuggers. The exact format depends on the object-code output format in use.  File: as.info, Node: a.out Symbols, Next: COFF Symbols, Prev: Symbol Type, Up: Symbol Attributes Symbol Attributes: `a.out' -------------------------- * Menu: * Symbol Desc:: Descriptor * Symbol Other:: Other  File: as.info, Node: Symbol Desc, Next: Symbol Other, Up: a.out Symbols Descriptor .......... This is an arbitrary 16-bit value. You may establish a symbol's descriptor value by using a `.desc' statement (*note `.desc': Desc.). A descriptor value means nothing to `as'.  File: as.info, Node: Symbol Other, Prev: Symbol Desc, Up: a.out Symbols Other ..... This is an arbitrary 8-bit value. It means nothing to `as'.  File: as.info, Node: COFF Symbols, Prev: a.out Symbols, Up: Symbol Attributes Symbol Attributes for COFF -------------------------- The COFF format supports a multitude of auxiliary symbol attributes; like the primary symbol attributes, they are set between `.def' and `.endef' directives. Primary Attributes .................. The symbol name is set with `.def'; the value and type, respectively, with `.val' and `.type'. Auxiliary Attributes .................... The `as' directives `.dim', `.line', `.scl', `.size', and `.tag' can generate auxiliary symbol table information for COFF.  File: as.info, Node: Expressions, Next: Pseudo Ops, Prev: Symbols, Up: Top Expressions *********** An "expression" specifies an address or numeric value. Whitespace may precede and/or follow an expression. * Menu: * Empty Exprs:: Empty Expressions * Integer Exprs:: Integer Expressions  File: as.info, Node: Empty Exprs, Next: Integer Exprs, Up: Expressions Empty Expressions ================= An empty expression has no value: it is just whitespace or null. Wherever an absolute expression is required, you may omit the expression and `as' will assume a value of (absolute) 0. This is compatible with other assemblers.  File: as.info, Node: Integer Exprs, Prev: Empty Exprs, Up: Expressions Integer Expressions =================== An "integer expression" is one or more *arguments* delimited by *operators*. * Menu: * Arguments:: Arguments * Operators:: Operators * Prefix Ops:: Prefix Operators * Infix Ops:: Infix Operators  File: as.info, Node: Arguments, Next: Operators, Up: Integer Exprs Arguments --------- "Arguments" are symbols, numbers or subexpressions. In other contexts arguments are sometimes called "arithmetic operands". In this manual, to avoid confusing them with the "instruction operands" of the machine language, we use the term "argument" to refer to parts of expressions only, reserving the word "operand" to refer only to machine instruction operands. Symbols are evaluated to yield {SECTION NNN} where SECTION is one of text, data, bss, absolute, or undefined. NNN is a signed, 2's complement 32 bit integer. Numbers are usually integers. A number can be a flonum or bignum. In this case, you are warned that only the low order 32 bits are used, and `as' pretends these 32 bits are an integer. You may write integer-manipulating instructions that act on exotic constants, compatible with other assemblers. Subexpressions are a left parenthesis `(' followed by an integer expression, followed by a right parenthesis `)'; or a prefix operator followed by an argument.  File: as.info, Node: Operators, Next: Prefix Ops, Prev: Arguments, Up: Integer Exprs Operators --------- "Operators" are arithmetic functions, like `+' or `%'. Prefix operators are followed by an argument. Infix operators appear between their arguments. Operators may be preceded and/or followed by whitespace.  File: as.info, Node: Prefix Ops, Next: Infix Ops, Prev: Operators, Up: Integer Exprs Prefix Operator --------------- `as' has the following "prefix operators". They each take one argument, which must be absolute. `-' "Negation". Two's complement negation. `~' "Complementation". Bitwise not.  File: as.info, Node: Infix Ops, Prev: Prefix Ops, Up: Integer Exprs Infix Operators --------------- "Infix operators" take two arguments, one on either side. Operators have precedence, but operations with equal precedence are performed left to right. Apart from `+' or `-', both arguments must be absolute, and the result is absolute. 1. Highest Precedence `*' "Multiplication". `/' "Division". Truncation is the same as the C operator `/' `%' "Remainder". `<' `<<' "Shift Left". Same as the C operator `<<'. `>' `>>' "Shift Right". Same as the C operator `>>'. 2. Intermediate precedence `|' "Bitwise Inclusive Or". `&' "Bitwise And". `^' "Bitwise Exclusive Or". `!' "Bitwise Or Not". 3. Lowest Precedence `+' "Addition". If either argument is absolute, the result has the section of the other argument. If either argument is pass1 or undefined, the result is pass1. Otherwise `+' is illegal. `-' "Subtraction". If the right argument is absolute, the result has the section of the left argument. If either argument is pass1 the result is pass1. If either argument is undefined the result is difference section. If both arguments are in the same section, the result is absolute--provided that section is one of text, data or bss. Otherwise subtraction is illegal. The sense of the rule for addition is that it's only meaningful to add the *offsets* in an address; you can only have a defined section in one of the two arguments. Similarly, you can't subtract quantities from two different sections.  File: as.info, Node: Pseudo Ops, Next: Machine Dependencies, Prev: Expressions, Up: Top Assembler Directives ******************** All assembler directives have names that begin with a period (`.'). The rest of the name is letters, usually in lower case. This chapter discusses directives that are available regardless of the target machine configuration for the GNU assembler. Some machine configurations provide additional directives. *Note Machine Dependencies::. * Menu: * Abort:: `.abort' * ABORT:: `.ABORT' * Align:: `.align ABS-EXPR , ABS-EXPR' * App-File:: `.app-file STRING' * Ascii:: `.ascii "STRING"'... * Asciz:: `.asciz "STRING"'... * Byte:: `.byte EXPRESSIONS' * Comm:: `.comm SYMBOL , LENGTH ' * Data:: `.data SUBSECTION' * Def:: `.def NAME' * Desc:: `.desc SYMBOL, ABS-EXPRESSION' * Dim:: `.dim' * Double:: `.double FLONUMS' * Eject:: `.eject' * Else:: `.else' * Endef:: `.endef' * Endif:: `.endif' * Equ:: `.equ SYMBOL, EXPRESSION' * Extern:: `.extern' * File:: `.file STRING' * Fill:: `.fill REPEAT , SIZE , VALUE' * Float:: `.float FLONUMS' * Global:: `.global SYMBOL', `.globl SYMBOL' * hword:: `.hword EXPRESSIONS' * Ident:: `.ident' * If:: `.if ABSOLUTE EXPRESSION' * Include:: `.include "FILE"' * Int:: `.int EXPRESSIONS' * Lcomm:: `.lcomm SYMBOL , LENGTH' * Lflags:: `.lflags' * Line:: `.line LINE-NUMBER' * Ln:: `.ln LINE-NUMBER' * List:: `.list' * Long:: `.long EXPRESSIONS' * Nolist:: `.nolist' * Octa:: `.octa BIGNUMS' * Org:: `.org NEW-LC , FILL' * Psize:: `.psize LINES, COLUMNS' * Quad:: `.quad BIGNUMS' * Sbttl:: `.sbttl "SUBHEADING"' * Scl:: `.scl CLASS' * Section:: `.section NAME, SUBSECTION' * Set:: `.set SYMBOL, EXPRESSION' * Short:: `.short EXPRESSIONS' * Single:: `.single FLONUMS' * Size:: `.size' * Space:: `.space SIZE , FILL' * Stab:: `.stabd, .stabn, .stabs' * Tag:: `.tag STRUCTNAME' * Text:: `.text SUBSECTION' * Title:: `.title "HEADING"' * Type:: `.type INT' * Val:: `.val ADDR' * Word:: `.word EXPRESSIONS' * Deprecated:: Deprecated Directives  File: as.info, Node: Abort, Next: ABORT, Up: Pseudo Ops `.abort' ======== This directive stops the assembly immediately. It is for compatibility with other assemblers. The original idea was that the assembly language source would be piped into the assembler. If the sender of the source quit, it could use this directive tells `as' to quit also. One day `.abort' will not be supported.  File: as.info, Node: ABORT, Next: Align, Prev: Abort, Up: Pseudo Ops `.ABORT' ======== When producing COFF output, `as' accepts this directive as a synonym for `.abort'. When producing `b.out' output, `as' accepts this directive, but ignores it.  File: as.info, Node: Align, Next: App-File, Prev: ABORT, Up: Pseudo Ops `.align ABS-EXPR , ABS-EXPR' ============================ Pad the location counter (in the current subsection) to a particular storage boundary. The first expression (which must be absolute) is the number of low-order zero bits the location counter will have after advancement. For example `.align 3' will advance the location counter until it a multiple of 8. If the location counter is already a multiple of 8, no change is needed. The second expression (also absolute) gives the value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are zero.  File: as.info, Node: App-File, Next: Ascii, Prev: Align, Up: Pseudo Ops `.app-file STRING' ================== `.app-file' (which may also be spelled `.file') tells `as' that we are about to start a new logical file. STRING is the new file name. In general, the filename is recognized whether or not it is surrounded by quotes `"'; but if you wish to specify an empty file name is permitted, you must give the quotes-`""'. This statement may go away in future: it is only recognized to be compatible with old `as' programs.  File: as.info, Node: Ascii, Next: Asciz, Prev: App-File, Up: Pseudo Ops `.ascii "STRING"'... ==================== `.ascii' expects zero or more string literals (*note Strings::.) separated by commas. It assembles each string (with no automatic trailing zero byte) into consecutive addresses.  File: as.info, Node: Asciz, Next: Byte, Prev: Ascii, Up: Pseudo Ops `.asciz "STRING"'... ==================== `.asciz' is just like `.ascii', but each string is followed by a zero byte. The "z" in `.asciz' stands for "zero".  File: as.info, Node: Byte, Next: Comm, Prev: Asciz, Up: Pseudo Ops `.byte EXPRESSIONS' =================== `.byte' expects zero or more expressions, separated by commas. Each expression is assembled into the next byte.  File: as.info, Node: Comm, Next: Data, Prev: Byte, Up: Pseudo Ops `.comm SYMBOL , LENGTH ' ======================== `.comm' declares a named common area in the bss section. Normally `ld' reserves memory addresses for it during linking, so no partial program defines the location of the symbol. Use `.comm' to tell `ld' that it must be at least LENGTH bytes long. `ld' will allocate space for each `.comm' symbol that is at least as long as the longest `.comm' request in any of the partial programs linked. LENGTH is an absolute expression.  File: as.info, Node: Data, Next: Def, Prev: Comm, Up: Pseudo Ops `.data SUBSECTION' ================== `.data' tells `as' to assemble the following statements onto the end of the data subsection numbered SUBSECTION (which is an absolute expression). If SUBSECTION is omitted, it defaults to zero.  File: as.info, Node: Def, Next: Desc, Prev: Data, Up: Pseudo Ops `.def NAME' =========== Begin defining debugging information for a symbol NAME; the definition extends until the `.endef' directive is encountered. This directive is only observed when `as' is configured for COFF format output; when producing `b.out', `.def' is recognized, but ignored.  File: as.info, Node: Desc, Next: Dim, Prev: Def, Up: Pseudo Ops `.desc SYMBOL, ABS-EXPRESSION' ============================== This directive sets the descriptor of the symbol (*note Symbol Attributes::.) to the low 16 bits of an absolute expression. The `.desc' directive is not available when `as' is configured for COFF output; it is only for `a.out' or `b.out' object format. For the sake of compatibility, `as' will accept it, but produce no output, when configured for COFF.  File: as.info, Node: Dim, Next: Double, Prev: Desc, Up: Pseudo Ops `.dim' ====== This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside `.def'/`.endef' pairs. `.dim' is only meaningful when generating COFF format output; when `as' is generating `b.out', it accepts this directive but ignores it.  File: as.info, Node: Double, Next: Eject, Prev: Dim, Up: Pseudo Ops `.double FLONUMS' ================= `.double' expects zero or more flonums, separated by commas. It assembles floating point numbers. The exact kind of floating point numbers emitted depends on how `as' is configured. *Note Machine Dependencies::.  File: as.info, Node: Eject, Next: Else, Prev: Double, Up: Pseudo Ops `.eject' ======== Force a page break at this point, when generating assembly listings.  File: as.info, Node: Else, Next: Endef, Prev: Eject, Up: Pseudo Ops `.else' ======= `.else' is part of the `as' support for conditional assembly; *note `.if': If.. It marks the beginning of a section of code to be assembled if the condition for the preceding `.if' was false.  File: as.info, Node: Endef, Next: Endif, Prev: Else, Up: Pseudo Ops `.endef' ======== This directive flags the end of a symbol definition begun with `.def'. `.endef' is only meaningful when generating COFF format output; if `as' is configured to generate `b.out', it accepts this directive but ignores it.  File: as.info, Node: Endif, Next: Equ, Prev: Endef, Up: Pseudo Ops `.endif' ======== `.endif' is part of the `as' support for conditional assembly; it marks the end of a block of code that is only assembled conditionally. *Note `.if': If.  File: as.info, Node: Equ, Next: Extern, Prev: Endif, Up: Pseudo Ops `.equ SYMBOL, EXPRESSION' ========================= This directive sets the value of SYMBOL to EXPRESSION. It is synonymous with `.set'; *note `.set': Set..  File: as.info, Node: Extern, Next: File, Prev: Equ, Up: Pseudo Ops `.extern' ========= `.extern' is accepted in the source program--for compatibility with other assemblers--but it is ignored. `as' treats all undefined symbols as external.  File: as.info, Node: File, Next: Fill, Prev: Extern, Up: Pseudo Ops `.file STRING' ============== `.file' (which may also be spelled `.app-file') tells `as' that we are about to start a new logical file. STRING is the new file name. In general, the filename is recognized whether or not it is surrounded by quotes `"'; but if you wish to specify an empty file name, you must give the quotes-`""'. This statement may go away in future: it is only recognized to be compatible with old `as' programs. In some configurations of `as', `.file' has already been removed to avoid conflicts with other assemblers. *Note Machine Dependencies::.  File: as.info, Node: Fill, Next: Float, Prev: File, Up: Pseudo Ops `.fill REPEAT , SIZE , VALUE' ============================= RESULT, SIZE and VALUE are absolute expressions. This emits REPEAT copies of SIZE bytes. REPEAT may be zero or more. SIZE may be zero or more, but if it is more than 8, then it is deemed to have the value 8, compatible with other people's assemblers. The contents of each REPEAT bytes is taken from an 8-byte number. The highest order 4 bytes are zero. The lowest order 4 bytes are VALUE rendered in the byte-order of an integer on the computer `as' is assembling for. Each SIZE bytes in a repetition is taken from the lowest order SIZE bytes of this number. Again, this bizarre behavior is compatible with other people's assemblers. SIZE and VALUE are optional. If the second comma and VALUE are absent, VALUE is assumed zero. If the first comma and following tokens are absent, SIZE is assumed to be 1.  File: as.info, Node: Float, Next: Global, Prev: Fill, Up: Pseudo Ops `.float FLONUMS' ================ This directive assembles zero or more flonums, separated by commas. It has the same effect as `.single'. The exact kind of floating point numbers emitted depends on how `as' is configured. *Note Machine Dependencies::.  File: as.info, Node: Global, Next: hword, Prev: Float, Up: Pseudo Ops `.global SYMBOL', `.globl SYMBOL' ================================= `.global' makes the symbol visible to `ld'. If you define SYMBOL in your partial program, its value is made available to other partial programs that are linked with it. Otherwise, SYMBOL will take its attributes from a symbol of the same name from another partial program it is linked with. Both spellings (`.globl' and `.global') are accepted, for compatibility with other assemblers.  File: as.info, Node: hword, Next: Ident, Prev: Global, Up: Pseudo Ops `.hword EXPRESSIONS' ==================== This expects zero or more EXPRESSIONS, and emits a 16 bit number for each. This directive is a synonym for `.short'; depending on the target architecture, it may also be a synonym for `.word'.  File: as.info, Node: Ident, Next: If, Prev: hword, Up: Pseudo Ops `.ident' ======== This directive is used by some assemblers to place tags in object files. `as' simply accepts the directive for source-file compatibility with such assemblers, but does not actually emit anything for it.  File: as.info, Node: If, Next: Include, Prev: Ident, Up: Pseudo Ops `.if ABSOLUTE EXPRESSION' ========================= `.if' marks the beginning of a section of code which is only considered part of the source program being assembled if the argument (which must be an ABSOLUTE EXPRESSION) is non-zero. The end of the conditional section of code must be marked by `.endif' (*note `.endif': Endif.); optionally, you may include code for the alternative condition, flagged by `.else' (*note `.else': Else.. The following variants of `.if' are also supported: `.ifdef SYMBOL' Assembles the following section of code if the specified SYMBOL has been defined. `.ifndef SYMBOL' `ifnotdef SYMBOL' Assembles the following section of code if the specified SYMBOL has not been defined. Both spelling variants are equivalent.  File: as.info, Node: Include, Next: Int, Prev: If, Up: Pseudo Ops `.include "FILE"' ================= This directive provides a way to include supporting files at specified points in your source program. The code from FILE is assembled as if it followed the point of the `.include'; when the end of the included file is reached, assembly of the original file continues. You can control the search paths used with the `-I' command-line option (*note Command-Line Options: Invoking.). Quotation marks are required around FILE.  File: as.info, Node: Int, Next: Lcomm, Prev: Include, Up: Pseudo Ops `.int EXPRESSIONS' ================== Expect zero or more EXPRESSIONS, of any section, separated by commas. For each expression, emit a 32-bit number that will, at run time, be the value of that expression. The byte order of the expression depends on what kind of computer will run the program.  File: as.info, Node: Lcomm, Next: Lflags, Prev: Int, Up: Pseudo Ops `.lcomm SYMBOL , LENGTH' ======================== Reserve LENGTH (an absolute expression) bytes for a local common denoted by SYMBOL. The section and value of SYMBOL are those of the new local common. The addresses are allocated in the bss section, so at run-time the bytes will start off zeroed. SYMBOL is not declared global (*note `.global': Global.), so is normally not visible to `ld'.  File: as.info, Node: Lflags, Next: Line, Prev: Lcomm, Up: Pseudo Ops `.lflags' ========= `as' accepts this directive, for compatibility with other assemblers, but ignores it.  File: as.info, Node: Line, Next: Ln, Prev: Lflags, Up: Pseudo Ops `.line LINE-NUMBER' =================== Tell `as' to change the logical line number. LINE-NUMBER must be an absolute expression. The next line will have that logical line number. So any other statements on the current line (after a statement separator character) will be reported as on logical line number LINE-NUMBER - 1. One day this directive will be unsupported: it is used only for compatibility with existing assembler programs. *Warning:* In the AMD29K configuration of as, this command is only available with the name `.ln', rather than as either `.line' or `.ln'. Even though this is a directive associated with the `a.out' or `b.out' object-code formats, `as' will still recognize it when producing COFF output, and will treat `.line' as though it were the COFF `.ln' *if* it is found outside a `.def'/`.endef' pair. Inside a `.def', `.line' is, instead, one of the directives used by compilers to generate auxiliary symbol information for debugging.  File: as.info, Node: Ln, Next: List, Prev: Line, Up: Pseudo Ops `.ln LINE-NUMBER' ================= `.ln' is a synonym for `.line'.  File: as.info, Node: List, Next: Long, Prev: Ln, Up: Pseudo Ops `.list' ======= Control (in conjunction with the `.nolist' directive) whether or not assembly listings are generated. These two directives maintain an internal counter (which is zero initially). `.list' increments the counter, and `.nolist' decrements it. Assembly listings are generated whenever the counter is greater than zero. By default, listings are disabled. When you enable them (with the `-a' command line option; *note Command-Line Options: Invoking.), the initial value of the listing counter is one.  File: as.info, Node: Long, Next: Nolist, Prev: List, Up: Pseudo Ops `.long EXPRESSIONS' =================== `.long' is the same as `.int', *note `.int': Int..  File: as.info, Node: Nolist, Next: Octa, Prev: Long, Up: Pseudo Ops `.nolist' ========= Control (in conjunction with the `.list' directive) whether or not assembly listings are generated. These two directives maintain an internal counter (which is zero initially). `.list' increments the counter, and `.nolist' decrements it. Assembly listings are generated whenever the counter is greater than zero.  File: as.info, Node: Octa, Next: Org, Prev: Nolist, Up: Pseudo Ops `.octa BIGNUMS' =============== This directive expects zero or more bignums, separated by commas. For each bignum, it emits a 16-byte integer. The term "octa" comes from contexts in which a "word" is two bytes; hence *octa*-word for 16 bytes.  File: as.info, Node: Org, Next: Psize, Prev: Octa, Up: Pseudo Ops `.org NEW-LC , FILL' ==================== `.org' will advance the location counter of the current section to NEW-LC. NEW-LC is either an absolute expression or an expression with the same section as the current subsection. That is, you can't use `.org' to cross sections: if NEW-LC has the wrong section, the `.org' directive is ignored. To be compatible with former assemblers, if the section of NEW-LC is absolute, `as' will issue a warning, then pretend the section of NEW-LC is the same as the current subsection. `.org' may only increase the location counter, or leave it unchanged; you cannot use `.org' to move the location counter backwards. Because `as' tries to assemble programs in one pass NEW-LC may not be undefined. If you really detest this restriction we eagerly await a chance to share your improved assembler. Beware that the origin is relative to the start of the section, not to the start of the subsection. This is compatible with other people's assemblers. When the location counter (of the current subsection) is advanced, the intervening bytes are filled with FILL which should be an absolute expression. If the comma and FILL are omitted, FILL defaults to zero.  File: as.info, Node: Psize, Next: Quad, Prev: Org, Up: Pseudo Ops `.psize LINES , COLUMNS' ======================== Use this directive to declare the number of lines--and, optionally, the number of columns--to use for each page, when generating listings. If you don't use `.psize', listings will use a default line-count of 60. You may omit the comma and COLUMNS specification; the default width is 200 columns. `as' will generate formfeeds whenever the specified number of lines is exceeded (or whenever you explicitly request one, using `.eject'). If you specify LINES as `0', no formfeeds are generated save those explicitly specified with `.eject'.  File: as.info, Node: Quad, Next: Sbttl, Prev: Psize, Up: Pseudo Ops `.quad BIGNUMS' =============== `.quad' expects zero or more bignums, separated by commas. For each bignum, it emits an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a warning message; and just takes the lowest order 8 bytes of the bignum. The term "quad" comes from contexts in which a "word" is two bytes; hence *quad*-word for 8 bytes.  File: as.info, Node: Sbttl, Next: Scl, Prev: Quad, Up: Pseudo Ops `.sbttl "SUBHEADING"' ===================== Use SUBHEADING as the title (third line, immediately after the title line) when generating assembly listings. This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.  File: as.info, Node: Scl, Next: Section, Prev: Sbttl, Up: Pseudo Ops `.scl CLASS' ============ Set the storage-class value for a symbol. This directive may only be used inside a `.def'/`.endef' pair. Storage class may flag whether a symbol is static or external, or it may record further symbolic debugging information. The `.scl' directive is primarily associated with COFF output; when configured to generate `b.out' output format, `as' will accept this directive but ignore it.  File: as.info, Node: Section, Next: Set, Prev: Scl, Up: Pseudo Ops `.section NAME, SUBSECTION' =========================== Assemble the following code into end of subsection numbered SUBSECTION in the COFF named section NAME. If you omit SUBSECTION, `as' uses subsection number zero. `.section .text' is equivalent to the `.text' directive; `.section .data' is equivalent to the `.data' directive.  File: as.info, Node: Set, Next: Short, Prev: Section, Up: Pseudo Ops `.set SYMBOL, EXPRESSION' ========================= This directive sets the value of SYMBOL to EXPRESSION. This will change SYMBOL's value and type to conform to EXPRESSION. If SYMBOL was flagged as external, it remains flagged. (*Note Symbol Attributes::.) You may `.set' a symbol many times in the same assembly. If the expression's section is unknowable during pass 1, a second pass over the source program will be forced. The second pass is currently not implemented. `as' will abort with an error message if one is required. If you `.set' a global symbol, the value stored in the object file is the last value stored into it.  File: as.info, Node: Short, Next: Single, Prev: Set, Up: Pseudo Ops `.short EXPRESSIONS' ==================== `.short' is normally the same as `.word'. *Note `.word': Word. In some configurations, however, `.short' and `.word' generate numbers of different lengths; *note Machine Dependencies::..  File: as.info, Node: Single, Next: Size, Prev: Short, Up: Pseudo Ops `.single FLONUMS' ================= This directive assembles zero or more flonums, separated by commas. It has the same effect as `.float'. The exact kind of floating point numbers emitted depends on how `as' is configured. *Note Machine Dependencies::.  File: as.info, Node: Size, Next: Space, Prev: Single, Up: Pseudo Ops `.size' ======= This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside `.def'/`.endef' pairs. `.size' is only meaningful when generating COFF format output; when `as' is generating `b.out', it accepts this directive but ignores it.  File: as.info, Node: Space, Next: Stab, Prev: Size, Up: Pseudo Ops `.space SIZE , FILL' ==================== This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL are absolute expressions. If the comma and FILL are omitted, FILL is assumed to be zero. On the AMD 29K, this directive is ignored; it is accepted for compatibility with other AMD 29K assemblers. *Warning:* In most versions of the GNU assembler, the directive `.space' has the effect of `.block' *Note Machine Dependencies::.  File: as.info, Node: Stab, Next: Tag, Prev: Space, Up: Pseudo Ops `.stabd, .stabn, .stabs' ======================== There are three directives that begin `.stab'. All emit symbols (*note Symbols::.), for use by symbolic debuggers. The symbols are not entered in the `as' hash table: they cannot be referenced elsewhere in the source file. Up to five fields are required: STRING This is the symbol's name. It may contain any character except `\000', so is more general than ordinary symbol names. Some debuggers used to code arbitrarily complex structures into symbol names using this field. TYPE An absolute expression. The symbol's type is set to the low 8 bits of this expression. Any bit pattern is permitted, but `ld' and debuggers will choke on silly bit patterns. OTHER An absolute expression. The symbol's "other" attribute is set to the low 8 bits of this expression. DESC An absolute expression. The symbol's descriptor is set to the low 16 bits of this expression. VALUE An absolute expression which becomes the symbol's value. If a warning is detected while reading a `.stabd', `.stabn', or `.stabs' statement, the symbol has probably already been created and you will get a half-formed symbol in your object file. This is compatible with earlier assemblers! `.stabd TYPE , OTHER , DESC' The "name" of the symbol generated is not even an empty string. It is a null pointer, for compatibility. Older assemblers used a null pointer so they didn't waste space in object files with empty strings. The symbol's value is set to the location counter, relocatably. When your program is linked, the value of this symbol will be where the location counter was when the `.stabd' was assembled. `.stabn TYPE , OTHER , DESC , VALUE' The name of the symbol is set to the empty string `""'. `.stabs STRING , TYPE , OTHER , DESC , VALUE' All five fields are specified.  File: as.info, Node: Tag, Next: Text, Prev: Stab, Up: Pseudo Ops `.tag STRUCTNAME' ================= This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside `.def'/`.endef' pairs. Tags are used to link structure definitions in the symbol table with instances of those structures. `.tag' is only used when generating COFF format output; when `as' is generating `b.out', it accepts this directive but ignores it.  File: as.info, Node: Text, Next: Title, Prev: Tag, Up: Pseudo Ops `.text SUBSECTION' ================== Tells `as' to assemble the following statements onto the end of the text subsection numbered SUBSECTION, which is an absolute expression. If SUBSECTION is omitted, subsection number zero is used.  File: as.info, Node: Title, Next: Type, Prev: Text, Up: Pseudo Ops `.title "HEADING"' ================== Use HEADING as the title (second line, immediately after the source file name and pagenumber) when generating assembly listings. This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.  File: as.info, Node: Type, Next: Val, Prev: Title, Up: Pseudo Ops `.type INT' =========== This directive, permitted only within `.def'/`.endef' pairs, records the integer INT as the type attribute of a symbol table entry. `.type' is associated only with COFF format output; when `as' is configured for `b.out' output, it accepts this directive but ignores it.  File: as.info, Node: Val, Next: Word, Prev: Type, Up: Pseudo Ops `.val ADDR' =========== This directive, permitted only within `.def'/`.endef' pairs, records the address ADDR as the value attribute of a symbol table entry. `.val' is used only for COFF output; when `as' is configured for `b.out', it accepts this directive but ignores it.  File: as.info, Node: Word, Next: Deprecated, Prev: Val, Up: Pseudo Ops `.word EXPRESSIONS' =================== This directive expects zero or more EXPRESSIONS, of any section, separated by commas. The size of the number emitted, and its byte order, depends on what kind of computer will run the program. *Warning: Special Treatment to support Compilers* Machines with a 32-bit address space, but that do less than 32-bit addressing, require the following special treatment. If the machine of interest to you does 32-bit addressing (or doesn't require it; *note Machine Dependencies::.), you can ignore this issue. In order to assemble compiler output into something that will work, `as' will occasionlly do strange things to `.word' directives. Directives of the form `.word sym1-sym2' are often emitted by compilers as part of jump tables. Therefore, when `as' assembles a directive of the form `.word sym1-sym2', and the difference between `sym1' and `sym2' does not fit in 16 bits, `as' will create a "secondary jump table", immediately before the next label. This secondary jump table will be preceded by a short-jump to the first byte after the secondary table. This short-jump prevents the flow of control from accidentally falling into the new table. Inside the table will be a long-jump to `sym2'. The original `.word' will contain `sym1' minus the address of the long-jump to `sym2'. If there were several occurrences of `.word sym1-sym2' before the secondary jump table, all of them will be adjusted. If there was a `.word sym3-sym4', that also did not fit in sixteen bits, a long-jump to `sym4' will be included in the secondary jump table, and the `.word' directives will be adjusted to contain `sym3' minus the address of the long-jump to `sym4'; and so on, for as many entries in the original jump table as necessary.  File: as.info, Node: Deprecated, Prev: Word, Up: Pseudo Ops Deprecated Directives ===================== One day these directives won't work. They are included for compatibility with older assemblers. .abort .app-file .line  File: as.info, Node: Machine Dependencies, Next: Copying, Prev: Pseudo Ops, Up: Top Machine Dependent Features ************************** The machine instruction sets are (almost by definition) different on each machine where `as' runs. Floating point representations vary as well, and `as' often supports a few additional directives or command-line options for compatibility with other assemblers on a particular platform. Finally, some versions of `as' support special pseudo-instructions for branch optimization. This chapter discusses most of these differences, though it does not include details on any machine's instruction set. For details on that subject, see the hardware manufacturer's manual. * Menu: * Vax-Dependent:: VAX Dependent Features * AMD29K-Dependent:: AMD 29K Dependent Features * H8/300-Dependent:: Hitachi H8/300 Dependent Features * H8/500-Dependent:: Hitachi H8/500 Dependent Features * SH-Dependent:: Hitachi SH Dependent Features * i960-Dependent:: Intel 80960 Dependent Features * M68K-Dependent:: M680x0 Dependent Features * Sparc-Dependent:: SPARC Dependent Features * Z8000-Dependent:: Z8000 Dependent Features * i386-Dependent:: 80386 Dependent Features  File: as.info, Node: Vax-Dependent, Next: AMD29K-Dependent, Up: Machine Dependencies VAX Dependent Features ====================== * Menu: * Vax-Opts:: VAX Command-Line Options * VAX-float:: VAX Floating Point * VAX-directives:: Vax Machine Directives * VAX-opcodes:: VAX Opcodes * VAX-branch:: VAX Branch Improvement * VAX-operands:: VAX Operands * VAX-no:: Not Supported on VAX  File: as.info, Node: Vax-Opts, Next: VAX-float, Up: Vax-Dependent VAX Command-Line Options ------------------------ The Vax version of `as' accepts any of the following options, gives a warning message that the option was ignored and proceeds. These options are for compatibility with scripts designed for other people's assemblers. `-D' (Debug) `-S' (Symbol Table) `-T' (Token Trace) These are obsolete options used to debug old assemblers. `-d' (Displacement size for JUMPs) This option expects a number following the `-d'. Like options that expect filenames, the number may immediately follow the `-d' (old standard) or constitute the whole of the command line argument that follows `-d' (GNU standard). `-V' (Virtualize Interpass Temporary File) Some other assemblers use a temporary file. This option commanded them to keep the information in active memory rather than in a disk file. `as' always does this, so this option is redundant. `-J' (JUMPify Longer Branches) Many 32-bit computers permit a variety of branch instructions to do the same job. Some of these instructions are short (and fast) but have a limited range; others are long (and slow) but can branch anywhere in virtual memory. Often there are 3 flavors of branch: short, medium and long. Some other assemblers would emit short and medium branches, unless told by this option to emit short and long branches. `-t' (Temporary File Directory) Some other assemblers may use a temporary file, and this option takes a filename being the directory to site the temporary file. Since `as' does not use a temporary disk file, this option makes no difference. `-t' needs exactly one filename. The Vax version of the assembler accepts two options when compiled for VMS. They are `-h', and `-+'. The `-h' option prevents `as' from modifying the symbol-table entries for symbols that contain lowercase characters (I think). The `-+' option causes `as' to print warning messages if the FILENAME part of the object file, or any symbol name is larger than 31 characters. The `-+' option also insertes some code following the `_main' symbol so that the object file will be compatible with Vax-11 "C".  File: as.info, Node: VAX-float, Next: VAX-directives, Prev: Vax-Opts, Up: Vax-Dependent VAX Floating Point ------------------ Conversion of flonums to floating point is correct, and compatible with previous assemblers. Rounding is towards zero if the remainder is exactly half the least significant bit. `D', `F', `G' and `H' floating point formats are understood. Immediate floating literals (*e.g.* `S`$6.9') are rendered correctly. Again, rounding is towards zero in the boundary case. The `.float' directive produces `f' format numbers. The `.double' directive produces `d' format numbers.  File: as.info, Node: VAX-directives, Next: VAX-opcodes, Prev: VAX-float, Up: Vax-Dependent Vax Machine Directives ---------------------- The Vax version of the assembler supports four directives for generating Vax floating point constants. They are described in the table below. `.dfloat' This expects zero or more flonums, separated by commas, and assembles Vax `d' format 64-bit floating point constants. `.ffloat' This expects zero or more flonums, separated by commas, and assembles Vax `f' format 32-bit floating point constants. `.gfloat' This expects zero or more flonums, separated by commas, and assembles Vax `g' format 64-bit floating point constants. `.hfloat' This expects zero or more flonums, separated by commas, and assembles Vax `h' format 128-bit floating point constants.  File: as.info, Node: VAX-opcodes, Next: VAX-branch, Prev: VAX-directives, Up: Vax-Dependent VAX Opcodes ----------- All DEC mnemonics are supported. Beware that `case...' instructions have exactly 3 operands. The dispatch table that follows the `case...' instruction should be made with `.word' statements. This is compatible with all unix assemblers we know of.  File: as.info, Node: VAX-branch, Next: VAX-operands, Prev: VAX-opcodes, Up: Vax-Dependent VAX Branch Improvement ---------------------- Certain pseudo opcodes are permitted. They are for branch instructions. They expand to the shortest branch instruction that will reach the target. Generally these mnemonics are made by substituting `j' for `b' at the start of a DEC mnemonic. This feature is included both for compatibility and to help compilers. If you don't need this feature, don't use these opcodes. Here are the mnemonics, and the code they can expand into. `jbsb' `Jsb' is already an instruction mnemonic, so we chose `jbsb'. (byte displacement) `bsbb ...' (word displacement) `bsbw ...' (long displacement) `jsb ...' `jbr' `jr' Unconditional branch. (byte displacement) `brb ...' (word displacement) `brw ...' (long displacement) `jmp ...' `jCOND' COND may be any one of the conditional branches `neq', `nequ', `eql', `eqlu', `gtr', `geq', `lss', `gtru', `lequ', `vc', `vs', `gequ', `cc', `lssu', `cs'. COND may also be one of the bit tests `bs', `bc', `bss', `bcs', `bsc', `bcc', `bssi', `bcci', `lbs', `lbc'. NOTCOND is the opposite condition to COND. (byte displacement) `bCOND ...' (word displacement) `bNOTCOND foo ; brw ... ; foo:' (long displacement) `bNOTCOND foo ; jmp ... ; foo:' `jacbX' X may be one of `b d f g h l w'. (word displacement) `OPCODE ...' (long displacement) OPCODE ..., foo ; brb bar ; foo: jmp ... ; bar: `jaobYYY' YYY may be one of `lss leq'. `jsobZZZ' ZZZ may be one of `geq gtr'. (byte displacement) `OPCODE ...' (word displacement) OPCODE ..., foo ; brb bar ; foo: brw DESTINATION ; bar: (long displacement) OPCODE ..., foo ; brb bar ; foo: jmp DESTINATION ; bar: `aobleq' `aoblss' `sobgeq' `sobgtr' (byte displacement) `OPCODE ...' (word displacement) OPCODE ..., foo ; brb bar ; foo: brw DESTINATION ; bar: (long displacement) OPCODE ..., foo ; brb bar ; foo: jmp DESTINATION ; bar:  File: as.info, Node: VAX-operands, Next: VAX-no, Prev: VAX-branch, Up: Vax-Dependent VAX Operands ------------ The immediate character is `$' for Unix compatibility, not `#' as DEC writes it. The indirect character is `*' for Unix compatibility, not `@' as DEC writes it. The displacement sizing character is ``' (an accent grave) for Unix compatibility, not `^' as DEC writes it. The letter preceding ``' may have either case. `G' is not understood, but all other letters (`b i l s w') are understood. Register names understood are `r0 r1 r2 ... r15 ap fp sp pc'. Any case of letters will do. For instance tstb *w`$4(r5) Any expression is permitted in an operand. Operands are comma separated.  File: as.info, Node: VAX-no, Prev: VAX-operands, Up: Vax-Dependent Not Supported on VAX -------------------- Vax bit fields can not be assembled with `as'. Someone can add the required code if they really need it.  File: as.info, Node: AMD29K-Dependent, Next: H8/300-Dependent, Prev: Vax-Dependent, Up: Machine Dependencies AMD 29K Dependent Features ========================== * Menu: * AMD29K Options:: Options * AMD29K Syntax:: Syntax * AMD29K Floating Point:: Floating Point * AMD29K Directives:: AMD 29K Machine Directives * AMD29K Opcodes:: Opcodes  File: as.info, Node: AMD29K Options, Next: AMD29K Syntax, Up: AMD29K-Dependent Options ------- `as' has no additional command-line options for the AMD 29K family.  File: as.info, Node: AMD29K Syntax, Next: AMD29K Floating Point, Prev: AMD29K Options, Up: AMD29K-Dependent Syntax ------ * Menu: * AMD29K-Chars:: Special Characters * AMD29K-Regs:: Register Names  File: as.info, Node: AMD29K-Chars, Next: AMD29K-Regs, Up: AMD29K Syntax Special Characters .................. `;' is the line comment character. `@' can be used instead of a newline to separate statements. The character `?' is permitted in identifiers (but may not begin an identifier). .