Date: Sun, 4 Jan 2015 00:58:31 +0000 (UTC) From: Baptiste Daroussin <bapt@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r276651 - in head: contrib/binutils/bfd/doc contrib/binutils/gas/doc contrib/binutils/ld etc/mtree gnu/usr.bin/binutils gnu/usr.bin/binutils/doc Message-ID: <201501040058.t040wViV080114@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: bapt Date: Sun Jan 4 00:58:30 2015 New Revision: 276651 URL: https://svnweb.freebsd.org/changeset/base/276651 Log: Add pregenerated documentation for as(1) and ld(1) Added: head/contrib/binutils/bfd/doc/bfdver.texi head/contrib/binutils/gas/doc/as.txt (contents, props changed) head/contrib/binutils/gas/doc/asconfig.texi head/contrib/binutils/ld/configdoc.texi - copied unchanged from r276637, head/contrib/binutils/ld/gen-doc.texi head/contrib/binutils/ld/ld.txt (contents, props changed) head/gnu/usr.bin/binutils/doc/ head/gnu/usr.bin/binutils/doc/Makefile (contents, props changed) Modified: head/etc/mtree/BSD.usr.dist head/gnu/usr.bin/binutils/Makefile Added: head/contrib/binutils/bfd/doc/bfdver.texi ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/contrib/binutils/bfd/doc/bfdver.texi Sun Jan 4 00:58:30 2015 (r276651) @@ -0,0 +1 @@ +@set VERSION "2.17.50 [FreeBSD] 2007-07-03" Added: head/contrib/binutils/gas/doc/as.txt ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/contrib/binutils/gas/doc/as.txt Sun Jan 4 00:58:30 2015 (r276651) @@ -0,0 +1,13924 @@ +START-INFO-DIR-ENTRY +* As: (as). The GNU assembler. +* Gas: (as). The GNU assembler. +END-INFO-DIR-ENTRY + +Using as +1 Overview + 1.1 Structure of this Manual + 1.2 The GNU Assembler + 1.3 Object File Formats + 1.4 Command Line + 1.5 Input Files + 1.6 Output (Object) File + 1.7 Error and Warning Messages +2 Command-Line Options + 2.1 Enable Listings: '-a[cdhlns]' + 2.2 '--alternate' + 2.3 '-D' + 2.4 Work Faster: '-f' + 2.5 '.include' Search Path: '-I' PATH + 2.6 Difference Tables: '-K' + 2.7 Include Local Symbols: '-L' + 2.8 Configuring listing output: '--listing' + 2.9 Assemble in MRI Compatibility Mode: '-M' + 2.10 Dependency Tracking: '--MD' + 2.11 Name the Object File: '-o' + 2.12 Join Data and Text Sections: '-R' + 2.13 Display Assembly Statistics: '--statistics' + 2.14 Compatible Output: '--traditional-format' + 2.15 Announce Version: '-v' + 2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' + 2.17 Generate Object File in Spite of Errors: '-Z' +3 Syntax + 3.1 Preprocessing + 3.2 Whitespace + 3.3 Comments + 3.4 Symbols + 3.5 Statements + 3.6 Constants + 3.6.1 Character Constants + 3.6.1.1 Strings + 3.6.1.2 Characters + 3.6.2 Number Constants + 3.6.2.1 Integers + 3.6.2.2 Bignums + 3.6.2.3 Flonums +4 Sections and Relocation + 4.1 Background + 4.2 Linker Sections + 4.3 Assembler Internal Sections + 4.4 Sub-Sections + 4.5 bss Section +5 Symbols + 5.1 Labels + 5.2 Giving Symbols Other Values + 5.3 Symbol Names + 5.4 The Special Dot Symbol + 5.5 Symbol Attributes + 5.5.1 Value + 5.5.2 Type +6 Expressions + 6.1 Empty Expressions + 6.2 Integer Expressions + 6.2.1 Arguments + 6.2.2 Operators + 6.2.3 Prefix Operator + 6.2.4 Infix Operators +7 Assembler Directives + 7.1 '.abort' + 7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' + 7.3 '.ascii "STRING"'... + 7.4 '.asciz "STRING"'... + 7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' + 7.6 '.byte EXPRESSIONS' + 7.7 '.comm SYMBOL , LENGTH ' + 7.8 '.cfi_startproc [simple]' + 7.9 '.cfi_endproc' + 7.10 '.cfi_personality ENCODING [, EXP]' + 7.11 '.cfi_lsda ENCODING [, EXP]' + 7.12 '.cfi_def_cfa REGISTER, OFFSET' + 7.13 '.cfi_def_cfa_register REGISTER' + 7.14 '.cfi_def_cfa_offset OFFSET' + 7.15 '.cfi_adjust_cfa_offset OFFSET' + 7.16 '.cfi_offset REGISTER, OFFSET' + 7.17 '.cfi_rel_offset REGISTER, OFFSET' + 7.18 '.cfi_register REGISTER1, REGISTER2' + 7.19 '.cfi_restore REGISTER' + 7.20 '.cfi_undefined REGISTER' + 7.21 '.cfi_same_value REGISTER' + 7.22 '.cfi_remember_state', + 7.23 '.cfi_return_column REGISTER' + 7.24 '.cfi_signal_frame' + 7.25 '.cfi_window_save' + 7.26 '.cfi_escape' EXPRESSION[, ...] + 7.27 '.file FILENO FILENAME' + 7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' + 7.29 '.loc_mark_blocks ENABLE' + 7.30 '.data SUBSECTION' + 7.31 '.double FLONUMS' + 7.32 '.eject' + 7.33 '.else' + 7.34 '.elseif' + 7.35 '.end' + 7.36 '.endfunc' + 7.37 '.endif' + 7.38 '.equ SYMBOL, EXPRESSION' + 7.39 '.equiv SYMBOL, EXPRESSION' + 7.40 '.eqv SYMBOL, EXPRESSION' + 7.41 '.err' + 7.42 '.error "STRING"' + 7.43 '.exitm' + 7.44 '.extern' + 7.45 '.fail EXPRESSION' + 7.46 '.file STRING' + 7.47 '.fill REPEAT , SIZE , VALUE' + 7.48 '.float FLONUMS' + 7.49 '.func NAME[,LABEL]' + 7.50 '.global SYMBOL', '.globl SYMBOL' + 7.51 '.hidden NAMES' + 7.52 '.hword EXPRESSIONS' + 7.53 '.ident' + 7.54 '.if ABSOLUTE EXPRESSION' + 7.55 '.incbin "FILE"[,SKIP[,COUNT]]' + 7.56 '.include "FILE"' + 7.57 '.int EXPRESSIONS' + 7.58 '.internal NAMES' + 7.59 '.irp SYMBOL,VALUES'... + 7.60 '.irpc SYMBOL,VALUES'... + 7.61 '.lcomm SYMBOL , LENGTH' + 7.62 '.lflags' + 7.63 '.line LINE-NUMBER' + 7.64 '.linkonce [TYPE]' + 7.65 '.ln LINE-NUMBER' + 7.66 '.mri VAL' + 7.67 '.list' + 7.68 '.long EXPRESSIONS' + 7.69 '.macro' + 7.70 '.altmacro' + 7.71 '.noaltmacro' + 7.72 '.nolist' + 7.73 '.octa BIGNUMS' + 7.74 '.org NEW-LC , FILL' + 7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' + 7.76 '.previous' + 7.77 '.popsection' + 7.78 '.print STRING' + 7.79 '.protected NAMES' + 7.80 '.psize LINES , COLUMNS' + 7.81 '.purgem NAME' + 7.82 '.pushsection NAME , SUBSECTION' + 7.83 '.quad BIGNUMS' + 7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' + 7.85 '.rept COUNT' + 7.86 '.sbttl "SUBHEADING"' + 7.87 '.section NAME' + 7.88 '.set SYMBOL, EXPRESSION' + 7.89 '.short EXPRESSIONS' + 7.90 '.single FLONUMS' + 7.91 '.size' + 7.92 '.sleb128 EXPRESSIONS' + 7.93 '.skip SIZE , FILL' + 7.94 '.space SIZE , FILL' + 7.95 '.stabd, .stabn, .stabs' + 7.96 '.string' "STR" + 7.97 '.struct EXPRESSION' + 7.98 '.subsection NAME' + 7.99 '.symver' + 7.100 '.text SUBSECTION' + 7.101 '.title "HEADING"' + 7.102 '.type' + 7.103 '.uleb128 EXPRESSIONS' + 7.104 '.version "STRING"' + 7.105 '.vtable_entry TABLE, OFFSET' + 7.106 '.vtable_inherit CHILD, PARENT' + 7.107 '.warning "STRING"' + 7.108 '.weak NAMES' + 7.109 '.weakref ALIAS, TARGET' + 7.110 '.word EXPRESSIONS' + 7.111 Deprecated Directives +8 ARM Dependent Features + 8.1 Options + 8.2 Syntax + 8.2.1 Special Characters + 8.2.2 Register Names + 8.2.3 ARM relocation generation + 8.3 Floating Point + 8.4 ARM Machine Directives + 8.5 Opcodes + 8.6 Mapping Symbols +9 80386 Dependent Features + 9.1 Options + 9.2 AT&T Syntax versus Intel Syntax + 9.3 Instruction Naming + 9.4 Register Naming + 9.5 Instruction Prefixes + 9.6 Memory References + 9.7 Handling of Jump Instructions + 9.8 Floating Point + 9.9 Intel's MMX and AMD's 3DNow! SIMD Operations + 9.10 Writing 16-bit Code + 9.11 AT&T Syntax bugs + 9.12 Specifying CPU Architecture + 9.13 Notes +10 IA-64 Dependent Features + 10.1 Options + 10.2 Syntax + 10.2.1 Special Characters + 10.2.2 Register Names + 10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names + 10.3 Opcodes +11 MIPS Dependent Features + 11.1 Assembler options + 11.2 MIPS ECOFF object code + 11.3 Directives for debugging information + 11.4 Directives to override the size of symbols + 11.5 Directives to override the ISA level + 11.6 Directives for extending MIPS 16 bit instructions + 11.7 Directive to mark data as an instruction + 11.8 Directives to save and restore options + 11.9 Directives to control generation of MIPS ASE instructions +12 PowerPC Dependent Features + 12.1 Options + 12.2 PowerPC Assembler Directives +13 SPARC Dependent Features + 13.1 Options + 13.2 Enforcing aligned data + 13.3 Floating Point + 13.4 Sparc Machine Directives +14 Reporting Bugs + 14.1 Have You Found a Bug? + 14.2 How to Report Bugs +15 Acknowledgements +Appendix A GNU Free Documentation License + ADDENDUM: How to use this License for your documents +AS Index +Using as +******** + +This file is a user guide to the GNU assembler 'as' version "2.17.50 +[FreeBSD] 2007-07-03". This version of the file describes 'as' +configured to generate code for machine specific architectures. + + This document is distributed under the terms of the GNU Free +Documentation License. A copy of the license is included in the section +entitled "GNU Free Documentation License". + +1 Overview +********** + +Here is a brief summary of how to invoke 'as'. For details, see *note +Command-Line Options: Invoking. + + as [-a[cdhlns][=FILE]] [-alternate] [-D] + [-defsym SYM=VAL] [-f] [-g] [-gstabs] + [-gstabs+] [-gdwarf-2] [-help] [-I DIR] [-J] + [-K] [-L] [-listing-lhs-width=NUM] + [-listing-lhs-width2=NUM] [-listing-rhs-width=NUM] + [-listing-cont-lines=NUM] [-keep-locals] [-o + OBJFILE] [-R] [-reduce-memory-overheads] [-statistics] + [-v] [-version] [-version] [-W] [-warn] + [-fatal-warnings] [-w] [-x] [-Z] [@FILE] + [-target-help] [TARGET-OPTIONS] + [-|FILES ...] + + _Target ARM options:_ + [-mcpu=PROCESSOR[+EXTENSION...]] + [-march=ARCHITECTURE[+EXTENSION...]] + [-mfpu=FLOATING-POINT-FORMAT] + [-mfloat-abi=ABI] + [-meabi=VER] + [-mthumb] + [-EB|-EL] + [-mapcs-32|-mapcs-26|-mapcs-float| + -mapcs-reentrant] + [-mthumb-interwork] [-k] + + _Target i386 options:_ + [-32|-64] [-n] + [-march=CPU] [-mtune=CPU] + + _Target IA-64 options:_ + [-mconstant-gp|-mauto-pic] + [-milp32|-milp64|-mlp64|-mp64] + [-mle|mbe] + [-mtune=itanium1|-mtune=itanium2] + [-munwind-check=warning|-munwind-check=error] + [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] + [-x|-xexplicit] [-xauto] [-xdebug] + + _Target MIPS options:_ + [-nocpp] [-EL] [-EB] [-O[OPTIMIZATION LEVEL]] + [-g[DEBUG LEVEL]] [-G NUM] [-KPIC] [-call_shared] + [-non_shared] [-xgot [-mvxworks-pic] + [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] + [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] + [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] + [-mips64] [-mips64r2] + [-construct-floats] [-no-construct-floats] + [-trap] [-no-break] [-break] [-no-trap] + [-mfix7000] [-mno-fix7000] + [-mips16] [-no-mips16] + [-msmartmips] [-mno-smartmips] + [-mips3d] [-no-mips3d] + [-mdmx] [-no-mdmx] + [-mdsp] [-mno-dsp] + [-mdspr2] [-mno-dspr2] + [-mmt] [-mno-mt] + [-mdebug] [-no-mdebug] + [-mpdr] [-mno-pdr] + + _Target PowerPC options:_ + [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| + -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| + -mbooke32|-mbooke64] + [-mcom|-many|-maltivec] [-memb] + [-mregnames|-mno-regnames] + [-mrelocatable|-mrelocatable-lib] + [-mlittle|-mlittle-endian|-mbig|-mbig-endian] + [-msolaris|-mno-solaris] + + _Target SPARC options:_ + [-Av6|-Av7|-Av8|-Asparclet|-Asparclite + -Av8plus|-Av8plusa|-Av9|-Av9a] + [-xarch=v8plus|-xarch=v8plusa] [-bump] + [-32|-64] + + + +'@FILE' + Read command-line options from FILE. The options read are inserted + in place of the original @FILE option. If FILE does not exist, or + cannot be read, then the option will be treated literally, and not + removed. + + Options in FILE are separated by whitespace. A whitespace + character may be included in an option by surrounding the entire + option in either single or double quotes. Any character (including + a backslash) may be included by prefixing the character to be + included with a backslash. The FILE may itself contain additional + @FILE options; any such options will be processed recursively. + +'-a[cdhlmns]' + Turn on listings, in any of a variety of ways: + + '-ac' + omit false conditionals + + '-ad' + omit debugging directives + + '-ah' + include high-level source + + '-al' + include assembly + + '-am' + include macro expansions + + '-an' + omit forms processing + + '-as' + include symbols + + '=file' + set the name of the listing file + + You may combine these options; for example, use '-aln' for assembly + listing without forms processing. The '=file' option, if used, + must be the last one. By itself, '-a' defaults to '-ahls'. + +'--alternate' + Begin in alternate macro mode. *Note '.altmacro': Altmacro. + +'-D' + Ignored. This option is accepted for script compatibility with + calls to other assemblers. + +'--defsym SYM=VALUE' + Define the symbol SYM to be VALUE before assembling the input file. + VALUE must be an integer constant. As in C, a leading '0x' + indicates a hexadecimal value, and a leading '0' indicates an octal + value. The value of the symbol can be overridden inside a source + file via the use of a '.set' pseudo-op. + +'-f' + "fast"--skip whitespace and comment preprocessing (assume source is + compiler output). + +'-g' +'--gen-debug' + Generate debugging information for each assembler source line using + whichever debug format is preferred by the target. This currently + means either STABS, ECOFF or DWARF2. + +'--gstabs' + Generate stabs debugging information for each assembler line. This + may help debugging assembler code, if the debugger can handle it. + +'--gstabs+' + Generate stabs debugging information for each assembler line, with + GNU extensions that probably only gdb can handle, and that could + make other debuggers crash or refuse to read your program. This + may help debugging assembler code. Currently the only GNU + extension is the location of the current working directory at + assembling time. + +'--gdwarf-2' + Generate DWARF2 debugging information for each assembler line. + This may help debugging assembler code, if the debugger can handle + it. Note--this option is only supported by some targets, not all + of them. + +'--help' + Print a summary of the command line options and exit. + +'--target-help' + Print a summary of all target specific options and exit. + +'-I DIR' + Add directory DIR to the search list for '.include' directives. + +'-J' + Don't warn about signed overflow. + +'-K' + This option is accepted but has no effect on the machine specific + family. + +'-L' +'--keep-locals' + Keep (in the symbol table) local symbols. These symbols start with + system-specific local label prefixes, typically '.L' for ELF + systems or 'L' for traditional a.out systems. *Note Symbol + Names::. + +'--listing-lhs-width=NUMBER' + Set the maximum width, in words, of the output data column for an + assembler listing to NUMBER. + +'--listing-lhs-width2=NUMBER' + Set the maximum width, in words, of the output data column for + continuation lines in an assembler listing to NUMBER. + +'--listing-rhs-width=NUMBER' + Set the maximum width of an input source line, as displayed in a + listing, to NUMBER bytes. + +'--listing-cont-lines=NUMBER' + Set the maximum number of lines printed in a listing for a single + line of input to NUMBER + 1. + +'-o OBJFILE' + Name the object-file output from 'as' OBJFILE. + +'-R' + Fold the data section into the text section. + + Set the default size of GAS's hash tables to a prime number close + to NUMBER. Increasing this value can reduce the length of time it + takes the assembler to perform its tasks, at the expense of + increasing the assembler's memory requirements. Similarly reducing + this value can reduce the memory requirements at the expense of + speed. + +'--reduce-memory-overheads' + This option reduces GAS's memory requirements, at the expense of + making the assembly processes slower. Currently this switch is a + synonym for '--hash-size=4051', but in the future it may have other + effects as well. + +'--statistics' + Print the maximum space (in bytes) and total time (in seconds) used + by assembly. + +'--strip-local-absolute' + Remove local absolute symbols from the outgoing symbol table. + +'-v' +'-version' + Print the 'as' version. + +'--version' + Print the 'as' version and exit. + +'-W' +'--no-warn' + Suppress warning messages. + +'--fatal-warnings' + Treat warnings as errors. + +'--warn' + Don't suppress warning messages or treat them as errors. + +'-w' + Ignored. + +'-x' + Ignored. + +'-Z' + Generate an object file even after errors. + +'-- | FILES ...' + Standard input, or source files to assemble. + + The following options are available when as is configured for the ARM +processor family. + +'-mcpu=PROCESSOR[+EXTENSION...]' + Specify which ARM processor variant is the target. +'-march=ARCHITECTURE[+EXTENSION...]' + Specify which ARM architecture variant is used by the target. +'-mfpu=FLOATING-POINT-FORMAT' + Select which Floating Point architecture is the target. +'-mfloat-abi=ABI' + Select which floating point ABI is in use. +'-mthumb' + Enable Thumb only instruction decoding. +'-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant' + Select which procedure calling convention is in use. +'-EB | -EL' + Select either big-endian (-EB) or little-endian (-EL) output. +'-mthumb-interwork' + Specify that the code has been generated with interworking between + Thumb and ARM code in mind. +'-k' + Specify that PIC code has been generated. + + The following options are available when 'as' is configured for the +SPARC architecture: + +'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' +'-Av8plus | -Av8plusa | -Av9 | -Av9a' + Explicitly select a variant of the SPARC architecture. + + '-Av8plus' and '-Av8plusa' select a 32 bit environment. '-Av9' and + '-Av9a' select a 64 bit environment. + + '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with + UltraSPARC extensions. + +'-xarch=v8plus | -xarch=v8plusa' + For compatibility with the Solaris v9 assembler. These options are + equivalent to -Av8plus and -Av8plusa, respectively. + +'-bump' + Warn when the assembler switches to another architecture. + + The following options are available when as is configured for a MIPS +processor. + +'-G NUM' + This option sets the largest size of an object that can be + referenced implicitly with the 'gp' register. It is only accepted + for targets that use ECOFF format, such as a DECstation running + Ultrix. The default value is 8. + +'-EB' + Generate "big endian" format output. + +'-EL' + Generate "little endian" format output. + +'-mips1' +'-mips2' +'-mips3' +'-mips4' +'-mips5' +'-mips32' +'-mips32r2' +'-mips64' +'-mips64r2' + Generate code for a particular MIPS Instruction Set Architecture + level. '-mips1' is an alias for '-march=r3000', '-mips2' is an + alias for '-march=r6000', '-mips3' is an alias for '-march=r4000' + and '-mips4' is an alias for '-march=r8000'. '-mips5', '-mips32', + '-mips32r2', '-mips64', and '-mips64r2' correspond to generic 'MIPS + V', 'MIPS32', 'MIPS32 Release 2', 'MIPS64', and 'MIPS64 Release 2' + ISA processors, respectively. + +'-march=CPU' + Generate code for a particular MIPS cpu. + +'-mtune=CPU' + Schedule and tune for a particular MIPS cpu. + +'-mfix7000' +'-mno-fix7000' + Cause nops to be inserted if the read of the destination register + of an mfhi or mflo instruction occurs in the following two + instructions. + +'-mdebug' +'-no-mdebug' + Cause stabs-style debugging output to go into an ECOFF-style + .mdebug section instead of the standard ELF .stabs sections. + +'-mpdr' +'-mno-pdr' + Control generation of '.pdr' sections. + +'-mgp32' +'-mfp32' + The register sizes are normally inferred from the ISA and ABI, but + these flags force a certain group of registers to be treated as 32 + bits wide at all times. '-mgp32' controls the size of + general-purpose registers and '-mfp32' controls the size of + floating-point registers. + +'-mips16' +'-no-mips16' + Generate code for the MIPS 16 processor. This is equivalent to + putting '.set mips16' at the start of the assembly file. + '-no-mips16' turns off this option. + +'-msmartmips' +'-mno-smartmips' + Enables the SmartMIPS extension to the MIPS32 instruction set. + This is equivalent to putting '.set smartmips' at the start of the + assembly file. '-mno-smartmips' turns off this option. + +'-mips3d' +'-no-mips3d' + Generate code for the MIPS-3D Application Specific Extension. This + tells the assembler to accept MIPS-3D instructions. '-no-mips3d' + turns off this option. + +'-mdmx' +'-no-mdmx' + Generate code for the MDMX Application Specific Extension. This + tells the assembler to accept MDMX instructions. '-no-mdmx' turns + off this option. + +'-mdsp' +'-mno-dsp' + Generate code for the DSP Release 1 Application Specific Extension. + This tells the assembler to accept DSP Release 1 instructions. + '-mno-dsp' turns off this option. + +'-mdspr2' +'-mno-dspr2' + Generate code for the DSP Release 2 Application Specific Extension. + This option implies -mdsp. This tells the assembler to accept DSP + Release 2 instructions. '-mno-dspr2' turns off this option. + +'-mmt' +'-mno-mt' + Generate code for the MT Application Specific Extension. This + tells the assembler to accept MT instructions. '-mno-mt' turns off + this option. + +'--construct-floats' +'--no-construct-floats' + The '--no-construct-floats' option disables the construction of + double width floating point constants by loading the two halves of + the value into the two single width floating point registers that + make up the double width register. By default '--construct-floats' + is selected, allowing construction of these floating point + constants. + +'--emulation=NAME' + This option causes 'as' to emulate 'as' configured for some other + target, in all respects, including output format (choosing between + ELF and ECOFF only), handling of pseudo-opcodes which may generate + debugging information or store symbol table information, and + default endianness. The available configuration names are: + 'mipsecoff', 'mipself', 'mipslecoff', 'mipsbecoff', 'mipslelf', + 'mipsbelf'. The first two do not alter the default endianness from + that of the primary target for which the assembler was configured; + the others change the default to little- or big-endian as indicated + by the 'b' or 'l' in the name. Using '-EB' or '-EL' will override + the endianness selection in any case. + + This option is currently supported only when the primary target + 'as' is configured for is a MIPS ELF or ECOFF target. Furthermore, + the primary target or others specified with '--enable-targets=...' + at configuration time must include support for the other format, if + both are to be available. For example, the Irix 5 configuration + includes support for both. + + Eventually, this option will support more configurations, with more + fine-grained control over the assembler's behavior, and will be + supported for more processors. + +'-nocpp' + 'as' ignores this option. It is accepted for compatibility with + the native tools. + +'--trap' +'--no-trap' +'--break' +'--no-break' + Control how to deal with multiplication overflow and division by + zero. '--trap' or '--no-break' (which are synonyms) take a trap + exception (and only work for Instruction Set Architecture level 2 + and higher); '--break' or '--no-trap' (also synonyms, and the + default) take a break exception. + +'-n' + When this option is used, 'as' will issue a warning every time it + generates a nop instruction from a macro. + +1.1 Structure of this Manual +============================ + +This manual is intended to describe what you need to know to use GNU +'as'. We cover the syntax expected in source files, including notation +for symbols, constants, and expressions; the directives that 'as' +understands; and of course how to invoke 'as'. + + We also cover special features in the machine specific configuration +of 'as', including assembler directives. + + On the other hand, this manual is _not_ intended as an introduction +to programming in assembly language--let alone programming in general! +In a similar vein, we make no attempt to introduce the machine +architecture; we do _not_ describe the instruction set, standard +mnemonics, registers or addressing modes that are standard to a +particular architecture. + +1.2 The GNU Assembler +===================== + +GNU 'as' is really a family of assemblers. This manual describes 'as', +a member of that family which is configured for the machine specific +architectures. If you use (or have used) the GNU assembler on one +architecture, you should find a fairly similar environment when you use +it on another architecture. Each version has much in common with the +others, including object file formats, most assembler directives (often +called "pseudo-ops") and assembler syntax. + + 'as' is primarily intended to assemble the output of the GNU C +compiler 'gcc' for use by the linker 'ld'. Nevertheless, we've tried to +make 'as' assemble correctly everything that other assemblers for the +same machine would assemble. + + Unlike older assemblers, 'as' is designed to assemble a source +program in one pass of the source file. This has a subtle impact on the +'.org' directive (*note '.org': Org.). + +1.3 Object File Formats +======================= + +The GNU assembler can be configured to produce several alternative +object file formats. For the most part, this does not affect how you +write assembly language programs; but directives for debugging symbols +are typically different in different file formats. *Note Symbol +Attributes: Symbol Attributes. For the machine specific target, 'as' is +configured to produce ELF format object files. + +1.4 Command Line +================ + +After the program name 'as', the command line may contain options and +file names. Options may appear in any order, and may be before, after, +or between file names. The order of file names is significant. + + '--' (two hyphens) by itself names the standard input file +explicitly, as one of the files for 'as' to assemble. + + Except for '--' any command line argument that begins with a hyphen +('-') is an option. Each option changes the behavior of 'as'. No +option changes the way another option works. An option is a '-' +followed by one or more letters; the case of the letter is important. +All options are optional. + + Some options expect exactly one file name to follow them. The file +name may either immediately follow the option's letter (compatible with +older assemblers) or it may be the next command argument (GNU standard). +These two command lines are equivalent: + + as -o my-object-file.o mumble.s + as -omy-object-file.o mumble.s + +1.5 Input Files +=============== + +We use the phrase "source program", abbreviated "source", to describe +the program input to one run of 'as'. The program may be in one or more +files; how the source is partitioned into files doesn't change the +meaning of the source. + + The source program is a concatenation of the text in all the files, +in the order specified. + + Each time you run 'as' it assembles exactly one source program. The +source program is made up of one or more files. (The standard input is +also a file.) + + You give 'as' a command line that has zero or more input file names. +The input files are read (from left file name to right). A command line +argument (in any position) that has no special meaning is taken to be an +input file name. + + If you give 'as' no file names it attempts to read one input file +from the 'as' standard input, which is normally your terminal. You may +have to type <ctl-D> to tell 'as' there is no more program to assemble. + + Use '--' if you need to explicitly name the standard input file in +your command line. + + If the source is empty, 'as' produces a small, empty object file. + +Filenames and Line-numbers +-------------------------- + +There are two ways of locating a line in the input file (or files) and +either may be used in reporting error messages. One way refers to a +line number in a physical file; the other refers to a line number in a +"logical" file. *Note Error and Warning Messages: Errors. + + "Physical files" are those files named in the command line given to +'as'. + + "Logical files" are simply names declared explicitly by assembler +directives; they bear no relation to physical files. Logical file names +help error messages reflect the original source file, when 'as' source +is itself synthesized from other files. 'as' understands the '#' +directives emitted by the 'gcc' preprocessor. See also *note '.file': +File. + +1.6 Output (Object) File +======================== + +Every time you run 'as' it produces an output file, which is your +assembly language program translated into numbers. This file is the +object file. Its default name is 'a.out'. You can give it another name +by using the '-o' option. Conventionally, object file names end with +'.o'. The default name is used for historical reasons: older assemblers +were capable of assembling self-contained programs directly into a +runnable program. (For some formats, this isn't currently possible, but +it can be done for the 'a.out' format.) + + The object file is meant for input to the linker 'ld'. It contains +assembled program code, information to help 'ld' integrate the assembled +program into a runnable file, and (optionally) symbolic information for +the debugger. + +1.7 Error and Warning Messages +============================== + +'as' may write warnings and error messages to the standard error file +(usually your terminal). This should not happen when a compiler runs +'as' automatically. Warnings report an assumption made so that 'as' +could keep assembling a flawed program; errors report a grave problem +that stops the assembly. + + Warning messages have the format + + file_name:NNN:Warning Message Text + +(where NNN is a line number). If a logical file name has been given +(*note '.file': File.) it is used for the filename, otherwise the name +of the current input file is used. If a logical line number was given +then it is used to calculate the number printed, otherwise the actual +line in the current source file is printed. The message text is +intended to be self explanatory (in the grand Unix tradition). + + Error messages have the format + file_name:NNN:FATAL:Error Message Text + The file name and line number are derived as for warning messages. +The actual message text may be rather less explanatory because many of +them aren't supposed to happen. + +2 Command-Line Options +********************** + +This chapter describes command-line options available in _all_ versions +of the GNU assembler; see *note Machine Dependencies::, for options +specific to the machine specific target. + + If you are invoking 'as' via the GNU C compiler, you can use the +'-Wa' option to pass arguments through to the assembler. The assembler +arguments must be separated from each other (and the '-Wa') by commas. +For example: + + gcc -c -g -O -Wa,-alh,-L file.c + +This passes two options to the assembler: '-alh' (emit a listing to +standard output with high-level and assembly source) and '-L' (retain +local symbols in the symbol table). + + Usually you do not need to use this '-Wa' mechanism, since many +compiler command-line options are automatically passed to the assembler +by the compiler. (You can call the GNU compiler driver with the '-v' +option to see precisely what options it passes to each compilation pass, +including the assembler.) + +2.1 Enable Listings: '-a[cdhlns]' +================================= + +These options enable listing output from the assembler. By itself, '-a' +requests high-level, assembly, and symbols listing. You can use other +letters to select specific options for the list: '-ah' requests a +high-level language listing, '-al' requests an output-program assembly +listing, and '-as' requests a symbol table listing. High-level listings +require that a compiler debugging option like '-g' be used, and that +assembly listings ('-al') be requested also. + + Use the '-ac' option to omit false conditionals from a listing. Any +lines which are not assembled because of a false '.if' (or '.ifdef', or +any other conditional), or a true '.if' followed by an '.else', will be +omitted from the listing. + + Use the '-ad' option to omit debugging directives from the listing. + + Once you have specified one of these options, you can further control +listing output and its appearance using the directives '.list', +'.nolist', '.psize', '.eject', '.title', and '.sbttl'. The '-an' option +turns off all forms processing. If you do not request listing output +with one of the '-a' options, the listing-control directives have no +effect. + + The letters after '-a' may be combined into one option, _e.g._, +'-aln'. + + Note if the assembler source is coming from the standard input (e.g., +because it is being created by 'gcc' and the '-pipe' command line switch +is being used) then the listing will not contain any comments or +preprocessor directives. This is because the listing code buffers input +source lines from stdin only after they have been preprocessed by the +assembler. This reduces memory usage and makes the code more efficient. + +2.2 '--alternate' +================= + +Begin in alternate macro mode, see *note '.altmacro': Altmacro. + +2.3 '-D' +======== + +This option has no effect whatsoever, but it is accepted to make it more +likely that scripts written for other assemblers also work with 'as'. + +2.4 Work Faster: '-f' +===================== + +'-f' should only be used when assembling programs written by a (trusted) +compiler. '-f' stops the assembler from doing whitespace and comment +preprocessing on the input file(s) before assembling them. *Note +Preprocessing: Preprocessing. + + _Warning:_ if you use '-f' when the files actually need to be + preprocessed (if they contain comments, for example), 'as' does not + work correctly. + +2.5 '.include' Search Path: '-I' PATH +===================================== + +Use this option to add a PATH to the list of directories 'as' searches +for files specified in '.include' directives (*note '.include': +Include.). You may use '-I' as many times as necessary to include a +variety of paths. The current working directory is always searched +first; after that, 'as' searches any '-I' directories in the same order +as they were specified (left to right) on the command line. + +2.6 Difference Tables: '-K' +=========================== + +On the machine specific family, this option is allowed, but has no +effect. It is permitted for compatibility with the GNU assembler on +other platforms, where it can be used to warn when the assembler alters +the machine code generated for '.word' directives in difference tables. +The machine specific family does not have the addressing limitations +that sometimes lead to this alteration on other platforms. + +2.7 Include Local Symbols: '-L' +=============================== + +Symbols beginning with system-specific local label prefixes, typically +'.L' for ELF systems or 'L' for traditional a.out systems, are called +"local symbols". *Note Symbol Names::. Normally you do not see such +symbols when debugging, because they are intended for the use of +programs (like compilers) that compose assembler programs, not for your +notice. Normally both 'as' and 'ld' discard such symbols, so you do not +normally debug with them. + + This option tells 'as' to retain those local symbols in the object +file. Usually if you do this you also tell the linker 'ld' to preserve +those symbols. + +2.8 Configuring listing output: '--listing' +=========================================== + +The listing feature of the assembler can be enabled via the command line +switch '-a' (*note a::). This feature combines the input source file(s) +with a hex dump of the corresponding locations in the output object +file, and displays them as a listing file. The format of this listing +can be controlled by directives inside the assembler source (i.e., +'.list' (*note List::), '.title' (*note Title::), '.sbttl' (*note *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201501040058.t040wViV080114>