diff options
| -rw-r--r-- | binutils/binutils.info | 1127 | ||||
| -rw-r--r-- | gas/doc/as.info | 241 | ||||
| -rw-r--r-- | gas/doc/as.info-1 | 1320 | ||||
| -rw-r--r-- | gas/doc/as.info-2 | 1524 | ||||
| -rw-r--r-- | gas/doc/as.info-3 | 1454 | ||||
| -rw-r--r-- | gas/doc/as.info-4 | 874 | ||||
| -rw-r--r-- | gas/doc/as.info-5 | 394 | ||||
| -rw-r--r-- | ld/ld.info | 65 | ||||
| -rw-r--r-- | ld/ld.info-1 | 1255 | ||||
| -rw-r--r-- | ld/ld.info-2 | 941 |
10 files changed, 9195 insertions, 0 deletions
diff --git a/binutils/binutils.info b/binutils/binutils.info new file mode 100644 index 0000000..0e38557 --- /dev/null +++ b/binutils/binutils.info @@ -0,0 +1,1127 @@ +This is Info file binutils.info, produced by Makeinfo-1.55 from the +input file ./binutils.texi. + +START-INFO-DIR-ENTRY +* Binutils:: The GNU binary utilities "ar", "ld", "objcopy", + "objdump", "nm", "size", "strings", "strip", and "ranlib". +END-INFO-DIR-ENTRY + + 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 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. + + +File: binutils.info, Node: Top, Next: ar, Prev: (dir), Up: (dir) + +Introduction +************ + + This brief manual contains preliminary documentation for the GNU +binary utilities (collectively version 2.2): + +* Menu: + +* ar:: Create, modify, and extract from archives +* ld:(ld)Overview. Combine object and archive files +* nm:: List symbols from object files +* objcopy:: Copy and translate object files +* objdump:: Display information from object files +* ranlib:: Generate index to archive contents +* size:: List section sizes and total size +* strings:: List printable strings from files +* strip:: Discard symbols +* c++filt:: Filter to demangle encoded C++ symbols +* Index:: + + +File: binutils.info, Node: ar, Next: nm, Prev: Top, Up: Top + +ar +** + + ar [-]P[MOD [RELPOS]] ARCHIVE [MEMBER...] + ar -M [ <mri-script ] + + The GNU `ar' program creates, modifies, and extracts from archives. +An "archive" is a single file holding a collection of other files in a +structure that makes it possible to retrieve the original individual +files (called "members" of the archive). + + The original files' contents, mode (permissions), timestamp, owner, +and group are preserved in the archive, and can be restored on +extraction. + + GNU `ar' can maintain archives whose members have names of any +length; however, depending on how `ar' is configured on your system, a +limit on member-name length may be imposed for compatibility with +archive formats maintained with other tools. If it exists, the limit +is often 15 characters (typical of formats related to a.out) or 16 +characters (typical of formats related to coff). + + `ar' is considered a binary utility because archives of this sort +are most often used as "libraries" holding commonly needed subroutines. + + `ar' creates an index to the symbols defined in relocatable object +modules in the archive when you specify the modifier `s'. Once +created, this index is updated in the archive whenever `ar' makes a +change to its contents (save for the `q' update operation). An archive +with such an index speeds up linking to the library, and allows +routines in the library to call each other without regard to their +placement in the archive. + + You may use `nm -s' or `nm --print-armap' to list this index table. +If an archive lacks the table, another form of `ar' called `ranlib' can +be used to add just the table. + + GNU `ar' is designed to be compatible with two different facilities. +You can control its activity using command-line options, like the +different varieties of `ar' on Unix systems; or, if you specify the +single command-line option `-M', you can control it with a script +supplied via standard input, like the MRI "librarian" program. + +* Menu: + +* ar-cmdline:: Controlling `ar' on the command line +* ar-scripts:: Controlling `ar' with a script + + +File: binutils.info, Node: ar-cmdline, Next: ar-scripts, Prev: ar, Up: ar + +Controlling `ar' on the command line +==================================== + + ar [-]P[MOD [RELPOS]] ARCHIVE [MEMBER...] + + When you use `ar' in the Unix style, `ar' insists on at least two +arguments to execute: one keyletter specifying the *operation* +(optionally accompanied by other keyletters specifying *modifiers*), +and the archive name to act on. + + Most operations can also accept further MEMBER arguments, specifying +particular files to operate on. + + GNU `ar' allows you to mix the operation code P and modifier flags +MOD in any order, within the first command-line argument. + + If you wish, you may begin the first command-line argument with a +dash. + + The P keyletter specifies what operation to execute; it may be any +of the following, but you must specify only one of them: + +`d' + *Delete* modules from the archive. Specify the names of modules to + be deleted as MEMBER...; the archive is untouched if you specify + no files to delete. + + If you specify the `v' modifier, `ar' lists each module as it is + deleted. + +`m' + Use this operation to *move* members in an archive. + + The ordering of members in an archive can make a difference in how + programs are linked using the library, if a symbol is defined in + more than one member. + + If no modifiers are used with `m', any members you name in the + MEMBER arguments are moved to the *end* of the archive; you can + use the `a', `b', or `i' modifiers to move them to a specified + place instead. + +`p' + *Print* the specified members of the archive, to the standard + output file. If the `v' modifier is specified, show the member + name before copying its contents to standard output. + + If you specify no MEMBER arguments, all the files in the archive + are printed. + +`q' + *Quick append*; add the files MEMBER... to the end of ARCHIVE, + without checking for replacement. + + The modifiers `a', `b', and `i' do *not* affect this operation; + new members are always placed at the end of the archive. + + The modifier `v' makes `ar' list each file as it is appended. + + Since the point of this operation is speed, the archive's symbol + table index is not updated, even if it already existed; you can + use `ar s' or `ranlib' explicitly to update the symbol table index. + +`r' + Insert the files MEMBER... into ARCHIVE (with *replacement*). This + operation differs from `q' in that any previously existing members + are deleted if their names match those being added. + + If one of the files named in MEMBER... does not exist, `ar' + displays an error message, and leaves undisturbed any existing + members of the archive matching that name. + + By default, new members are added at the end of the file; but you + may use one of the modifiers `a', `b', or `i' to request placement + relative to some existing member. + + The modifier `v' used with this operation elicits a line of output + for each file inserted, along with one of the letters `a' or `r' + to indicate whether the file was appended (no old member deleted) + or replaced. + +`t' + Display a *table* listing the contents of ARCHIVE, or those of the + files listed in MEMBER... that are present in the archive. + Normally only the member name is shown; if you also want to see + the modes (permissions), timestamp, owner, group, and size, you can + request that by also specifying the `v' modifier. + + If you do not specify a MEMBER, all files in the archive are + listed. + + If there is more than one file with the same name (say, `fie') in + an archive (say `b.a'), `ar t b.a fie' lists only the first + instance; to see them all, you must ask for a complete listing--in + our example, `ar t b.a'. + +`x' + *Extract* members (named MEMBER) from the archive. You can use + the `v' modifier with this operation, to request that `ar' list + each name as it extracts it. + + If you do not specify a MEMBER, all files in the archive are + extracted. + + A number of modifiers (MOD) may immediately follow the P keyletter, +to specify variations on an operation's behavior: + +`a' + Add new files *after* an existing member of the archive. If you + use the modifier `a', the name of an existing archive member must + be present as the RELPOS argument, before the ARCHIVE + specification. + +`b' + Add new files *before* an existing member of the archive. If you + use the modifier `b', the name of an existing archive member must + be present as the RELPOS argument, before the ARCHIVE + specification. (same as `i'). + +`c' + *Create* the archive. The specified ARCHIVE is always created if + it did not exist, when you request an update. But a warning is + issued unless you specify in advance that you expect to create it, + by using this modifier. + +`i' + Insert new files *before* an existing member of the archive. If + you use the modifier `i', the name of an existing archive member + must be present as the RELPOS argument, before the ARCHIVE + specification. (same as `b'). + +`l' + This modifier is accepted but not used. + +`o' + Preserve the *original* dates of members when extracting them. If + you do not specify this modifier, files extracted from the archive + are stamped with the time of extraction. + +`s' + Write an object-file index into the archive, or update an existing + one, even if no other change is made to the archive. You may use + this modifier flag either with any operation, or alone. Running + `ar s' on an archive is equivalent to running `ranlib' on it. + +`u' + Normally, `ar r'... inserts all files listed into the archive. If + you would like to insert *only* those of the files you list that + are newer than existing members of the same names, use this + modifier. The `u' modifier is allowed only for the operation `r' + (replace). In particular, the combination `qu' is not allowed, + since checking the timestamps would lose any speed advantage from + the operation `q'. + +`v' + This modifier requests the *verbose* version of an operation. Many + operations display additional information, such as filenames + processed, when the modifier `v' is appended. + +`V' + This modifier shows the version number of `ar'. + + +File: binutils.info, Node: ar-scripts, Prev: ar-cmdline, Up: ar + +Controlling `ar' with a script +============================== + + ar -M [ <SCRIPT ] + + If you use the single command-line option `-M' with `ar', you can +control its operation with a rudimentary command language. This form +of `ar' operates interactively if standard input is coming directly +from a terminal. During interactive use, `ar' prompts for input (the +prompt is `AR >'), and continues executing even after errors. If you +redirect standard input to a script file, no prompts are issued, and +`ar' abandons execution (with a nonzero exit code) on any error. + + The `ar' command language is *not* designed to be equivalent to the +command-line options; in fact, it provides somewhat less control over +archives. The only purpose of the command language is to ease the +transition to GNU `ar' for developers who already have scripts written +for the MRI "librarian" program. + + The syntax for the `ar' command language is straightforward: + * commands are recognized in upper or lower case; for example, `LIST' + is the same as `list'. In the following descriptions, commands are + shown in upper case for clarity. + + * a single command may appear on each line; it is the first word on + the line. + + * empty lines are allowed, and have no effect. + + * comments are allowed; text after either of the characters `*' or + `;' is ignored. + + * Whenever you use a list of names as part of the argument to an `ar' + command, you can separate the individual names with either commas + or blanks. Commas are shown in the explanations below, for + clarity. + + * `+' is used as a line continuation character; if `+' appears at + the end of a line, the text on the following line is considered + part of the current command. + + Here are the commands you can use in `ar' scripts, or when using +`ar' interactively. Three of them have special significance: + + `OPEN' or `CREATE' specify a "current archive", which is a temporary +file required for most of the other commands. + + `SAVE' commits the changes so far specified by the script. Prior to +`SAVE', commands affect only the temporary copy of the current archive. + +`ADDLIB ARCHIVE' +`ADDLIB ARCHIVE (MODULE, MODULE, ... MODULE)' + Add all the contents of ARCHIVE (or, if specified, each named + MODULE from ARCHIVE) to the current archive. + + Requires prior use of `OPEN' or `CREATE'. + +`ADDMOD MEMBER, MEMBER, ... MEMBER' + Add each named MEMBER as a module in the current archive. + + Requires prior use of `OPEN' or `CREATE'. + +`CLEAR' + Discard the contents of the current archive, cancelling the effect + of any operations since the last `SAVE'. May be executed (with no + effect) even if no current archive is specified. + +`CREATE ARCHIVE' + Creates an archive, and makes it the current archive (required for + many other commands). The new archive is created with a temporary + name; it is not actually saved as ARCHIVE until you use `SAVE'. + You can overwrite existing archives; similarly, the contents of any + existing file named ARCHIVE will not be destroyed until `SAVE'. + +`DELETE MODULE, MODULE, ... MODULE' + Delete each listed MODULE from the current archive; equivalent to + `ar -d ARCHIVE MODULE ... MODULE'. + + Requires prior use of `OPEN' or `CREATE'. + +`DIRECTORY ARCHIVE (MODULE, ... MODULE)' +`DIRECTORY ARCHIVE (MODULE, ... MODULE) OUTPUTFILE' + List each named MODULE present in ARCHIVE. The separate command + `VERBOSE' specifies the form of the output: when verbose output is + off, output is like that of `ar -t ARCHIVE MODULE...'. When + verbose output is on, the listing is like `ar -tv ARCHIVE + MODULE...'. + + Output normally goes to the standard output stream; however, if you + specify OUTPUTFILE as a final argument, `ar' directs the output to + that file. + +`END' + Exit from `ar', with a `0' exit code to indicate successful + completion. This command does not save the output file; if you + have changed the current archive since the last `SAVE' command, + those changes are lost. + +`EXTRACT MODULE, MODULE, ... MODULE' + Extract each named MODULE from the current archive, writing them + into the current directory as separate files. Equivalent to `ar -x + ARCHIVE MODULE...'. + + Requires prior use of `OPEN' or `CREATE'. + +`LIST' + Display full contents of the current archive, in "verbose" style + regardless of the state of `VERBOSE'. The effect is like `ar tv + ARCHIVE'). (This single command is a GNU `ld' enhancement, rather + than present for MRI compatibility.) + + Requires prior use of `OPEN' or `CREATE'. + +`OPEN ARCHIVE' + Opens an existing archive for use as the current archive (required + for many other commands). Any changes as the result of subsequent + commands will not actually affect ARCHIVE until you next use + `SAVE'. + +`REPLACE MODULE, MODULE, ... MODULE' + In the current archive, replace each existing MODULE (named in the + `REPLACE' arguments) from files in the current working directory. + To execute this command without errors, both the file, and the + module in the current archive, must exist. + + Requires prior use of `OPEN' or `CREATE'. + +`VERBOSE' + Toggle an internal flag governing the output from `DIRECTORY'. + When the flag is on, `DIRECTORY' output matches output from `ar + -tv '.... + +`SAVE' + Commit your changes to the current archive, and actually save it + as a file with the name specified in the last `CREATE' or `OPEN' + command. + + Requires prior use of `OPEN' or `CREATE'. + + +File: binutils.info, Node: nm, Next: objcopy, Prev: ar, Up: Top + +nm +** + + nm [ -a | --debug-syms ] [ -g | --extern-only ] + [ -B ] [ -C | --demangle ] + [ -s | --print-armap ] [ -A | -o | --print-file-name ] + [ -n | -v | --numeric-sort ] [ -p | --no-sort ] + [ -r | --reverse-sort ] [ -u | --undefined-only ] + [ -t RADIX | --radix=RADIX ] [ -P | --portability ] + [ --target=BFDNAME ] [ -f FORMAT | --format=FORMAT ] + [ -V | --version ] [ --help ] [ OBJFILE... ] + + GNU `nm' lists the symbols from object files OBJFILE.... If no +object files are listed as arguments, `nm' assumes `a.out'. + + For each symbol, `nm' shows: + + * The symbol value, in the radix selected by options (see below), or + hexadecimal by default. + + * The symbol type. At least the following types are used; others + are, as well, depending on the object file format. If lowercase, + the symbol is local; if uppercase, the symbol is global (external). + + `A' + Absolute. + + `B' + BSS (uninitialized data). + + `C' + Common. + + `D' + Initialized data. + + `I' + Indirect reference. + + `T' + Text (program code). + + `U' + Undefined. + + * The symbol name. + + The long and short forms of options, shown here as alternatives, are +equivalent. + +`-A' +`-o' +`--print-file-name' + Precede each symbol by the name of the input file (or archive + element) in which it was found, rather than identifying the input + file once only, before all of its symbols. + +`-a' +`--debug-syms' + Display all symbols, even debugger-only symbols; normally these + are not listed. + +`-B' + The same as `--format=bsd' (for compatibility with the MIPS `nm'). + +`-C' +`--demangle' + Decode ("demangle") low-level symbol names into user-level names. + Besides removing any initial underscore prepended by the system, + this makes C++ function names readable. *Note c++filt::, for more + information on demangling. + +`-f FORMAT' +`--format=FORMAT' + Use the output format FORMAT, which can be `bsd', `sysv', or + `posix'. The default is `bsd'. Only the first character of + FORMAT is significant; it can be either upper or lower case. + +`-g' +`--extern-only' + Display only external symbols. + +`-n' +`-v' +`--numeric-sort' + Sort symbols numerically by their addresses, rather than + alphabetically by their names. + +`-p' +`--no-sort' + Do not bother to sort the symbols in any order; print them in the + order encountered. + +`-P' +`--portability' + Use the POSIX.2 standard output format instead of the default + format. Equivalent to `-f posix'. + +`-s' +`--print-armap' + When listing symbols from archive members, include the index: a + mapping (stored in the archive by `ar' or `ranlib') of which + modules contain definitions for which names. + +`-r' +`--reverse-sort' + Reverse the order of the sort (whether numeric or alphabetic); let + the last come first. + +`-t RADIX' +`--radix=RADIX' + Use RADIX as the radix for printing the symbol values. It must be + `d' for decimal, `o' for octal, or `x' for hexadecimal. + +`--target=BFDNAME' + Specify an object code format other than your system's default + format. *Note objdump::, for information on listing available + formats. + +`-u' +`--undefined-only' + Display only undefined symbols (those external to each object + file). + +`-V' +`--version' + Show the version number of `nm' and exit. + +`--help' + Show a summary of the options to `nm' and exit. + + +File: binutils.info, Node: objcopy, Next: objdump, Prev: nm, Up: Top + +objcopy +******* + + objcopy [ -F FORMAT | --format=FORMAT ] + [ -I FORMAT | --input-format=FORMAT ] + [ -O FORMAT | --output-format=FORMAT ] + [ -S | --strip-all ] [ -g | --strip-debug ] + [ -x | --discard-all ] [ -X | --discard-locals ] + [ -v | --verbose ] [ -V | --version ] [ --help ] + INFILE [OUTFILE] + + The GNU `objcopy' utility copies the contents of an object file to +another. `objcopy' uses the GNU BFD Library to read and write the +object files. It can write the destination object file in a format +different from that of the source object file. The exact behavior of +`objcopy' is controlled by command-line options. + + `objcopy' creates temporary files to do its translations and deletes +them afterward. `objcopy' uses BFD to do all its translation work; it +knows about all the formats BFD knows about, and thus is able to +recognize most formats without being told explicitly. *Note BFD: +(ld.info)BFD the GNU linker. + +`INFILE' +`OUTFILE' + The source and output files respectively. If you do not specify + OUTFILE, `objcopy' creates a temporary file and destructively + renames the result with the name of the input file. + +`-I FORMAT' +`--input-format=FORMAT' + Consider the source file's object format to be FORMAT, rather than + attempting to deduce it. + +`-O FORMAT' +`--output-format=FORMAT' + Write the output file using the object format FORMAT. + +`-F FORMAT' +`--format=FORMAT' + Use FORMAT as the object format for both the input and the output + file; i.e. simply transfer data from source to destination with no + translation. + +`-S' +`--strip-all' + Do not copy relocation and symbol information from the source file. + +`-g' +`--strip-debug' + Do not copy debugging symbols from the source file. + +`-x' +`--discard-all' + Do not copy non-global symbols from the source file. + +`-X' +`--discard-locals' + Do not copy compiler-generated local symbols. (These usually + start with `L' or `.'.) + +`-V' +`--version' + Show the version number of `objcopy'. + +`-v' +`--verbose' + Verbose output: list all object files modified. In the case of + archives, `objcopy -V' lists all members of the archive. + +`--help' + Show a summary of the options to `objcopy'. + + +File: binutils.info, Node: objdump, Next: ranlib, Prev: objcopy, Up: Top + +objdump +******* + + objdump [ -a ] [ -b BFDNAME ] [ -d ] [ -f ] + [ -h | --header ] [ -i ] [ -j SECTION ] [ -l ] + [ -m MACHINE ] [ -r | --reloc ] [ -s ] [ --stabs ] + [ -t | --syms ] [ -x ] [ --version ] [ --help ] + OBJFILE... + + `objdump' displays information about one or more object files. The +options control what particular information to display. This +information is mostly useful to programmers who are working on the +compilation tools, as opposed to programmers who just want their +program to compile and work. + + OBJFILE... are the object files to be examined. When you specify +archives, `objdump' shows information on each of the member object +files. + + The long and short forms of options, shown here as alternatives, are +equivalent. At least one option besides `-l' must be given. + +`-a' + If any of the OBJFILE files are archives, display the archive + header information (in a format similar to `ls -l'). Besides the + information you could list with `ar tv', `objdump -a' shows the + object file format of each archive member. + +`-b BFDNAME' + Specify that the object-code format for the object files is + BFDNAME. This option may not be necessary; OBJDUMP can + automatically recognize many formats. + + For example, + objdump -b oasys -m vax -h fu.o + + displays summary information from the section headers (`-h') of + `fu.o', which is explicitly identified (`-m') as a VAX object file + in the format produced by Oasys compilers. You can list the + formats available with the `-i' option. + +`-d' + Disassemble. Display the assembler mnemonics for the machine + instructions from OBJFILE. + +`-f' + File header. Display summary information from the overall header + of each of the OBJFILE files. + +`-h' +`--header' + Header. Display summary information from the section headers of + the object file. + +`--help' + Print a summary of the options to `objdump' and exit. + +`-i' + Display a list showing all architectures and object formats + available for specification with `-b' or `-m'. + +`-j NAME' + Display information only for section NAME. + +`-l' + Label the display (using debugging information) with the source + filename and line numbers corresponding to the object code shown. + +`-m MACHINE' + Specify that the object files OBJFILE are for architecture + MACHINE. You can list available architectures using the `-i' + option. + +`-r' +`--reloc' + Relocation. Print the relocation entries of the file. + +`-s' + Display the full contents of any sections requested. + +`--stabs' + Display the full contents of any sections requested. Display the + contents of the .stab and .stab.index and .stab.excl sections from + an ELF file. This is only useful on systems (such as Solaris 2.0) + in which `.stab' debugging symbol-table entries are carried in an + ELF section. In most other file formats, debugging symbol-table + entries are interleaved with linkage symbols, and are visible in + the `--syms' output. + +`-t' +`--syms' + Symbol Table. Print the symbol table entries of the file. This + is similar to the information provided by the `nm' program. + +`--version' + Print the version number of `objdump' and exit. + +`-x' + Display all available header information, including the symbol + table and relocation entries. Using `-x' is equivalent to + specifying all of `-a -f -h -r -t'. + + +File: binutils.info, Node: ranlib, Next: size, Prev: objdump, Up: Top + +ranlib +****** + + ranlib [-vV] ARCHIVE + + `ranlib' generates an index to the contents of an archive and stores +it in the archive. The index lists each symbol defined by a member of +an archive that is a relocatable object file. + + You may use `nm -s' or `nm --print-armap' to list this index. + + An archive with such an index speeds up linking to the library and +allows routines in the library to call each other without regard to +their placement in the archive. + + The GNU `ranlib' program is another form of GNU `ar'; running +`ranlib' is completely equivalent to executing `ar -s'. *Note ar::. + +`-v' +`-V' + Show the version number of `ranlib'. + + +File: binutils.info, Node: size, Next: strings, Prev: ranlib, Up: Top + +size +**** + + size [ -A | -B | --format=COMPATIBILITY ] + [ --help ] [ -d | -o | -x | --radix=NUMBER ] + [ --target=BFDNAME ] [ -V | --version ] + OBJFILE... + + The GNU `size' utility lists the section sizes--and the total +size--for each of the object or archive files OBJFILE in its argument +list. By default, one line of output is generated for each object file +or each module in an archive. + + OBJFILE... are the object files to be examined. + + The command line options have the following meanings: + +`-A' +`-B' +`--format=COMPATIBILITY' + Using one of these options, you can choose whether the output from + GNU `size' resembles output from System V `size' (using `-A', or + `--format=sysv'), or Berkeley `size' (using `-B', or + `--format=berkeley'). The default is the one-line format similar + to Berkeley's. + + Here is an example of the Berkeley (default) format of output from + `size': + size --format Berkeley ranlib size + text data bss dec hex filename + 294880 81920 11592 388392 5ed28 ranlib + 294880 81920 11888 388688 5ee50 size + + This is the same data, but displayed closer to System V + conventions: + + size --format SysV ranlib size + ranlib : + section size addr + .text 294880 8192 + .data 81920 303104 + .bss 11592 385024 + Total 388392 + + + size : + section size addr + .text 294880 8192 + .data 81920 303104 + .bss 11888 385024 + Total 388688 + +`--help' + Show a summary of acceptable arguments and options. + +`-d' +`-o' +`-x' +`--radix=NUMBER' + Using one of these options, you can control whether the size of + each section is given in decimal (`-d', or `--radix=10'); octal + (`-o', or `--radix=8'); or hexadecimal (`-x', or `--radix=16'). + In `--radix=NUMBER', only the three values (8, 10, 16) are + supported. The total size is always given in two radices; decimal + and hexadecimal for `-d' or `-x' output, or octal and hexadecimal + if you're using `-o'. + +`--target=BFDNAME' + Specify that the object-code format for OBJFILE is BFDNAME. This + option may not be necessary; `size' can automatically recognize + many formats. *Note objdump::, for information on listing + available formats. + +`-V' +`--version' + Display the version number of `size'. + + +File: binutils.info, Node: strings, Next: strip, Prev: size, Up: Top + +strings +******* + + strings [-afov] [-MIN-LEN] [-n MIN-LEN] [-t RADIX] [-] + [--all] [--print-file-name] [--bytes=MIN-LEN] + [--radix=RADIX] [--help] [--version] FILE... + + For each FILE given, GNU `strings' prints the printable character +sequences that are at least 4 characters long (or the number given with +the options below) and are followed by a NUL or newline character. By +default, it only prints the strings from the initialized data sections +of object files; for other types of files, it prints the strings from +the whole file. + + `strings' is mainly useful for determining the contents of non-text +files. + +`-a' +`--all' +`-' + Do not scan only the initialized data section of object files; scan + the whole files. + +`-f' +`--print-file-name' + Print the name of the file before each string. + +`--help' + Print a summary of the program usage on the standard output and + exit. + +`-MIN-LEN' +`-n MIN-LEN' +`--bytes=MIN-LEN' + Print sequences of characters that are at least MIN-LEN characters + long, instead of the default 4. + +`-o' + Like `-t o'. Some other versions of `strings' have `-o' act like + `-t d' instead. Since we can not be compatible with both ways, we + simply chose one. + +`-t RADIX' +`--radix=RADIX' + Print the offset within the file before each string. The single + character argument specifies the radix of the offset--`o' for + octal, `x' for hexadecimal, or `d' for decimal. + +`-v' +`--version' + Print the program version number on the standard output and exit. + + +File: binutils.info, Node: strip, Next: c++filt, Prev: strings, Up: Top + +strip +***** + + strip [ -F FORMAT | --format=FORMAT | --target=FORMAT ] + [ -I FORMAT | --input-format=FORMAT ] + [ -O FORMAT | --output-format=FORMAT ] + [ -s | --strip-all ] [ -S | -g | --strip-debug ] + [ -x | --discard-all ] [ -X | --discard-locals ] + [ -v | --verbose ] [ -V | --version ] [ --help ] + OBJFILE... + + GNU `strip' discards all symbols from object files OBJFILE. The +list of object files may include archives. At least one object file +must be given. + + `strip' modifies the files named in its argument, rather than +writing modified copies under different names. + +`-F FORMAT' +`--format=FORMAT' +`--target=FORMAT' + Treat the original OBJFILE as a file with the object code format + FORMAT, and rewrite it in the same format. + +`--help' + Show a summary of the options to `strip' and exit. + +`-I FORMAT' +`--input-format=FORMAT' + Treat the original OBJFILE as a file with the object code format + FORMAT. + +`-O FORMAT' +`--output-format=FORMAT' + Replace OBJFILE with a file in the output format FORMAT. + +`-s' +`--strip-all' + Remove all symbols. + +`-g' +`-S' +`--strip-debug' + Remove debugging symbols only. + +`-x' +`--discard-all' + Remove non-global symbols. + +`-X' +`--discard-locals' + Remove compiler-generated local symbols. (These usually start + with `L' or `.'.) + +`-V' +`--version' + Show the version number for `strip'. + +`-v' +`--verbose' + Verbose output: list all object files modified. In the case of + archives, `strip -v' lists all members of the archive. + + +File: binutils.info, Node: c++filt, Next: Index, Prev: strip, Up: Top + +c++filt +******* + + c++filt [ -_ | --strip-underscores ] + [ -s FORMAT | --format=FORMAT ] + [ --help ] [ --version ] [ SYMBOL... ] + + The C++ language provides function overloading, which means that you +can write many functions with the same name (providing each takes +parameters of different types). All C++ function names are encoded +into a low-level assembly label (this process is known as "mangling"). +The `c++filt' program does the inverse mapping: it decodes +("demangles") low-level names into user-level names so that the linker +can keep these overloaded functions from clashing. + + Every alphanumeric word (consisting of letters, digits, underscores, +dollars, or periods) seen in the input is a potential label. If the +label decodes into a C++ name, the C++ name replaces the low-level name +in the output. + + You can use `c++filt' to decipher individual symbols: + + c++filt SYMBOL + + If no SYMBOL arguments are given, `c++filt' reads symbol names from +the standard input and writes the demangled names to the standard +output. All results are printed on the standard output. + +`-_' +`--strip-underscores' + On some systems, both the C and C++ compilers put an underscore in + front of every name. For example, the C name `foo' gets the + low-level name `_foo'. This option removes the initial underscore. + +`-s FORMAT' +`--format=FORMAT' + GNU `nm' can decode three different methods of mangling, used by + different C++ compilers. The argument to this option selects which + method it uses: + + `gnu' + the one used by the GNU compiler (the default method) + + `lucid' + the one used by the Lucid compiler + + `arm' + the one specified by the C++ Annotated Reference Manual + +`--help' + Print a summary of the options to `c++filt' and exit. + +`--version' + Print the version number of `c++filt' and exit. + + *Warning:* `c++filt' is a new utility, and the details of its user + interface are subject to change in future releases. In particular, + a command-line option may be required in the the future to decode + a name passed as an argument on the command line; in other words, + + c++filt SYMBOL + + may in a future release become + + c++filt OPTION SYMBOL + + +File: binutils.info, Node: Index, Prev: c++filt, Up: Top + +Index +***** + +* Menu: + +* .stab: objdump. +* ar compatibility: ar. +* nm compatibility: nm. +* nm compatibility: nm. +* nm format: nm. +* nm format: nm. +* size display format: size. +* size number format: size. +* all header information, object file: objdump. +* ar: ar. +* architecture: objdump. +* architectures available: objdump. +* archive contents: ranlib. +* archive headers: objdump. +* archives: ar. +* c++filt: c++filt. +* collections of files: ar. +* compatibility, ar: ar. +* contents of archive: ar-cmdline. +* creating archives: ar-cmdline. +* dates in archive: ar-cmdline. +* debug symbols: objdump. +* debugging symbols: nm. +* deleting from archive: ar-cmdline. +* demangling C++ symbols: c++filt. +* demangling C++ symbols: nm. +* disassembling object code: objdump. +* discarding symbols: strip. +* ELF object file format: objdump. +* external symbols: nm. +* external symbols: nm. +* extract from archive: ar-cmdline. +* file name: nm. +* header information, all: objdump. +* input file name: nm. +* libraries: ar. +* listings strings: strings. +* machine instructions: objdump. +* moving in archive: ar-cmdline. +* MRI compatibility, ar: ar-scripts. +* name duplication in archive: ar-cmdline. +* name length: ar. +* nm: nm. +* objdump: objdump. +* object code format: nm. +* object code format: objdump. +* object code format: size. +* object file header: objdump. +* object file information: objdump. +* object file sections: objdump. +* object formats available: objdump. +* operations on archive: ar-cmdline. +* printing from archive: ar-cmdline. +* printing strings: strings. +* quick append to archive: ar-cmdline. +* radix for section sizes: size. +* ranlib: ranlib. +* relative placement in archive: ar-cmdline. +* relocation entries, in object file: objdump. +* removing symbols: strip. +* repeated names in archive: ar-cmdline. +* replacement in archive: ar-cmdline. +* scripts, ar: ar-scripts. +* section headers: objdump. +* section information: objdump. +* section sizes: size. +* sections, full contents: objdump. +* size: size. +* sorting symbols: nm. +* source file name: nm. +* source filenames for object files: objdump. +* stab: objdump. +* strings: strings. +* strings, printing: strings. +* strip: strip. +* symbol index: ranlib. +* symbol index: ar. +* symbol index, listing: nm. +* symbol table entries, printing: objdump. +* symbols: nm. +* symbols, discarding: strip. +* undefined symbols: nm. +* Unix compatibility, ar: ar-cmdline. +* updating an archive: ar-cmdline. +* version: Top. +* writing archive index: ar-cmdline. + + + +Tag Table: +Node: Top918 +Node: ar1769 +Node: ar-cmdline3935 +Node: ar-scripts10370 +Node: nm16051 +Node: objcopy19624 +Node: objdump21994 +Node: ranlib25572 +Node: size26306 +Node: strings28993 +Node: strip30625 +Node: c++filt32286 +Node: Index34647 + +End Tag Table diff --git a/gas/doc/as.info b/gas/doc/as.info new file mode 100644 index 0000000..3cf6d9a --- /dev/null +++ b/gas/doc/as.info @@ -0,0 +1,241 @@ +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. + + +Indirect: +as.info-1: 1145 +as.info-2: 50499 +as.info-3: 99245 +as.info-4: 149134 +as.info-5: 184796 +as.info-6: 203973 + +Tag Table: +(Indirect) +Node: Top1145 +Node: Overview1833 +Node: Manual5516 +Node: GNU Assembler6455 +Node: Object Formats7630 +Node: Command Line8077 +Node: Input Files9159 +Node: Object11067 +Node: Errors12012 +Node: Invoking13209 +Node: a14540 +Node: D15637 +Node: f15862 +Node: I16367 +Node: K16909 +Node: L17208 +Node: o17863 +Node: R18314 +Node: v19222 +Node: W19473 +Node: Syntax20045 +Node: Pre-processing20637 +Node: Whitespace22105 +Node: Comments22496 +Node: Symbol Intro24306 +Node: Statements24989 +Node: Constants27044 +Node: Characters27670 +Node: Strings28163 +Node: Chars30187 +Node: Numbers30928 +Node: Integers31459 +Node: Bignums32102 +Node: Flonums32445 +Node: Sections33977 +Node: Secs Background34340 +Node: Ld Sections38752 +Node: As Sections41141 +Node: Sub-Sections42031 +Node: bss45080 +Node: Symbols45664 +Node: Labels46311 +Node: Setting Symbols46735 +Node: Symbol Names47101 +Node: Dot50054 +Node: Symbol Attributes50499 +Node: Symbol Value51173 +Node: Symbol Type52207 +Node: a.out Symbols52586 +Node: Symbol Desc52836 +Node: Symbol Other53118 +Node: COFF Symbols53274 +Node: Expressions53883 +Node: Empty Exprs54214 +Node: Integer Exprs54559 +Node: Arguments54949 +Node: Operators56046 +Node: Prefix Ops56372 +Node: Infix Ops56691 +Node: Pseudo Ops58494 +Node: Abort61763 +Node: ABORT62164 +Node: Align62426 +Node: App-File63123 +Node: Ascii63660 +Node: Asciz63965 +Node: Byte64203 +Node: Comm64435 +Node: Data64992 +Node: Def65302 +Node: Desc65670 +Node: Dim66167 +Node: Double66558 +Node: Eject66889 +Node: Else67057 +Node: Endef67346 +Node: Endif67668 +Node: Equ67919 +Node: Extern68157 +Node: File68409 +Node: Fill69060 +Node: Float70017 +Node: Global70353 +Node: hword70895 +Node: Ident71216 +Node: If71516 +Node: Include72370 +Node: Int72910 +Node: Lcomm73288 +Node: Lflags73762 +Node: Line73949 +Node: Ln75003 +Node: List75147 +Node: Long75744 +Node: Nolist75915 +Node: Octa76332 +Node: Org76658 +Node: Psize77946 +Node: Quad78624 +Node: Sbttl79065 +Node: Scl79423 +Node: Section79922 +Node: Set80334 +Node: Short81059 +Node: Single81373 +Node: Size81710 +Node: Space82106 +Node: Stab82643 +Node: Tag84649 +Node: Text85155 +Node: Title85467 +Node: Type85839 +Node: Val86215 +Node: Word86570 +Node: Deprecated88443 +Node: Machine Dependencies88677 +Node: Vax-Dependent90020 +Node: Vax-Opts90528 +Node: VAX-float92810 +Node: VAX-directives93431 +Node: VAX-opcodes94280 +Node: VAX-branch94658 +Node: VAX-operands97159 +Node: VAX-no97895 +Node: AMD29K-Dependent98121 +Node: AMD29K Options98527 +Node: AMD29K Syntax98701 +Node: AMD29K-Chars98939 +Node: AMD29K-Regs99245 +Node: AMD29K Floating Point100509 +Node: AMD29K Directives100715 +Node: AMD29K Opcodes102123 +Node: H8/300-Dependent102459 +Node: H8/300 Options102865 +Node: H8/300 Syntax103046 +Node: H8/300-Chars103333 +Node: H8/300-Regs103617 +Node: H8/300-Addressing104521 +Node: H8/300 Floating Point105547 +Node: H8/300 Directives105863 +Node: H8/300 Opcodes106382 +Node: H8/500-Dependent114735 +Node: H8/500 Options115137 +Node: H8/500 Syntax115318 +Node: H8/500-Chars115605 +Node: H8/500-Regs115896 +Node: H8/500-Addressing116652 +Node: H8/500 Floating Point117269 +Node: H8/500 Directives117474 +Node: H8/500 Opcodes117793 +Node: SH-Dependent122906 +Node: SH Options123290 +Node: SH Syntax123455 +Node: SH-Chars123714 +Node: SH-Regs123993 +Node: SH-Addressing124592 +Node: SH Floating Point125486 +Node: SH Directives125671 +Node: SH Opcodes125876 +Node: i960-Dependent130123 +Node: Options-i960130513 +Node: Floating Point-i960134399 +Node: Directives-i960134656 +Node: Opcodes for i960136676 +Node: callj-i960137282 +Node: Compare-and-branch-i960137765 +Node: M68K-Dependent139652 +Node: M68K-Opts140107 +Node: M68K-Syntax141446 +Node: M68K-Moto-Syntax143276 +Node: M68K-Float144770 +Node: M68K-Directives145556 +Node: M68K-opcodes146094 +Node: M68K-Branch146306 +Node: M68K-Chars149134 +Node: Sparc-Dependent149489 +Node: Sparc-Opts149809 +Node: Sparc-Float150743 +Node: Sparc-Directives150925 +Node: i386-Dependent151975 +Node: i386-Options152570 +Node: i386-Syntax152714 +Node: i386-Opcodes154664 +Node: i386-Regs156783 +Node: i386-prefixes157924 +Node: i386-Memory159593 +Node: i386-jumps161871 +Node: i386-Float162987 +Node: i386-Notes164977 +Node: Z8000-Dependent165818 +Node: Z8000 Options166783 +Node: Z8000 Syntax166958 +Node: Z8000-Chars167234 +Node: Z8000-Regs167452 +Node: Z8000-Addressing168224 +Node: Z8000 Directives169167 +Node: Z8000 Opcodes170725 +Node: Acknowledgements180661 +Node: Copying184796 +Node: Index203973 + +End Tag Table diff --git a/gas/doc/as.info-1 b/gas/doc/as.info-1 new file mode 100644 index 0000000..115a218 --- /dev/null +++ b/gas/doc/as.info-1 @@ -0,0 +1,1320 @@ +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: Top, Next: Overview, Prev: (DIR), Up: (DIR) + +Using as +******** + + This file is a user guide to the GNU assembler `as'. + +* Menu: + +* Overview:: Overview +* Invoking:: Command-Line Options +* Syntax:: Syntax +* Sections:: Sections and Relocation +* Symbols:: Symbols +* Expressions:: Expressions +* Pseudo Ops:: Assembler Directives +* Machine Dependencies:: Machine Dependent Features + +* Copying:: GNU GENERAL PUBLIC LICENSE + +* Acknowledgements:: Who Did What + +* Index:: Index + + +File: as.info, Node: Overview, Next: Invoking, Prev: Top, Up: Top + +Overview +******** + + Here is a brief summary of how to invoke `as'. For details, *note +Comand-Line Options: Invoking.. + + as [ -a[dhlns] ] [ -D ] [ -f ] + [ -I PATH ] [ -K ] [ -L ] + [ -o OBJFILE ] [ -R ] [ -v ] [ -w ] + [ -Av6 | -Av7 | -Av8 | -Asparclite | -bump ] + [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] + [ -b ] [ -norelax ] + [ -l ] [ -m68000 | -m68010 | -m68020 | ... ] + [ -- | FILES ... ] + +`-a[dhlns]' + Turn on listings; `-ad', omit debugging pseudo-ops from listing, + `-ah', include high-level source, `-al', assembly listing, `-an', + no forms processing, `-as', symbols. These options may be + combined; *e.g.*, `-aln' for assembly listing without forms + processing. By itself, `-a' defaults to `-ahls' -- that is, all + listings turned on. + +`-D' + This option is accepted only for script compatibility with calls to + other assemblers; it has no effect on `as'. + +`-f' + "fast"--skip whitespace and comment preprocessing (assume source is + compiler output) + +`-I PATH' + Add PATH to the search list for `.include' directives + +`-K' + Issue warnings when difference tables altered for long + displacements. + +`-L' + Keep (in symbol table) local symbols, starting with `L' + +`-o OBJFILE' + Name the object-file output from `as' + +`-R' + Fold data section into text section + +`-v' + Announce `as' version + +`-W' + Suppress warning messages + +`-- | FILES ...' + Standard input, or source files to assemble. + + The following options are available when as is configured for the +Intel 80960 processor. + +`-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC' + Specify which variant of the 960 architecture is the target. + +`-b' + Add code to collect statistics about branches taken. + +`-norelax' + Do not alter compare-and-branch instructions for long + displacements; error if necessary. + + The following options are available when as is configured for the +Motorola 68000 series. + +`-l' + Shorten references to undefined symbols, to one word instead of + two. + +`-m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040' +`| -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32' + Specify what processor in the 68000 family is the target. The + default is normally the 68020, but this can be changed at + configuration time. + +`-m68881 | -m68882 | -mno-68881 | -mno-68882' + The target machine does (or does not) have a floating-point + coprocessor. The default is to assume a coprocessor for 68020, + 68030, and cpu32. Although the basic 68000 is not compatible with + the 68881, a combination of the two can be specified, since it's + possible to do emulation of the coprocessor instructions with the + main processor. + +`-m68851 | -mno-68851' + The target machine does (or does not) have a memory-management + unit coprocessor. The default is to assume an MMU for 68020 and + up. + + The following options are available when `as' is configured for the +SPARC architecture: + +`-Av6 | -Av7 | -Av8 | -Asparclite' + Explicitly select a variant of the SPARC architecture. + +`-bump' + Warn when the assembler switches to another architecture. + +* Menu: + +* Manual:: Structure of this Manual +* GNU Assembler:: as, the GNU Assembler +* Object Formats:: Object File Formats +* Command Line:: Command Line +* Input Files:: Input Files +* Object:: Output (Object) File +* Errors:: Error and Warning Messages + + +File: as.info, Node: Manual, Next: GNU Assembler, Up: Overview + +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'. + + This manual also describes some of the machine-dependent features of +various flavors of the assembler. + + 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. You may want to consult the manufacturer's +machine architecture manual for this information. + + +File: as.info, Node: GNU Assembler, Next: Object Formats, Prev: Manual, Up: Overview + +as, the GNU Assembler +===================== + + GNU `as' is really a family of assemblers. 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. Any exceptions are documented +explicitly (*note Machine Dependencies::.). This doesn't mean `as' +always uses the same syntax as another assembler for the same +architecture; for example, we know of several incompatible versions of +680x0 assembly language syntax. + + 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.). + + +File: as.info, Node: Object Formats, Next: Command Line, Prev: GNU Assembler, Up: Overview + +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. + + +File: as.info, Node: Command Line, Next: Input Files, Prev: Object Formats, Up: Overview + +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 + + +File: as.info, Node: Input Files, Next: Object, Prev: Command Line, Up: Overview + +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' will produce 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. *Note `.app-file': App-File. + + +File: as.info, Node: Object, Next: Errors, Prev: Input Files, Up: Overview + +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, named `b.out', if `as' is configured for the Intel 80960, +or unless you tell `as' to give it another name by using the `-o' +option. Conventionally, object file names end with `.o'. The default +name of `a.out' 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 `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. + + +File: as.info, Node: Errors, Prev: Object, Up: Overview + +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 `.app-file': App-File.) it is used for the filename, otherwise +the name of the current input file is used. If a logical line number +was given (*note `.line': Line.) 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. + + +File: as.info, Node: Invoking, Next: Syntax, Prev: Overview, Up: Top + +Command-Line Options +******************** + + This chapter describes command-line options available in *all* +versions of the GNU assembler; *note Machine Dependencies::., for +options specific to particular machine architectures. + + If you are invoking `as' via the GNU C compiler (version 2), 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 + + will cause a listing to be emitted to standard output with high-level +and assembly source. + + Many compiler command-line options, such as `-R' and many +machine-specific options, will be automatically be passed to the +assembler by the compiler, so usually you do not need to use this `-Wa' +mechanism. + +* Menu: + +* a:: -a[dhlns] enable listings +* D:: -D for compatibility +* f:: -f to work faster +* I:: -I for .include search path + +* K:: -K for difference tables + +* L:: -L to retain local labels +* o:: -o to name the object file +* R:: -R to join data and text sections +* v:: -v to announce version +* W:: -W to suppress warnings + + +File: as.info, Node: a, Next: D, Up: Invoking + +Enable Listings: `-a[dhlns]' +============================ + + These options enable listing output from the assembler. By itself, +`-a' requests high-level, assembly, and symbols listing. Other letters +may be used 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. + + The `-ad' option may be used to omit debugging pseudo-ops 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'. + + +File: as.info, Node: D, Next: f, Prev: a, Up: Invoking + +`-D' +==== + + This option has no effect whatsoever, but it is accepted to make it +more likely that scripts written for other assemblers will also work +with `as'. + + +File: as.info, Node: f, Next: I, Prev: D, Up: Invoking + +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 pre-processing on the input file(s) before assembling them. +*Note Pre-processing: Pre-processing. + + *Warning:* if the files actually need to be pre-processed (if they + contain comments, for example), `as' will not work correctly if + `-f' is used. + + +File: as.info, Node: I, Next: K, Prev: f, Up: Invoking + +`.include' search path: `-I' PATH +================================= + + Use this option to add a PATH to the list of directories `as' will +search 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. + + +File: as.info, Node: K, Next: L, Prev: I, Up: Invoking + +Difference Tables: `-K' +======================= + + `as' sometimes alters the code emitted for directives of the form +`.word SYM1-SYM2'; *note `.word': Word.. You can use the `-K' option +if you want a warning issued when this is done. + + +File: as.info, Node: L, Next: o, Prev: K, Up: Invoking + +Include Local Labels: `-L' +========================== + + Labels beginning with `L' (upper case only) are called "local +labels". *Note Symbol Names::. Normally you don't see such labels 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 labels, so you don't normally +debug with them. + + This option tells `as' to retain those `L...' symbols in the object +file. Usually if you do this you also tell the linker `ld' to preserve +symbols whose names begin with `L'. + + +File: as.info, Node: o, Next: R, Prev: L, Up: Invoking + +Name the Object File: `-o' +========================== + + There is always one object file output when you run `as'. By +default it has the name `a.out' (or `b.out', for Intel 960 targets +only). You use this option (which takes exactly one filename) to give +the object file a different name. + + Whatever the object file is called, `as' will overwrite any existing +file of the same name. + + +File: as.info, Node: R, Next: v, Prev: o, Up: Invoking + +Join Data and Text Sections: `-R' +================================= + + `-R' tells `as' to write the object file as if all data-section data +lives in the text section. This is only done at the very last moment: +your binary data are the same, but data section parts are relocated +differently. The data section part of your object file is zero bytes +long because all its bytes are appended to the text section. (*Note +Sections and Relocation: Sections.) + + When you specify `-R' it would be possible to generate shorter +address displacements (because we don't have to cross between text and +data section). We refrain from doing this simply for compatibility with +older versions of `as'. In future, `-R' may work this way. + + When `as' is configured for COFF output, this option is only useful +if you use sections named `.text' and `.data'. + + +File: as.info, Node: v, Next: W, Prev: R, Up: Invoking + +Announce Version: `-v' +====================== + + You can find out what version of as is running by including the +option `-v' (which you can also spell as `-version') on the command +line. + + +File: as.info, Node: W, Prev: v, Up: Invoking + +Suppress Warnings: `-W' +======================= + + `as' should never give a warning or error message when assembling +compiler output. But programs written by people often cause `as' to +give a warning that a particular assumption was made. All such +warnings are directed to the standard error file. If you use this +option, no warnings are issued. This option only affects the warning +messages: it does not change any particular of how `as' assembles your +file. Errors, which stop the assembly, are still reported. + + +File: as.info, Node: Syntax, Next: Sections, Prev: Invoking, Up: Top + +Syntax +****** + + This chapter describes the machine-independent syntax allowed in a +source file. `as' syntax is similar to what many other assemblers use; +it is inspired by the BSD 4.2 assembler, except that `as' does not +assemble Vax bit-fields. + +* Menu: + +* Pre-processing:: Pre-processing +* Whitespace:: Whitespace +* Comments:: Comments +* Symbol Intro:: Symbols +* Statements:: Statements +* Constants:: Constants + + +File: as.info, Node: Pre-processing, Next: Whitespace, Up: Syntax + +Pre-Processing +============== + + The `as' internal pre-processor: + * adjusts and removes extra whitespace. It leaves one space or tab + before the keywords on a line, and turns any other whitespace on + the line into a single space. + + * removes all comments, replacing them with a single space, or an + appropriate number of newlines. + + * converts character constants into the appropriate numeric values. + + Note that it does not do macro processing, include file handling, or +anything else you may get from your C compiler's pre-processor. You can +do include file processing with the `.include' directive (*note +`.include': Include.). Other "CPP" style pre-processing can be done +with the GNU C compiler, by giving the input file a `.S' suffix; see +the compiler documentation for details. + + Excess whitespace, comments, and character constants cannot be used +in the portions of the input text that are not pre-processed. + + If the first line of an input file is `#NO_APP' or the `-f' option +is given, the input file will not be pre-processed. Within such an +input file, parts of the file can be pre-processed by putting a line +that says `#APP' before the text that should be pre-processed, and +putting a line that says `#NO_APP' after them. This feature is mainly +intend to support `asm' statements in compilers whose output normally +does not need to be pre-processed. + + +File: as.info, Node: Whitespace, Next: Comments, Prev: Pre-processing, Up: Syntax + +Whitespace +========== + + "Whitespace" is one or more blanks or tabs, in any order. +Whitespace is used to separate symbols, and to make programs neater for +people to read. Unless within character constants (*note Character +Constants: Characters.), any whitespace means the same as exactly one +space. + + +File: as.info, Node: Comments, Next: Symbol Intro, Prev: Whitespace, Up: Syntax + +Comments +======== + + There are two ways of rendering comments to `as'. In both cases the +comment is equivalent to one space. + + Anything from `/*' through the next `*/' is a comment. This means +you may not nest these comments. + + /* + The only way to include a newline ('\n') in a comment + is to use this sort of comment. + */ + + /* This sort of comment does not nest. */ + + Anything from the "line comment" character to the next newline is +considered a comment and is ignored. The line comment character is `#' +on the Vax; `#' on the i960; `!' on the SPARC; `|' on the 680x0; `;' +for the AMD 29K family; `;' for the H8/300 family; `!' for the H8/500 +family; `!' for the Hitachi SH; `!' for the Z8000; see *Note Machine +Dependencies::. + + On some machines there are two different line comment characters. +One will only begin a comment if it is the first non-whitespace +character on a line, while the other will always begin a comment. + + To be compatible with past assemblers, a special interpretation is +given to lines that begin with `#'. Following the `#' an absolute +expression (*note Expressions::.) is expected: this will be the +logical line number of the next line. Then a string (*Note Strings::.) +is allowed: if present it is a new logical file name. The rest of the +line, if any, should be whitespace. + + If the first non-whitespace characters on the line are not numeric, +the line is ignored. (Just like a comment.) + # This is an ordinary comment. + # 42-6 "new_file_name" # New logical file name + # This is logical line # 36. + This feature is deprecated, and may disappear from future versions +of `as'. + + +File: as.info, Node: Symbol Intro, Next: Statements, Prev: Comments, Up: Syntax + +Symbols +======= + + A "symbol" is one or more characters chosen from the set of all +letters (both upper and lower case), digits and the three characters +`_.$'. On most machines, you can also use `$' in symbol names; +exceptions are noted in *Note Machine Dependencies::. No symbol may +begin with a digit. Case is significant. There is no length limit: +all characters are significant. Symbols are delimited by characters +not in that set, or by the beginning of a file (since the source +program must end with a newline, the end of a file is not a possible +symbol delimiter). *Note Symbols::. + + +File: as.info, Node: Statements, Next: Constants, Prev: Symbol Intro, Up: Syntax + +Statements +========== + + A "statement" ends at a newline character (`\n') or line separator +character. (The line separator is usually `;', unless this conflicts +with the comment character; *note Machine Dependencies::..) The +newline or separator character is considered part of the preceding +statement. Newlines and separators within character constants are an +exception: they don't end statements. + + It is an error to end any statement with end-of-file: the last +character of any input file should be a newline. + + You may write a statement on more than one line if you put a +backslash (`\') immediately in front of any newlines within the +statement. When `as' reads a backslashed newline both characters are +ignored. You can even put backslashed newlines in the middle of symbol +names without changing the meaning of your source program. + + An empty statement is allowed, and may include whitespace. It is +ignored. + + A statement begins with zero or more labels, optionally followed by a +key symbol which determines what kind of statement it is. The key +symbol determines the syntax of the rest of the statement. If the +symbol begins with a dot `.' then the statement is an assembler +directive: typically valid for any computer. If the symbol begins with +a letter the statement is an assembly language "instruction": it will +assemble into a machine language instruction. Different versions of +`as' for different computers will recognize different instructions. In +fact, the same symbol may represent a different instruction in a +different computer's assembly language. + + A label is a symbol immediately followed by a colon (`:'). +Whitespace before a label or after a colon is permitted, but you may not +have whitespace between a label's symbol and its colon. *Note Labels::. + + label: .directive followed by something + another_label: # This is an empty statement. + instruction operand_1, operand_2, ... + + +File: as.info, Node: Constants, Prev: Statements, Up: Syntax + +Constants +========= + + A constant is a number, written so that its value is known by +inspection, without knowing any context. Like this: + .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. + .ascii "Ring the bell\7" # A string constant. + .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. + .float 0f-314159265358979323846264338327\ + 95028841971.693993751E-40 # - pi, a flonum. + +* Menu: + +* Characters:: Character Constants +* Numbers:: Number Constants + + +File: as.info, Node: Characters, Next: Numbers, Up: Constants + +Character Constants +------------------- + + There are two kinds of character constants. A "character" stands +for one character in one byte and its value may be used in numeric +expressions. String constants (properly called string *literals*) are +potentially many bytes and their values may not be used in arithmetic +expressions. + +* Menu: + +* Strings:: Strings +* Chars:: Characters + + +File: as.info, Node: Strings, Next: Chars, Up: Characters + +Strings +....... + + A "string" is written between double-quotes. It may contain +double-quotes or null characters. The way to get special characters +into a string is to "escape" these characters: precede them with a +backslash `\' character. For example `\\' represents one backslash: +the first `\' is an escape which tells `as' to interpret the second +character literally as a backslash (which prevents `as' from +recognizing the second `\' as an escape character). The complete list +of escapes follows. + +`\b' + Mnemonic for backspace; for ASCII this is octal code 010. + +`\f' + Mnemonic for FormFeed; for ASCII this is octal code 014. + +`\n' + Mnemonic for newline; for ASCII this is octal code 012. + +`\r' + Mnemonic for carriage-Return; for ASCII this is octal code 015. + +`\t' + Mnemonic for horizontal Tab; for ASCII this is octal code 011. + +`\ DIGIT DIGIT DIGIT' + An octal character code. The numeric code is 3 octal digits. For + compatibility with other Unix systems, 8 and 9 are accepted as + digits: for example, `\008' has the value 010, and `\009' the + value 011. + +`\\' + Represents one `\' character. + +`\"' + Represents one `"' character. Needed in strings to represent this + character, because an unescaped `"' would end the string. + +`\ ANYTHING-ELSE' + Any other character when escaped by `\' will give a warning, but + assemble as if the `\' was not present. The idea is that if you + used an escape sequence you clearly didn't want the literal + interpretation of the following character. However `as' has no + other interpretation, so `as' knows it is giving you the wrong + code and warns you of the fact. + + Which characters are escapable, and what those escapes represent, +varies widely among assemblers. The current set is what we think the +BSD 4.2 assembler recognizes, and is a subset of what most C compilers +recognize. If you are in doubt, don't use an escape sequence. + + +File: as.info, Node: Chars, Prev: Strings, Up: Characters + +Characters +.......... + + A single character may be written as a single quote immediately +followed by that character. The same escapes apply to characters as to +strings. So if you want to write the character backslash, you must +write `'\\' where the first `\' escapes the second `\'. As you can +see, the quote is an acute accent, not a grave accent. A newline +immediately following an acute accent is taken as a literal character +and does not count as the end of a statement. The value of a character +constant in a numeric expression is the machine's byte-wide code for +that character. `as' assumes your character code is ASCII: `'A' means +65, `'B' means 66, and so on. + + +File: as.info, Node: Numbers, Prev: Characters, Up: Constants + +Number Constants +---------------- + + `as' distinguishes three kinds of numbers according to how they are +stored in the target machine. *Integers* are numbers that would fit +into an `int' in the C language. *Bignums* are integers, but they are +stored in more than 32 bits. *Flonums* are floating point numbers, +described below. + +* Menu: + +* Integers:: Integers +* Bignums:: Bignums +* Flonums:: Flonums + + +File: as.info, Node: Integers, Next: Bignums, Up: Numbers + +Integers +........ + + A binary integer is `0b' or `0B' followed by zero or more of the +binary digits `01'. + + An octal integer is `0' followed by zero or more of the octal digits +(`01234567'). + + A decimal integer starts with a non-zero digit followed by zero or +more digits (`0123456789'). + + A hexadecimal integer is `0x' or `0X' followed by one or more +hexadecimal digits chosen from `0123456789abcdefABCDEF'. + + Integers have the usual values. To denote a negative integer, use +the prefix operator `-' discussed under expressions (*note Prefix +Operators: Prefix Ops.). + + +File: as.info, Node: Bignums, Next: Flonums, Prev: Integers, Up: Numbers + +Bignums +....... + + A "bignum" has the same syntax and semantics as an integer except +that the number (or its negative) takes more than 32 bits to represent +in binary. The distinction is made because in some places integers are +permitted while bignums are not. + + +File: as.info, Node: Flonums, Prev: Bignums, Up: Numbers + +Flonums +....... + + A "flonum" represents a floating point number. The translation is +indirect: a decimal floating point number from the text is converted by +`as' to a generic binary floating point number of more than sufficient +precision. This generic floating point number is converted to a +particular computer's floating point format (or formats) by a portion +of `as' specialized to that computer. + + A flonum is written by writing (in order) + * The digit `0'. + + * A letter, to tell `as' the rest of the number is a flonum. `e' is + recommended. Case is not important. + + On the H8/300, H8/500, Hitachi SH, and AMD 29K architectures, the + letter must be one of the letters `DFPRSX' (in upper or lower + case). + + On the Intel 960 architecture, the letter must be one of the + letters `DFT' (in upper or lower case). + + * An optional sign: either `+' or `-'. + + * An optional "integer part": zero or more decimal digits. + + * An optional "fractional part": `.' followed by zero or more + decimal digits. + + * An optional exponent, consisting of: + + * An `E' or `e'. + + * Optional sign: either `+' or `-'. + + * One or more decimal digits. + + At least one of the integer part or the fractional part must be +present. The floating point number has the usual base-10 value. + + `as' does all processing using integers. Flonums are computed +independently of any floating point hardware in the computer running +`as'. + + +File: as.info, Node: Sections, Next: Symbols, Prev: Syntax, Up: Top + +Sections and Relocation +*********************** + +* Menu: + +* Secs Background:: Background +* Ld Sections:: ld Sections +* As Sections:: as Internal Sections +* Sub-Sections:: Sub-Sections +* bss:: bss Section + + +File: as.info, Node: Secs Background, Next: Ld Sections, Up: Sections + +Background +========== + + Roughly, a section is a range of addresses, with no gaps; all data +"in" those addresses is treated the same for some particular purpose. +For example there may be a "read only" section. + + The linker `ld' reads many object files (partial programs) and +combines their contents to form a runnable program. When `as' emits an +object file, the partial program is assumed to start at address 0. +`ld' will assign the final addresses the partial program occupies, so +that different partial programs don't overlap. This is actually an +over-simplification, but it will suffice to explain how `as' uses +sections. + + `ld' moves blocks of bytes of your program to their run-time +addresses. These blocks slide to their run-time addresses as rigid +units; their length does not change and neither does the order of bytes +within them. Such a rigid unit is called a *section*. Assigning +run-time addresses to sections is called "relocation". It includes the +task of adjusting mentions of object-file addresses so they refer to +the proper run-time addresses. For the H8/300 and H8/500, and for the +Hitachi SH, `as' pads sections if needed to ensure they end on a word +(sixteen bit) boundary. + + An object file written by `as' has at least three sections, any of +which may be empty. These are named "text", "data" and "bss" sections. + + When it generates COFF output, `as' can also generate whatever other +named sections you specify using the `.section' directive (*note +`.section': Section.). If you don't use any directives that place +output in the `.text' or `.data' sections, these sections will still +exist, but will be empty. + + Within the object file, the text section starts at address `0', the +data section follows, and the bss section follows the data section. + + To let `ld' know which data will change when the sections are +relocated, and how to change that data, `as' also writes to the object +file details of the relocation needed. To perform relocation `ld' must +know, each time an address in the object file is mentioned: + * Where in the object file is the beginning of this reference to an + address? + + * How long (in bytes) is this reference? + + * Which section does the address refer to? What is the numeric + value of + (ADDRESS) - (START-ADDRESS OF SECTION)? + + * Is the reference to an address "Program-Counter relative"? + + In fact, every address `as' ever uses is expressed as + (SECTION) + (OFFSET INTO SECTION) + +Further, every expression `as' computes is of this section-relative +nature. "Absolute expression" means an expression with section +"absolute" (*note Ld Sections::.). A "pass1 expression" means an +expression with section "pass1" (*note as Internal Sections: As +Sections.). In this manual we use the notation {SECNAME N} to mean +"offset N into section SECNAME". + + Apart from text, data and bss sections you need to know about the +"absolute" section. When `ld' mixes partial programs, addresses in the +absolute section remain unchanged. For example, address `{absolute 0}' +is "relocated" to run-time address 0 by `ld'. Although two partial +programs' data sections will not overlap addresses after linking, *by +definition* their absolute sections will overlap. Address `{absolute +239}' in one partial program will always be the same address when the +program is running as address `{absolute 239}' in any other partial +program. + + The idea of sections is extended to the "undefined" section. Any +address whose section is unknown at assembly time is by definition +rendered {undefined U}--where U will be filled in later. Since numbers +are always defined, the only way to generate an undefined address is to +mention an undefined symbol. A reference to a named common block would +be such a symbol: its value is unknown at assembly time so it has +section *undefined*. + + By analogy the word *section* is used to describe groups of sections +in the linked program. `ld' puts all partial programs' text sections +in contiguous addresses in the linked program. It is customary to +refer to the *text section* of a program, meaning all the addresses of +all partial program's text sections. Likewise for data and bss +sections. + + Some sections are manipulated by `ld'; others are invented for use +of `as' and have no meaning except during assembly. + + +File: as.info, Node: Ld Sections, Next: As Sections, Prev: Secs Background, Up: Sections + +ld Sections +=========== + + `ld' deals with just four kinds of sections, summarized below. + +*named sections* +*text section* +*data section* + These sections hold your program. `as' and `ld' treat them as + separate but equal sections. Anything you can say of one section + is true another. When the program is running, however, it is + customary for the text section to be unalterable. The text + section is often shared among processes: it will contain + instructions, constants and the like. The data section of a + running program is usually alterable: for example, C variables + would be stored in the data section. + +*bss section* + This section contains zeroed bytes when your program begins + running. It is used to hold unitialized variables or common + storage. The length of each partial program's bss section is + important, but because it starts out containing zeroed bytes there + is no need to store explicit zero bytes in the object file. The + bss section was invented to eliminate those explicit zeros from + object files. + +*absolute section* + Address 0 of this section is always "relocated" to runtime address + 0. This is useful if you want to refer to an address that `ld' + must not change when relocating. In this sense we speak of + absolute addresses being "unrelocatable": they don't change during + relocation. + +*undefined section* + This "section" is a catch-all for address references to objects + not in the preceding sections. + + An idealized example of three relocatable sections follows. The +example uses the traditional section names `.text' and `.data'. Memory +addresses are on the horizontal axis. + + +-----+----+--+ + partial program # 1: |ttttt|dddd|00| + +-----+----+--+ + + text data bss + seg. seg. seg. + + +---+---+---+ + partial program # 2: |TTT|DDD|000| + +---+---+---+ + + +--+---+-----+--+----+---+-----+~~ + linked program: | |TTT|ttttt| |dddd|DDD|00000| + +--+---+-----+--+----+---+-----+~~ + + addresses: 0 ... + + +File: as.info, Node: As Sections, Next: Sub-Sections, Prev: Ld Sections, Up: Sections + +as Internal Sections +==================== + + These sections are meant only for the internal use of `as'. They +have no meaning at run-time. You don't really need to know about these +sections for most purposes; but they can be mentioned in `as' warning +messages, so it might be helpful to have an idea of their meanings to +`as'. These sections are used to permit the value of every expression +in your assembly language program to be a section-relative address. + +ASSEMBLER-INTERNAL-LOGIC-ERROR! + An internal assembler logic error has been found. This means + there is a bug in the assembler. + +expr section + The assembler stores complex expression internally as combinations + of symbols. When it needs to represent an expression as a symbol, + it puts it in the expr section. + + +File: as.info, Node: Sub-Sections, Next: bss, Prev: As Sections, Up: Sections + +Sub-Sections +============ + + Assembled bytes conventionally fall into two sections: text and data. +You may have separate groups of data in named sections that you want to +end up near to each other in the object file, even though they are not +contiguous in the assembler source. `as' allows you to use +"subsections" for this purpose. Within each section, there can be +numbered subsections with values from 0 to 8192. Objects assembled +into the same subsection will be grouped with other objects in the same +subsection when they are all put into the object file. For example, a +compiler might want to store constants in the text section, but might +not want to have them interspersed with the program being assembled. +In this case, the compiler could issue a `.text 0' before each section +of code being output, and a `.text 1' before each group of constants +being output. + + Subsections are optional. If you don't use subsections, everything +will be stored in subsection number zero. + + Each subsection is zero-padded up to a multiple of four bytes. +(Subsections may be padded a different amount on different flavors of +`as'.) + + Subsections appear in your object file in numeric order, lowest +numbered to highest. (All this to be compatible with other people's +assemblers.) The object file contains no representation of subsections; +`ld' and other programs that manipulate object files will see no trace +of them. They just see all your text subsections as a text section, +and all your data subsections as a data section. + + To specify which subsection you want subsequent statements assembled +into, use a numeric argument to specify it, in a `.text EXPRESSION' or +a `.data EXPRESSION' statement. When generating COFF output, you can +also use an extra subsection argument with arbitrary named sections: +`.section NAME, EXPRESSION'. EXPRESSION should be an absolute +expression. (*Note Expressions::.) If you just say `.text' then +`.text 0' is assumed. Likewise `.data' means `.data 0'. Assembly +begins in `text 0'. For instance: + .text 0 # The default subsection is text 0 anyway. + .ascii "This lives in the first text subsection. *" + .text 1 + .ascii "But this lives in the second text subsection." + .data 0 + .ascii "This lives in the data section," + .ascii "in the first data subsection." + .text 0 + .ascii "This lives in the first text section," + .ascii "immediately following the asterisk (*)." + + Each section has a "location counter" incremented by one for every +byte assembled into that section. Because subsections are merely a +convenience restricted to `as' there is no concept of a subsection +location counter. There is no way to directly manipulate a location +counter--but the `.align' directive will change it, and any label +definition will capture its current value. The location counter of the +section that statements are being assembled into is said to be the +"active" location counter. + + +File: as.info, Node: bss, Prev: Sub-Sections, Up: Sections + +bss Section +=========== + + The bss section is used for local common variable storage. You may +allocate address space in the bss section, but you may not dictate data +to load into it before your program executes. When your program starts +running, all the contents of the bss section are zeroed bytes. + + Addresses in the bss section are allocated with special directives; +you may not assemble anything directly into the bss section. Hence +there are no bss subsections. *Note `.comm': Comm, *note `.lcomm': +Lcomm.. + + +File: as.info, Node: Symbols, Next: Expressions, Prev: Sections, Up: Top + +Symbols +******* + + Symbols are a central concept: the programmer uses symbols to name +things, the linker uses symbols to link, and the debugger uses symbols +to debug. + + *Warning:* `as' does not place symbols in the object file in the + same order they were declared. This may break some debuggers. + +* Menu: + +* Labels:: Labels +* Setting Symbols:: Giving Symbols Other Values +* Symbol Names:: Symbol Names +* Dot:: The Special Dot Symbol +* Symbol Attributes:: Symbol Attributes + + +File: as.info, Node: Labels, Next: Setting Symbols, Up: Symbols + +Labels +====== + + A "label" is written as a symbol immediately followed by a colon +`:'. The symbol then represents the current value of the active +location counter, and is, for example, a suitable instruction operand. +You are warned if you use the same symbol to represent two different +locations: the first definition overrides any other definitions. + + +File: as.info, Node: Setting Symbols, Next: Symbol Names, Prev: Labels, Up: Symbols + +Giving Symbols Other Values +=========================== + + A symbol can be given an arbitrary value by writing a symbol, +followed by an equals sign `=', followed by an expression (*note +Expressions::.). This is equivalent to using the `.set' directive. +*Note `.set': Set. + + +File: as.info, Node: Symbol Names, Next: Dot, Prev: Setting Symbols, Up: Symbols + +Symbol Names +============ + + Symbol names begin with a letter or with one of `._'. On most +machines, you can also use `$' in symbol names; exceptions are noted in +*Note Machine Dependencies::. That character may be followed by any +string of digits, letters, dollar signs (unless otherwise noted in +*Note Machine Dependencies::), and underscores. For the AMD 29K +family, `?' is also allowed in the body of a symbol name, though not at +its beginning. + + Case of letters is significant: `foo' is a different symbol name +than `Foo'. + + Each symbol has exactly one name. Each name in an assembly language +program refers to exactly one symbol. You may use that symbol name any +number of times in a program. + +Local Symbol Names +------------------ + + Local symbols help compilers and programmers use names temporarily. +There are ten local symbol names, which are re-used throughout the +program. You may refer to them using the names `0' `1' ... `9'. To +define a local symbol, write a label of the form `N:' (where N +represents any digit). To refer to the most recent previous definition +of that symbol write `Nb', using the same digit as when you defined the +label. To refer to the next definition of a local label, write +`Nf'--where N gives you a choice of 10 forward references. The `b' +stands for "backwards" and the `f' stands for "forwards". + + Local symbols are not emitted by the current GNU C compiler. + + There is no restriction on how you can use these labels, but +remember that at any point in the assembly you can refer to at most 10 +prior local labels and to at most 10 forward local labels. + + Local symbol names are only a notation device. They are immediately +transformed into more conventional symbol names before the assembler +uses them. The symbol names stored in the symbol table, appearing in +error messages and optionally emitted to the object file have these +parts: + +`L' + All local labels begin with `L'. Normally both `as' and `ld' + forget symbols that start with `L'. These labels are used for + symbols you are never intended to see. If you give the `-L' + option then `as' will retain these symbols in the object file. If + you also instruct `ld' to retain these symbols, you may use them + in debugging. + +`DIGIT' + If the label is written `0:' then the digit is `0'. If the label + is written `1:' then the digit is `1'. And so on up through `9:'. + +A' + This unusual character is included so you don't accidentally invent + a symbol of the same name. The character has ASCII value `\001'. + +`*ordinal number*' + This is a serial number to keep the labels distinct. The first + `0:' gets the number `1'; The 15th `0:' gets the number `15'; + *etc.*. Likewise for the other labels `1:' through `9:'. + + For instance, the first `1:' is named `LA1', the 44th `3:' is named +`LA44'. + + +File: as.info, Node: Dot, Next: Symbol Attributes, Prev: Symbol Names, Up: Symbols + +The Special Dot Symbol +====================== + + The special symbol `.' refers to the current address that `as' is +assembling into. Thus, the expression `melvin: .long .' will cause +`melvin' to contain its own address. Assigning a value to `.' is +treated the same as a `.org' directive. Thus, the expression `.=.+4' +is the same as saying `.space 4'. + diff --git a/gas/doc/as.info-2 b/gas/doc/as.info-2 new file mode 100644 index 0000000..45bb197 --- /dev/null +++ b/gas/doc/as.info-2 @@ -0,0 +1,1524 @@ +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). + diff --git a/gas/doc/as.info-3 b/gas/doc/as.info-3 new file mode 100644 index 0000000..cdc5a0e --- /dev/null +++ b/gas/doc/as.info-3 @@ -0,0 +1,1454 @@ +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: AMD29K-Regs, Prev: AMD29K-Chars, Up: AMD29K Syntax + +Register Names +.............. + + General-purpose registers are represented by predefined symbols of +the form `GRNNN' (for global registers) or `LRNNN' (for local +registers), where NNN represents a number between `0' and `127', +written with no leading zeros. The leading letters may be in either +upper or lower case; for example, `gr13' and `LR7' are both valid +register names. + + You may also refer to general-purpose registers by specifying the +register number as the result of an expression (prefixed with `%%' to +flag the expression as a register number): + %%EXPRESSION + +--where EXPRESSION must be an absolute expression evaluating to a +number between `0' and `255'. The range [0, 127] refers to global +registers, and the range [128, 255] to local registers. + + In addition, `as' understands the following protected +special-purpose register names for the AMD 29K family: + + vab chd pc0 + ops chc pc1 + cps rbp pc2 + cfg tmc mmu + cha tmr lru + + These unprotected special-purpose register names are also recognized: + ipc alu fpe + ipa bp inte + ipb fc fps + q cr exop + + +File: as.info, Node: AMD29K Floating Point, Next: AMD29K Directives, Prev: AMD29K Syntax, Up: AMD29K-Dependent + +Floating Point +-------------- + + The AMD 29K family uses IEEE floating-point numbers. + + +File: as.info, Node: AMD29K Directives, Next: AMD29K Opcodes, Prev: AMD29K Floating Point, Up: AMD29K-Dependent + +AMD 29K Machine Directives +-------------------------- + +`.block 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. + + In other versions of the GNU assembler, this directive is called + `.space'. + +`.cputype' + This directive is ignored; it is accepted for compatibility with + other AMD 29K assemblers. + +`.file' + This directive is ignored; it is accepted for compatibility with + other AMD 29K assemblers. + + *Warning:* in other versions of the GNU assembler, `.file' is + used for the directive called `.app-file' in the AMD 29K + support. + +`.line' + This directive is ignored; it is accepted for compatibility with + other AMD 29K assemblers. + +`.sect' + This directive is ignored; it is accepted for compatibility with + other AMD 29K assemblers. + +`.use SECTION NAME' + Establishes the section and subsection for the following code; + SECTION NAME may be one of `.text', `.data', `.data1', or `.lit'. + With one of the first three SECTION NAME options, `.use' is + equivalent to the machine directive SECTION NAME; the remaining + case, `.use .lit', is the same as `.data 200'. + + +File: as.info, Node: AMD29K Opcodes, Prev: AMD29K Directives, Up: AMD29K-Dependent + +Opcodes +------- + + `as' implements all the standard AMD 29K opcodes. No additional +pseudo-instructions are needed on this family. + + For information on the 29K machine instruction set, see `Am29000 +User's Manual', Advanced Micro Devices, Inc. + + +File: as.info, Node: H8/300-Dependent, Next: H8/500-Dependent, Prev: AMD29K-Dependent, Up: Machine Dependencies + +H8/300 Dependent Features +========================= + +* Menu: + +* H8/300 Options:: Options +* H8/300 Syntax:: Syntax +* H8/300 Floating Point:: Floating Point +* H8/300 Directives:: H8/300 Machine Directives +* H8/300 Opcodes:: Opcodes + + +File: as.info, Node: H8/300 Options, Next: H8/300 Syntax, Up: H8/300-Dependent + +Options +------- + + `as' has no additional command-line options for the Hitachi H8/300 +family. + + +File: as.info, Node: H8/300 Syntax, Next: H8/300 Floating Point, Prev: H8/300 Options, Up: H8/300-Dependent + +Syntax +------ + +* Menu: + +* H8/300-Chars:: Special Characters +* H8/300-Regs:: Register Names +* H8/300-Addressing:: Addressing Modes + + +File: as.info, Node: H8/300-Chars, Next: H8/300-Regs, Up: H8/300 Syntax + +Special Characters +.................. + + `;' is the line comment character. + + `$' can be used instead of a newline to separate statements. +Therefore *you may not use `$' in symbol names* on the H8/300. + + +File: as.info, Node: H8/300-Regs, Next: H8/300-Addressing, Prev: H8/300-Chars, Up: H8/300 Syntax + +Register Names +.............. + + You can use predefined symbols of the form `rNh' and `rNl' to refer +to the H8/300 registers as sixteen 8-bit general-purpose registers. N +is a digit from `0' to `7'); for instance, both `r0h' and `r7l' are +valid register names. + + You can also use the eight predefined symbols `rN' to refer to the +H8/300 registers as 16-bit registers (you must use this form for +addressing). + + On the H8/300H, you can also use the eight predefined symbols `erN' +(`er0' ... `er7') to refer to the 32-bit general purpose registers. + + The two control registers are called `pc' (program counter; a 16-bit +register, except on the H8/300H where it is 24 bits) and `ccr' +(condition code register; an 8-bit register). `r7' is used as the +stack pointer, and can also be called `sp'. + + +File: as.info, Node: H8/300-Addressing, Prev: H8/300-Regs, Up: H8/300 Syntax + +Addressing Modes +................ + + as understands the following addressing modes for the H8/300: +`rN' + Register direct + +`@rN' + Register indirect + +`@(D, rN)' +`@(D:16, rN)' +`@(D:24, rN)' + Register indirect: 16-bit or 24-bit displacement D from register + N. (24-bit displacements are only meaningful on the H8/300H.) + +`@rN+' + Register indirect with post-increment + +`@-rN' + Register indirect with pre-decrement + +``@'AA' +``@'AA:8' +``@'AA:16' +``@'AA:24' + Absolute address `aa'. (The address size `:24' only makes sense + on the H8/300H.) + +`#XX' +`#XX:8' +`#XX:16' +`#XX:32' + Immediate data XX. You may specify the `:8', `:16', or `:32' for + clarity, if you wish; but `as' neither requires this nor uses + it--the data size required is taken from context. + +``@'`@'AA' +``@'`@'AA:8' + Memory indirect. You may specify the `:8' for clarity, if you + wish; but `as' neither requires this nor uses it. + + +File: as.info, Node: H8/300 Floating Point, Next: H8/300 Directives, Prev: H8/300 Syntax, Up: H8/300-Dependent + +Floating Point +-------------- + + The H8/300 family has no hardware floating point, but the `.float' +directive generates IEEE floating-point numbers for compatibility with +other development tools. + + +File: as.info, Node: H8/300 Directives, Next: H8/300 Opcodes, Prev: H8/300 Floating Point, Up: H8/300-Dependent + +H8/300 Machine Directives +------------------------- + + `as' has only one machine-dependent directive for the H8/300: + +`.h300h' + Recognize and emit additional instructions for the H8/300H + variant, and also make `.int' emit 32-bit numbers rather than the + usual (16-bit) for the H8/300 family. + + On the H8/300 family (including the H8/300H) `.word' directives +generate 16-bit numbers. + + +File: as.info, Node: H8/300 Opcodes, Prev: H8/300 Directives, Up: H8/300-Dependent + +Opcodes +------- + + For detailed information on the H8/300 machine instruction set, see +`H8/300 Series Programming Manual' (Hitachi ADE-602-025). For +information specific to the H8/300H, see `H8/300H Series Programming +Manual' (Hitachi). + + `as' implements all the standard H8/300 opcodes. No additional +pseudo-instructions are needed on this family. + + The following table summarizes the H8/300 opcodes, and their +arguments. Entries marked `*' are opcodes used only on the H8/300H. + + Legend: + Rs source register + Rd destination register + abs absolute address + imm immediate data + disp:N N-bit displacement from a register + pcrel:N N-bit displacement relative to program counter + + add.b #imm,rd * andc #imm,ccr + add.b rs,rd band #imm,rd + add.w rs,rd band #imm,@rd + * add.w #imm,rd band #imm,@abs:8 + * add.l rs,rd bra pcrel:8 + * add.l #imm,rd * bra pcrel:16 + adds #imm,rd bt pcrel:8 + addx #imm,rd * bt pcrel:16 + addx rs,rd brn pcrel:8 + and.b #imm,rd * brn pcrel:16 + and.b rs,rd bf pcrel:8 + * and.w rs,rd * bf pcrel:16 + * and.w #imm,rd bhi pcrel:8 + * and.l #imm,rd * bhi pcrel:16 + * and.l rs,rd bls pcrel:8 + + * bls pcrel:16 bld #imm,rd + bcc pcrel:8 bld #imm,@rd + * bcc pcrel:16 bld #imm,@abs:8 + bhs pcrel:8 bnot #imm,rd + * bhs pcrel:16 bnot #imm,@rd + bcs pcrel:8 bnot #imm,@abs:8 + * bcs pcrel:16 bnot rs,rd + blo pcrel:8 bnot rs,@rd + * blo pcrel:16 bnot rs,@abs:8 + bne pcrel:8 bor #imm,rd + * bne pcrel:16 bor #imm,@rd + beq pcrel:8 bor #imm,@abs:8 + * beq pcrel:16 bset #imm,rd + bvc pcrel:8 bset #imm,@rd + * bvc pcrel:16 bset #imm,@abs:8 + bvs pcrel:8 bset rs,rd + * bvs pcrel:16 bset rs,@rd + bpl pcrel:8 bset rs,@abs:8 + * bpl pcrel:16 bsr pcrel:8 + bmi pcrel:8 bsr pcrel:16 + * bmi pcrel:16 bst #imm,rd + bge pcrel:8 bst #imm,@rd + * bge pcrel:16 bst #imm,@abs:8 + blt pcrel:8 btst #imm,rd + * blt pcrel:16 btst #imm,@rd + bgt pcrel:8 btst #imm,@abs:8 + * bgt pcrel:16 btst rs,rd + ble pcrel:8 btst rs,@rd + * ble pcrel:16 btst rs,@abs:8 + bclr #imm,rd bxor #imm,rd + bclr #imm,@rd bxor #imm,@rd + bclr #imm,@abs:8 bxor #imm,@abs:8 + bclr rs,rd cmp.b #imm,rd + bclr rs,@rd cmp.b rs,rd + bclr rs,@abs:8 cmp.w rs,rd + biand #imm,rd cmp.w rs,rd + biand #imm,@rd * cmp.w #imm,rd + biand #imm,@abs:8 * cmp.l #imm,rd + bild #imm,rd * cmp.l rs,rd + bild #imm,@rd daa rs + bild #imm,@abs:8 das rs + bior #imm,rd dec.b rs + bior #imm,@rd * dec.w #imm,rd + bior #imm,@abs:8 * dec.l #imm,rd + bist #imm,rd divxu.b rs,rd + bist #imm,@rd * divxu.w rs,rd + bist #imm,@abs:8 * divxs.b rs,rd + bixor #imm,rd * divxs.w rs,rd + bixor #imm,@rd eepmov + bixor #imm,@abs:8 * eepmovw + + * exts.w rd mov.w rs,@abs:16 + * exts.l rd * mov.l #imm,rd + * extu.w rd * mov.l rs,rd + * extu.l rd * mov.l @rs,rd + inc rs * mov.l @(disp:16,rs),rd + * inc.w #imm,rd * mov.l @(disp:24,rs),rd + * inc.l #imm,rd * mov.l @rs+,rd + jmp @rs * mov.l @abs:16,rd + jmp abs * mov.l @abs:24,rd + jmp @@abs:8 * mov.l rs,@rd + jsr @rs * mov.l rs,@(disp:16,rd) + jsr abs * mov.l rs,@(disp:24,rd) + jsr @@abs:8 * mov.l rs,@-rd + ldc #imm,ccr * mov.l rs,@abs:16 + ldc rs,ccr * mov.l rs,@abs:24 + * ldc @abs:16,ccr movfpe @abs:16,rd + * ldc @abs:24,ccr movtpe rs,@abs:16 + * ldc @(disp:16,rs),ccr mulxu.b rs,rd + * ldc @(disp:24,rs),ccr * mulxu.w rs,rd + * ldc @rs+,ccr * mulxs.b rs,rd + * ldc @rs,ccr * mulxs.w rs,rd + * mov.b @(disp:24,rs),rd neg.b rs + * mov.b rs,@(disp:24,rd) * neg.w rs + mov.b @abs:16,rd * neg.l rs + mov.b rs,rd nop + mov.b @abs:8,rd not.b rs + mov.b rs,@abs:8 * not.w rs + mov.b rs,rd * not.l rs + mov.b #imm,rd or.b #imm,rd + mov.b @rs,rd or.b rs,rd + mov.b @(disp:16,rs),rd * or.w #imm,rd + mov.b @rs+,rd * or.w rs,rd + mov.b @abs:8,rd * or.l #imm,rd + mov.b rs,@rd * or.l rs,rd + mov.b rs,@(disp:16,rd) orc #imm,ccr + mov.b rs,@-rd pop.w rs + mov.b rs,@abs:8 * pop.l rs + mov.w rs,@rd push.w rs + * mov.w @(disp:24,rs),rd * push.l rs + * mov.w rs,@(disp:24,rd) rotl.b rs + * mov.w @abs:24,rd * rotl.w rs + * mov.w rs,@abs:24 * rotl.l rs + mov.w rs,rd rotr.b rs + mov.w #imm,rd * rotr.w rs + mov.w @rs,rd * rotr.l rs + mov.w @(disp:16,rs),rd rotxl.b rs + mov.w @rs+,rd * rotxl.w rs + mov.w @abs:16,rd * rotxl.l rs + mov.w rs,@(disp:16,rd) rotxr.b rs + mov.w rs,@-rd * rotxr.w rs + + * rotxr.l rs * stc ccr,@(disp:24,rd) + bpt * stc ccr,@-rd + rte * stc ccr,@abs:16 + rts * stc ccr,@abs:24 + shal.b rs sub.b rs,rd + * shal.w rs sub.w rs,rd + * shal.l rs * sub.w #imm,rd + shar.b rs * sub.l rs,rd + * shar.w rs * sub.l #imm,rd + * shar.l rs subs #imm,rd + shll.b rs subx #imm,rd + * shll.w rs subx rs,rd + * shll.l rs * trapa #imm + shlr.b rs xor #imm,rd + * shlr.w rs xor rs,rd + * shlr.l rs * xor.w #imm,rd + sleep * xor.w rs,rd + stc ccr,rd * xor.l #imm,rd + * stc ccr,@rs * xor.l rs,rd + * stc ccr,@(disp:16,rd) xorc #imm,ccr + + Four H8/300 instructions (`add', `cmp', `mov', `sub') are defined +with variants using the suffixes `.b', `.w', and `.l' to specify the +size of a memory operand. `as' supports these suffixes, but does not +require them; since one of the operands is always a register, `as' can +deduce the correct size. + + For example, since `r0' refers to a 16-bit register, + mov r0,@foo +is equivalent to + mov.w r0,@foo + + If you use the size suffixes, `as' issues a warning when the suffix +and the register size do not match. + + +File: as.info, Node: H8/500-Dependent, Next: SH-Dependent, Prev: H8/300-Dependent, Up: Machine Dependencies + +H8/500 Dependent Features +========================= + +* Menu: + +* H8/500 Options:: Options +* H8/500 Syntax:: Syntax +* H8/500 Floating Point:: Floating Point +* H8/500 Directives:: H8/500 Machine Directives +* H8/500 Opcodes:: Opcodes + + +File: as.info, Node: H8/500 Options, Next: H8/500 Syntax, Up: H8/500-Dependent + +Options +------- + + `as' has no additional command-line options for the Hitachi H8/500 +family. + + +File: as.info, Node: H8/500 Syntax, Next: H8/500 Floating Point, Prev: H8/500 Options, Up: H8/500-Dependent + +Syntax +------ + +* Menu: + +* H8/500-Chars:: Special Characters +* H8/500-Regs:: Register Names +* H8/500-Addressing:: Addressing Modes + + +File: as.info, Node: H8/500-Chars, Next: H8/500-Regs, Up: H8/500 Syntax + +Special Characters +.................. + + `!' is the line comment character. + + `;' can be used instead of a newline to separate statements. + + Since `$' has no special meaning, you may use it in symbol names. + + +File: as.info, Node: H8/500-Regs, Next: H8/500-Addressing, Prev: H8/500-Chars, Up: H8/500 Syntax + +Register Names +.............. + + You can use the predefined symbols `r0', `r1', `r2', `r3', `r4', +`r5', `r6', and `r7' to refer to the H8/500 registers. + + The H8/500 also has these control registers: + +`cp' + code pointer + +`dp' + data pointer + +`bp' + base pointer + +`tp' + stack top pointer + +`ep' + extra pointer + +`sr' + status register + +`ccr' + condition code register + + All registers are 16 bits long. To represent 32 bit numbers, use two +adjacent registers; for distant memory addresses, use one of the segment +pointers (`cp' for the program counter; `dp' for `r0'-`r3'; `ep' for +`r4' and `r5'; and `tp' for `r6' and `r7'. + + +File: as.info, Node: H8/500-Addressing, Prev: H8/500-Regs, Up: H8/500 Syntax + +Addressing Modes +................ + + as understands the following addressing modes for the H8/500: +`RN' + Register direct + +`@RN' + Register indirect + +`@(d:8, RN)' + Register indirect with 8 bit signed displacement + +`@(d:16, RN)' + Register indirect with 16 bit signed displacement + +`@-RN' + Register indirect with pre-decrement + +`@RN+' + Register indirect with post-increment + +`@AA:8' + 8 bit absolute address + +`@AA:16' + 16 bit absolute address + +`#XX:8' + 8 bit immediate + +`#XX:16' + 16 bit immediate + + +File: as.info, Node: H8/500 Floating Point, Next: H8/500 Directives, Prev: H8/500 Syntax, Up: H8/500-Dependent + +Floating Point +-------------- + + The H8/500 family uses IEEE floating-point numbers. + + +File: as.info, Node: H8/500 Directives, Next: H8/500 Opcodes, Prev: H8/500 Floating Point, Up: H8/500-Dependent + +H8/500 Machine Directives +------------------------- + + `as' has no machine-dependent directives for the H8/500. However, +on this platform the `.int' and `.word' directives generate 16-bit +numbers. + + +File: as.info, Node: H8/500 Opcodes, Prev: H8/500 Directives, Up: H8/500-Dependent + +Opcodes +------- + + For detailed information on the H8/500 machine instruction set, see +`H8/500 Series Programming Manual' (Hitachi M21T001). + + `as' implements all the standard H8/500 opcodes. No additional +pseudo-instructions are needed on this family. + + The following table summarizes H8/500 opcodes and their operands: + + Legend: + abs8 8-bit absolute address + abs16 16-bit absolute address + abs24 24-bit absolute address + crb `ccr', `br', `ep', `dp', `tp', `dp' + disp8 8-bit displacement + ea `rn', `@rn', `@(d:8, rn)', `@(d:16, rn)', + `@-rn', `@rn+', `@aa:8', `@aa:16', + `#xx:8', `#xx:16' + ea_mem `@rn', `@(d:8, rn)', `@(d:16, rn)', + `@-rn', `@rn+', `@aa:8', `@aa:16' + ea_noimm `rn', `@rn', `@(d:8, rn)', `@(d:16, rn)', + `@-rn', `@rn+', `@aa:8', `@aa:16' + fp r6 + imm4 4-bit immediate data + imm8 8-bit immediate data + imm16 16-bit immediate data + pcrel8 8-bit offset from program counter + pcrel16 16-bit offset from program counter + qim `-2', `-1', `1', `2' + rd any register + rs a register distinct from rd + rlist comma-separated list of registers in parentheses; + register ranges `rd-rs' are allowed + sp stack pointer (`r7') + sr status register + sz size; `.b' or `.w'. If omitted, default `.w' + + ldc[.b] ea,crb bcc[.w] pcrel16 + ldc[.w] ea,sr bcc[.b] pcrel8 + add[:q] sz qim,ea_noimm bhs[.w] pcrel16 + add[:g] sz ea,rd bhs[.b] pcrel8 + adds sz ea,rd bcs[.w] pcrel16 + addx sz ea,rd bcs[.b] pcrel8 + and sz ea,rd blo[.w] pcrel16 + andc[.b] imm8,crb blo[.b] pcrel8 + andc[.w] imm16,sr bne[.w] pcrel16 + bpt bne[.b] pcrel8 + bra[.w] pcrel16 beq[.w] pcrel16 + bra[.b] pcrel8 beq[.b] pcrel8 + bt[.w] pcrel16 bvc[.w] pcrel16 + bt[.b] pcrel8 bvc[.b] pcrel8 + brn[.w] pcrel16 bvs[.w] pcrel16 + brn[.b] pcrel8 bvs[.b] pcrel8 + bf[.w] pcrel16 bpl[.w] pcrel16 + bf[.b] pcrel8 bpl[.b] pcrel8 + bhi[.w] pcrel16 bmi[.w] pcrel16 + bhi[.b] pcrel8 bmi[.b] pcrel8 + bls[.w] pcrel16 bge[.w] pcrel16 + bls[.b] pcrel8 bge[.b] pcrel8 + + blt[.w] pcrel16 mov[:g][.b] imm8,ea_mem + blt[.b] pcrel8 mov[:g][.w] imm16,ea_mem + bgt[.w] pcrel16 movfpe[.b] ea,rd + bgt[.b] pcrel8 movtpe[.b] rs,ea_noimm + ble[.w] pcrel16 mulxu sz ea,rd + ble[.b] pcrel8 neg sz ea + bclr sz imm4,ea_noimm nop + bclr sz rs,ea_noimm not sz ea + bnot sz imm4,ea_noimm or sz ea,rd + bnot sz rs,ea_noimm orc[.b] imm8,crb + bset sz imm4,ea_noimm orc[.w] imm16,sr + bset sz rs,ea_noimm pjmp abs24 + bsr[.b] pcrel8 pjmp @rd + bsr[.w] pcrel16 pjsr abs24 + btst sz imm4,ea_noimm pjsr @rd + btst sz rs,ea_noimm prtd imm8 + clr sz ea prtd imm16 + cmp[:e][.b] imm8,rd prts + cmp[:i][.w] imm16,rd rotl sz ea + cmp[:g].b imm8,ea_noimm rotr sz ea + cmp[:g][.w] imm16,ea_noimm rotxl sz ea + Cmp[:g] sz ea,rd rotxr sz ea + dadd rs,rd rtd imm8 + divxu sz ea,rd rtd imm16 + dsub rs,rd rts + exts[.b] rd scb/f rs,pcrel8 + extu[.b] rd scb/ne rs,pcrel8 + jmp @rd scb/eq rs,pcrel8 + jmp @(imm8,rd) shal sz ea + jmp @(imm16,rd) shar sz ea + jmp abs16 shll sz ea + jsr @rd shlr sz ea + jsr @(imm8,rd) sleep + jsr @(imm16,rd) stc[.b] crb,ea_noimm + jsr abs16 stc[.w] sr,ea_noimm + ldm @sp+,(rlist) stm (rlist),@-sp + link fp,imm8 sub sz ea,rd + link fp,imm16 subs sz ea,rd + mov[:e][.b] imm8,rd subx sz ea,rd + mov[:i][.w] imm16,rd swap[.b] rd + mov[:l][.w] abs8,rd tas[.b] ea + mov[:l].b abs8,rd trapa imm4 + mov[:s][.w] rs,abs8 trap/vs + mov[:s].b rs,abs8 tst sz ea + mov[:f][.w] @(disp8,fp),rd unlk fp + mov[:f][.w] rs,@(disp8,fp) xch[.w] rs,rd + mov[:f].b @(disp8,fp),rd xor sz ea,rd + mov[:f].b rs,@(disp8,fp) xorc.b imm8,crb + mov[:g] sz rs,ea_mem xorc.w imm16,sr + mov[:g] sz ea,rd + + +File: as.info, Node: SH-Dependent, Next: i960-Dependent, Prev: H8/500-Dependent, Up: Machine Dependencies + +Hitachi SH Dependent Features +============================= + +* Menu: + +* SH Options:: Options +* SH Syntax:: Syntax +* SH Floating Point:: Floating Point +* SH Directives:: SH Machine Directives +* SH Opcodes:: Opcodes + + +File: as.info, Node: SH Options, Next: SH Syntax, Up: SH-Dependent + +Options +------- + + `as' has no additional command-line options for the Hitachi SH +family. + + +File: as.info, Node: SH Syntax, Next: SH Floating Point, Prev: SH Options, Up: SH-Dependent + +Syntax +------ + +* Menu: + +* SH-Chars:: Special Characters +* SH-Regs:: Register Names +* SH-Addressing:: Addressing Modes + + +File: as.info, Node: SH-Chars, Next: SH-Regs, Up: SH Syntax + +Special Characters +.................. + + `!' is the line comment character. + + You can use `;' instead of a newline to separate statements. + + Since `$' has no special meaning, you may use it in symbol names. + + +File: as.info, Node: SH-Regs, Next: SH-Addressing, Prev: SH-Chars, Up: SH Syntax + +Register Names +.............. + + You can use the predefined symbols `r0', `r1', `r2', `r3', `r4', +`r5', `r6', `r7', `r8', `r9', `r10', `r11', `r12', `r13', `r14', and +`r15' to refer to the SH registers. + + The SH also has these control registers: + +`pr' + procedure register (holds return address) + +`pc' + program counter + +`mach' +`macl' + high and low multiply accumulator registers + +`sr' + status register + +`gbr' + global base register + +`vbr' + vector base register (for interrupt vectors) + + +File: as.info, Node: SH-Addressing, Prev: SH-Regs, Up: SH Syntax + +Addressing Modes +................ + + `as' understands the following addressing modes for the SH. `RN' in +the following refers to any of the numbered registers, but *not* the +control registers. + +`RN' + Register direct + +`@RN' + Register indirect + +`@-RN' + Register indirect with pre-decrement + +`@RN+' + Register indirect with post-increment + +`@(DISP, RN)' + Register indirect with displacement + +`@(R0, RN)' + Register indexed + +`@(DISP, GBR)' + `GBR' offset + +`@(R0, GBR)' + GBR indexed + +`ADDR' +`@(DISP, PC)' + PC relative address (for branch or for addressing memory). The + `as' implementation allows you to use the simpler form ADDR + anywhere a PC relative address is called for; the alternate form + is supported for compatibility with other assemblers. + +`#IMM' + Immediate data + + +File: as.info, Node: SH Floating Point, Next: SH Directives, Prev: SH Syntax, Up: SH-Dependent + +Floating Point +-------------- + + The SH family uses IEEE floating-point numbers. + + +File: as.info, Node: SH Directives, Next: SH Opcodes, Prev: SH Floating Point, Up: SH-Dependent + +SH Machine Directives +--------------------- + + `as' has no machine-dependent directives for the SH. + + +File: as.info, Node: SH Opcodes, Prev: SH Directives, Up: SH-Dependent + +Opcodes +------- + + For detailed information on the SH machine instruction set, see +`SH-Microcomputer User's Manual' (Hitachi Micro Systems, Inc.). + + `as' implements all the standard SH opcodes. No additional +pseudo-instructions are needed on this family. Note, however, that +because `as' supports a simpler form of PC-relative addressing, you may +simply write (for example) + + mov.l bar,r0 + +where other assemblers might require an explicit displacement to `bar' +from the program counter: + + mov.l @(DISP, PC) + + Here is a summary of SH opcodes: + + Legend: + Rn a numbered register + Rm another numbered register + #imm immediate data + disp displacement + disp8 8-bit displacement + disp12 12-bit displacement + + add #imm,Rn lds.l @Rn+,PR + add Rm,Rn mac.w @Rm+,@Rn+ + addc Rm,Rn mov #imm,Rn + addv Rm,Rn mov Rm,Rn + and #imm,R0 mov.b Rm,@(R0,Rn) + and Rm,Rn mov.b Rm,@-Rn + and.b #imm,@(R0,GBR) mov.b Rm,@Rn + bf disp8 mov.b @(disp,Rm),R0 + bra disp12 mov.b @(disp,GBR),R0 + bsr disp12 mov.b @(R0,Rm),Rn + bt disp8 mov.b @Rm+,Rn + clrm mov.b @Rm,Rn + clrt mov.b R0,@(disp,Rm) + cmp/eq #imm,R0 mov.b R0,@(disp,GBR) + cmp/eq Rm,Rn mov.l Rm,@(disp,Rn) + cmp/ge Rm,Rn mov.l Rm,@(R0,Rn) + cmp/gt Rm,Rn mov.l Rm,@-Rn + cmp/hi Rm,Rn mov.l Rm,@Rn + cmp/hs Rm,Rn mov.l @(disp,Rn),Rm + cmp/pl Rn mov.l @(disp,GBR),R0 + cmp/pz Rn mov.l @(disp,PC),Rn + cmp/str Rm,Rn mov.l @(R0,Rm),Rn + div0s Rm,Rn mov.l @Rm+,Rn + div0u mov.l @Rm,Rn + div1 Rm,Rn mov.l R0,@(disp,GBR) + exts.b Rm,Rn mov.w Rm,@(R0,Rn) + exts.w Rm,Rn mov.w Rm,@-Rn + extu.b Rm,Rn mov.w Rm,@Rn + extu.w Rm,Rn mov.w @(disp,Rm),R0 + jmp @Rn mov.w @(disp,GBR),R0 + jsr @Rn mov.w @(disp,PC),Rn + ldc Rn,GBR mov.w @(R0,Rm),Rn + ldc Rn,SR mov.w @Rm+,Rn + ldc Rn,VBR mov.w @Rm,Rn + ldc.l @Rn+,GBR mov.w R0,@(disp,Rm) + ldc.l @Rn+,SR mov.w R0,@(disp,GBR) + ldc.l @Rn+,VBR mova @(disp,PC),R0 + lds Rn,MACH movt Rn + lds Rn,MACL muls Rm,Rn + lds Rn,PR mulu Rm,Rn + lds.l @Rn+,MACH neg Rm,Rn + lds.l @Rn+,MACL negc Rm,Rn + + nop stc VBR,Rn + not Rm,Rn stc.l GBR,@-Rn + or #imm,R0 stc.l SR,@-Rn + or Rm,Rn stc.l VBR,@-Rn + or.b #imm,@(R0,GBR) sts MACH,Rn + rotcl Rn sts MACL,Rn + rotcr Rn sts PR,Rn + rotl Rn sts.l MACH,@-Rn + rotr Rn sts.l MACL,@-Rn + rte sts.l PR,@-Rn + rts sub Rm,Rn + sett subc Rm,Rn + shal Rn subv Rm,Rn + shar Rn swap.b Rm,Rn + shll Rn swap.w Rm,Rn + shll16 Rn tas.b @Rn + shll2 Rn trapa #imm + shll8 Rn tst #imm,R0 + shlr Rn tst Rm,Rn + shlr16 Rn tst.b #imm,@(R0,GBR) + shlr2 Rn xor #imm,R0 + shlr8 Rn xor Rm,Rn + sleep xor.b #imm,@(R0,GBR) + stc GBR,Rn xtrct Rm,Rn + stc SR,Rn + + +File: as.info, Node: i960-Dependent, Next: M68K-Dependent, Prev: SH-Dependent, Up: Machine Dependencies + +Intel 80960 Dependent Features +============================== + +* Menu: + +* Options-i960:: i960 Command-line Options +* Floating Point-i960:: Floating Point +* Directives-i960:: i960 Machine Directives +* Opcodes for i960:: i960 Opcodes + + +File: as.info, Node: Options-i960, Next: Floating Point-i960, Up: i960-Dependent + +i960 Command-line Options +------------------------- + +`-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC' + Select the 80960 architecture. Instructions or features not + supported by the selected architecture cause fatal errors. + + `-ACA' is equivalent to `-ACA_A'; `-AKC' is equivalent to `-AMC'. + Synonyms are provided for compatibility with other tools. + + If none of these options is specified, `as' will generate code for + any instruction or feature that is supported by *some* version of + the 960 (even if this means mixing architectures!). In principle, + `as' will attempt to deduce the minimal sufficient processor type + if none is specified; depending on the object code format, the + processor type may be recorded in the object file. If it is + critical that the `as' output match a specific architecture, + specify that architecture explicitly. + +`-b' + Add code to collect information about conditional branches taken, + for later optimization using branch prediction bits. (The + conditional branch instructions have branch prediction bits in the + CA, CB, and CC architectures.) If BR represents a conditional + branch instruction, the following represents the code generated by + the assembler when `-b' is specified: + + call INCREMENT ROUTINE + .word 0 # pre-counter + Label: BR + call INCREMENT ROUTINE + .word 0 # post-counter + + The counter following a branch records the number of times that + branch was *not* taken; the differenc between the two counters is + the number of times the branch *was* taken. + + A table of every such `Label' is also generated, so that the + external postprocessor `gbr960' (supplied by Intel) can locate all + the counters. This table is always labelled `__BRANCH_TABLE__'; + this is a local symbol to permit collecting statistics for many + separate object files. The table is word aligned, and begins with + a two-word header. The first word, initialized to 0, is used in + maintaining linked lists of branch tables. The second word is a + count of the number of entries in the table, which follow + immediately: each is a word, pointing to one of the labels + illustrated above. + + +------------+------------+------------+ ... +------------+ + | | | | | | + | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N | + | | | | | | + +------------+------------+------------+ ... +------------+ + + __BRANCH_TABLE__ layout + + The first word of the header is used to locate multiple branch + tables, since each object file may contain one. Normally the links + are maintained with a call to an initialization routine, placed at + the beginning of each function in the file. The GNU C compiler + will generate these calls automatically when you give it a `-b' + option. For further details, see the documentation of `gbr960'. + +`-norelax' + Normally, Compare-and-Branch instructions with targets that require + displacements greater than 13 bits (or that have external targets) + are replaced with the corresponding compare (or `chkbit') and + branch instructions. You can use the `-norelax' option to specify + that `as' should generate errors instead, if the target + displacement is larger than 13 bits. + + This option does not affect the Compare-and-Jump instructions; the + code emitted for them is *always* adjusted when necessary + (depending on displacement size), regardless of whether you use + `-norelax'. + + +File: as.info, Node: Floating Point-i960, Next: Directives-i960, Prev: Options-i960, Up: i960-Dependent + +Floating Point +-------------- + + `as' generates IEEE floating-point numbers for the directives +`.float', `.double', `.extended', and `.single'. + + +File: as.info, Node: Directives-i960, Next: Opcodes for i960, Prev: Floating Point-i960, Up: i960-Dependent + +i960 Machine Directives +----------------------- + +`.bss SYMBOL, LENGTH, ALIGN' + Reserve LENGTH bytes in the bss section for a local SYMBOL, + aligned to the power of two specified by ALIGN. LENGTH and ALIGN + must be positive absolute expressions. This directive differs + from `.lcomm' only in that it permits you to specify an alignment. + *Note `.lcomm': Lcomm. + +`.extended FLONUMS' + `.extended' expects zero or more flonums, separated by commas; for + each flonum, `.extended' emits an IEEE extended-format (80-bit) + floating-point number. + +`.leafproc CALL-LAB, BAL-LAB' + You can use the `.leafproc' directive in conjunction with the + optimized `callj' instruction to enable faster calls of leaf + procedures. If a procedure is known to call no other procedures, + you may define an entry point that skips procedure prolog code + (and that does not depend on system-supplied saved context), and + declare it as the BAL-LAB using `.leafproc'. If the procedure + also has an entry point that goes through the normal prolog, you + can specify that entry point as CALL-LAB. + + A `.leafproc' declaration is meant for use in conjunction with the + optimized call instruction `callj'; the directive records the data + needed later to choose between converting the `callj' into a `bal' + or a `call'. + + CALL-LAB is optional; if only one argument is present, or if the + two arguments are identical, the single argument is assumed to be + the `bal' entry point. + +`.sysproc NAME, INDEX' + The `.sysproc' directive defines a name for a system procedure. + After you define it using `.sysproc', you can use NAME to refer to + the system procedure identified by INDEX when calling procedures + with the optimized call instruction `callj'. + + Both arguments are required; INDEX must be between 0 and 31 + (inclusive). + + +File: as.info, Node: Opcodes for i960, Prev: Directives-i960, Up: i960-Dependent + +i960 Opcodes +------------ + + All Intel 960 machine instructions are supported; *note i960 +Command-line Options: Options-i960. for a discussion of selecting the +instruction subset for a particular 960 architecture. + + Some opcodes are processed beyond simply emitting a single +corresponding instruction: `callj', and Compare-and-Branch or +Compare-and-Jump instructions with target displacements larger than 13 +bits. + +* Menu: + +* callj-i960:: `callj' +* Compare-and-branch-i960:: Compare-and-Branch + + +File: as.info, Node: callj-i960, Next: Compare-and-branch-i960, Up: Opcodes for i960 + +`callj' +....... + + You can write `callj' to have the assembler or the linker determine +the most appropriate form of subroutine call: `call', `bal', or +`calls'. If the assembly source contains enough information--a +`.leafproc' or `.sysproc' directive defining the operand--then `as' +will translate the `callj'; if not, it will simply emit the `callj', +leaving it for the linker to resolve. + + +File: as.info, Node: Compare-and-branch-i960, Prev: callj-i960, Up: Opcodes for i960 + +Compare-and-Branch +.................. + + The 960 architectures provide combined Compare-and-Branch +instructions that permit you to store the branch target in the lower 13 +bits of the instruction word itself. However, if you specify a branch +target far enough away that its address won't fit in 13 bits, the +assembler can either issue an error, or convert your Compare-and-Branch +instruction into separate instructions to do the compare and the branch. + + Whether `as' gives an error or expands the instruction depends on +two choices you can make: whether you use the `-norelax' option, and +whether you use a "Compare and Branch" instruction or a "Compare and +Jump" instruction. The "Jump" instructions are *always* expanded if +necessary; the "Branch" instructions are expanded when necessary +*unless* you specify `-norelax'--in which case `as' gives an error +instead. + + These are the Compare-and-Branch instructions, their "Jump" variants, +and the instruction pairs they may expand into: + + Compare and + Branch Jump Expanded to + ------ ------ ------------ + bbc chkbit; bno + bbs chkbit; bo + cmpibe cmpije cmpi; be + cmpibg cmpijg cmpi; bg + cmpibge cmpijge cmpi; bge + cmpibl cmpijl cmpi; bl + cmpible cmpijle cmpi; ble + cmpibno cmpijno cmpi; bno + cmpibne cmpijne cmpi; bne + cmpibo cmpijo cmpi; bo + cmpobe cmpoje cmpo; be + cmpobg cmpojg cmpo; bg + cmpobge cmpojge cmpo; bge + cmpobl cmpojl cmpo; bl + cmpoble cmpojle cmpo; ble + cmpobne cmpojne cmpo; bne + + +File: as.info, Node: M68K-Dependent, Next: Sparc-Dependent, Prev: i960-Dependent, Up: Machine Dependencies + +M680x0 Dependent Features +========================= + +* Menu: + +* M68K-Opts:: M680x0 Options +* M68K-Syntax:: Syntax +* M68K-Moto-Syntax:: Motorola Syntax +* M68K-Float:: Floating Point +* M68K-Directives:: 680x0 Machine Directives +* M68K-opcodes:: Opcodes + + +File: as.info, Node: M68K-Opts, Next: M68K-Syntax, Up: M68K-Dependent + +M680x0 Options +-------------- + + The Motorola 680x0 version of `as' has two machine dependent options. +One shortens undefined references from 32 to 16 bits, while the other +is used to tell `as' what kind of machine it is assembling for. + + You can use the `-l' option to shorten the size of references to +undefined symbols. If the `-l' option is not given, references to +undefined symbols will be a full long (32 bits) wide. (Since `as' +cannot know where these symbols will end up, `as' can only allocate +space for the linker to fill in later. Since `as' doesn't know how far +away these symbols will be, it allocates as much space as it can.) If +this option is given, the references will only be one word wide (16 +bits). This may be useful if you want the object file to be as small as +possible, and you know that the relevant symbols will be less than 17 +bits away. + + The 680x0 version of `as' is most frequently used to assemble +programs for the Motorola MC68020 microprocessor. Occasionally it is +used to assemble programs for the mostly similar, but slightly different +MC68000 or MC68010 microprocessors. You can give `as' the options +`-m68000', `-mc68000', `-m68010', `-mc68010', `-m68020', and `-mc68020' +to tell it what processor is the target. + + +File: as.info, Node: M68K-Syntax, Next: M68K-Moto-Syntax, Prev: M68K-Opts, Up: M68K-Dependent + +Syntax +------ + + This syntax for the Motorola 680x0 was developed at MIT. + + The 680x0 version of `as' uses syntax similar to the Sun assembler. +Intervening periods are now ignored; for example, `movl' is equivalent +to `move.l'. + + In the following table "apc" stands for any of the address registers +(`a0' through `a7'), nothing, (`'), the Program Counter (`pc'), or the +zero-address relative to the program counter (`zpc'). + + The following addressing modes are understood: +"Immediate" + `#DIGITS' + +"Data Register" + `d0' through `d7' + +"Address Register" + `a0' through `a7' + +"Address Register Indirect" + `a0@' through `a7@' + `a7' is also known as `sp', i.e. the Stack Pointer. `a6' is also + known as `fp', the Frame Pointer. + +"Address Register Postincrement" + `a0@+' through `a7@+' + +"Address Register Predecrement" + `a0@-' through `a7@-' + +"Indirect Plus Offset" + `APC@(DIGITS)' + +"Index" + `APC@(DIGITS,REGISTER:SIZE:SCALE)' + + or `APC@(REGISTER:SIZE:SCALE)' + +"Postindex" + `APC@(DIGITS)@(DIGITS,REGISTER:SIZE:SCALE)' + + or `APC@(DIGITS)@(REGISTER:SIZE:SCALE)' + +"Preindex" + `APC@(DIGITS,REGISTER:SIZE:SCALE)@(DIGITS)' + + or `APC@(REGISTER:SIZE:SCALE)@(DIGITS)' + +"Memory Indirect" + `APC@(DIGITS)@(DIGITS)' + +"Absolute" + `SYMBOL', or `DIGITS' + + For some configurations, especially those where the compiler normally +does not prepend an underscore to the names of user variables, the +assembler requires a `%' before any use of a register name. This is +intended to let the assembler distinguish between user variables and +registers named `a0' through `a7', et cetera. The `%' is always +accepted, but is only required for some configurations, notably +`m68k-coff'. + + +File: as.info, Node: M68K-Moto-Syntax, Next: M68K-Float, Prev: M68K-Syntax, Up: M68K-Dependent + +Motorola Syntax +--------------- + + The standard Motorola syntax for this chip differs from the syntax +already discussed (*note Syntax: M68K-Syntax.). `as' can accept both +kinds of syntax, even within a single instruction. The syntaxes are +fully compatible, because the Motorola syntax never uses the `@' +character and the MIT syntax always does, except in cases where the +syntaxes are identical. + + In particular, you may write or generate M68K assembler with the +following conventions: + + (In the following table "apc" stands for any of the address +registers (`a0' through `a7'), nothing, (`'), the Program Counter +(`pc'), or the zero-address relative to the program counter (`zpc').) + + The following additional addressing modes are understood: +"Address Register Indirect" + `a0' through `a7' + `a7' is also known as `sp', i.e. the Stack Pointer. `a6' is also + known as `fp', the Frame Pointer. + +"Address Register Postincrement" + `(a0)+' through `(a7)+' + +"Address Register Predecrement" + `-(a0)' through `-(a7)' + +"Indirect Plus Offset" + `DIGITS(APC)' + +"Index" + `DIGITS(APC,(REGISTER.SIZE*SCALE)' + or `(APC,REGISTER.SIZE*SCALE)' + In either case, SIZE and SCALE are optional (SCALE defaults to + `1', SIZE defaults to `l'). SCALE can be `1', `2', `4', or `8'. + SIZE can be `w' or `l'. SCALE is only supported on the 68020 and + greater. + + +File: as.info, Node: M68K-Float, Next: M68K-Directives, Prev: M68K-Moto-Syntax, Up: M68K-Dependent + +Floating Point +-------------- + + The floating point code is not too well tested, and may have subtle +bugs in it. + + Packed decimal (P) format floating literals are not supported. Feel +free to add the code! + + The floating point formats generated by directives are these. + +`.float' + `Single' precision floating point constants. + +`.double' + `Double' precision floating point constants. + + There is no directive to produce regions of memory holding extended +precision numbers, however they can be used as immediate operands to +floating-point instructions. Adding a directive to create extended +precision numbers would not be hard, but it has not yet seemed +necessary. + + +File: as.info, Node: M68K-Directives, Next: M68K-opcodes, Prev: M68K-Float, Up: M68K-Dependent + +680x0 Machine Directives +------------------------ + + In order to be compatible with the Sun assembler the 680x0 assembler +understands the following directives. + +`.data1' + This directive is identical to a `.data 1' directive. + +`.data2' + This directive is identical to a `.data 2' directive. + +`.even' + This directive is identical to a `.align 1' directive. + +`.skip' + This directive is identical to a `.space' directive. + + +File: as.info, Node: M68K-opcodes, Prev: M68K-Directives, Up: M68K-Dependent + +Opcodes +------- + +* Menu: + +* M68K-Branch:: Branch Improvement +* M68K-Chars:: Special Characters + + +File: as.info, Node: M68K-Branch, Next: M68K-Chars, Up: M68K-opcodes + +Branch Improvement +.................. + + Certain pseudo opcodes are permitted 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 Motorola mnemonic. + + The following table summarizes the pseudo-operations. A `*' flags +cases that are more fully described after the table: + + Displacement + +------------------------------------------------- + | 68020 68000/10 + Pseudo-Op |BYTE WORD LONG LONG non-PC relative + +------------------------------------------------- + jbsr |bsrs bsr bsrl jsr jsr + jra |bras bra bral jmp jmp + * jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp + * dbXX |dbXX dbXX dbXX; bra; jmpl + * fjXX |fbXXw fbXXw fbXXl fbNXw;jmp + + XX: condition + NX: negative of condition XX + + `*'--see full description below + +`jbsr' +`jra' + These are the simplest jump pseudo-operations; they always map to + one particular machine instruction, depending on the displacement + to the branch target. + +`jXX' + Here, `jXX' stands for an entire family of pseudo-operations, + where XX is a conditional branch or condition-code test. The full + list of pseudo-ops in this family is: + jhi jls jcc jcs jne jeq jvc + jvs jpl jmi jge jlt jgt jle + + For the cases of non-PC relative displacements and long + displacements on the 68000 or 68010, `as' will issue a longer code + fragment in terms of NX, the opposite condition to XX. For + example, for the non-PC relative case: + jXX foo + gives + bNXs oof + jmp foo + oof: + +`dbXX' + The full family of pseudo-operations covered here is + dbhi dbls dbcc dbcs dbne dbeq dbvc + dbvs dbpl dbmi dbge dblt dbgt dble + dbf dbra dbt + + Other than for word and byte displacements, when the source reads + `dbXX foo', `as' will emit + dbXX oo1 + bra oo2 + oo1:jmpl foo + oo2: + +`fjXX' + This family includes + fjne fjeq fjge fjlt fjgt fjle fjf + fjt fjgl fjgle fjnge fjngl fjngle fjngt + fjnle fjnlt fjoge fjogl fjogt fjole fjolt + fjor fjseq fjsf fjsne fjst fjueq fjuge + fjugt fjule fjult fjun + + For branch targets that are not PC relative, `as' emits + fbNX oof + jmp foo + oof: + when it encounters `fjXX foo'. + diff --git a/gas/doc/as.info-4 b/gas/doc/as.info-4 new file mode 100644 index 0000000..4571cf8 --- /dev/null +++ b/gas/doc/as.info-4 @@ -0,0 +1,874 @@ +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: M68K-Chars, Prev: M68K-Branch, Up: M68K-opcodes + +Special Characters +.................. + + The immediate character is `#' for Sun compatibility. The +line-comment character is `|'. If a `#' appears at the beginning of a +line, it is treated as a comment unless it looks like `# line file', in +which case it is treated normally. + + +File: as.info, Node: Sparc-Dependent, Next: Z8000-Dependent, Prev: M68K-Dependent, Up: Machine Dependencies + +SPARC Dependent Features +======================== + +* Menu: + +* Sparc-Opts:: Options +* Sparc-Float:: Floating Point +* Sparc-Directives:: Sparc Machine Directives + + +File: as.info, Node: Sparc-Opts, Next: Sparc-Float, Up: Sparc-Dependent + +Options +------- + + The SPARC chip family includes several successive levels (or other +variants) of chip, using the same core instruction set, but including a +few additional instructions at each level. + + By default, `as' assumes the core instruction set (SPARC v6), but +"bumps" the architecture level as needed: it switches to successively +higher architectures as it encounters instructions that only exist in +the higher levels. + +`-Av6 | -Av7 | -Av8 | -Asparclite' + Use one of the `-A' options to select one of the SPARC + architectures explicitly. If you select an architecture + explicitly, `as' reports a fatal error if it encounters an + instruction or feature requiring a higher level. + +`-bump' + Permit the assembler to "bump" the architecture level as required, + but warn whenever it is necessary to switch to another level. + + +File: as.info, Node: Sparc-Float, Next: Sparc-Directives, Prev: Sparc-Opts, Up: Sparc-Dependent + +Floating Point +-------------- + + The Sparc uses IEEE floating-point numbers. + + +File: as.info, Node: Sparc-Directives, Prev: Sparc-Float, Up: Sparc-Dependent + +Sparc Machine Directives +------------------------ + + The Sparc version of `as' supports the following additional machine +directives: + +`.common' + This must be followed by a symbol name, a positive number, and + `"bss"'. This behaves somewhat like `.comm', but the syntax is + different. + +`.half' + This is functionally identical to `.short'. + +`.proc' + This directive is ignored. Any text following it on the same line + is also ignored. + +`.reserve' + This must be followed by a symbol name, a positive number, and + `"bss"'. This behaves somewhat like `.lcomm', but the syntax is + different. + +`.seg' + This must be followed by `"text"', `"data"', or `"data1"'. It + behaves like `.text', `.data', or `.data 1'. + +`.skip' + This is functionally identical to the `.space' directive. + +`.word' + On the Sparc, the .word directive produces 32 bit values, instead + of the 16 bit values it produces on many other machines. + + +File: as.info, Node: i386-Dependent, Prev: Z8000-Dependent, Up: Machine Dependencies + +80386 Dependent Features +======================== + +* Menu: + +* i386-Options:: Options +* i386-Syntax:: AT&T Syntax versus Intel Syntax +* i386-Opcodes:: Opcode Naming +* i386-Regs:: Register Naming +* i386-prefixes:: Opcode Prefixes +* i386-Memory:: Memory References +* i386-jumps:: Handling of Jump Instructions +* i386-Float:: Floating Point +* i386-Notes:: Notes + + +File: as.info, Node: i386-Options, Next: i386-Syntax, Up: i386-Dependent + +Options +------- + + The 80386 has no machine dependent options. + + +File: as.info, Node: i386-Syntax, Next: i386-Opcodes, Prev: i386-Options, Up: i386-Dependent + +AT&T Syntax versus Intel Syntax +------------------------------- + + In order to maintain compatibility with the output of `gcc', `as' +supports AT&T System V/386 assembler syntax. This is quite different +from Intel syntax. We mention these differences because almost all +80386 documents used only Intel syntax. Notable differences between +the two syntaxes are: + + * AT&T immediate operands are preceded by `$'; Intel immediate + operands are undelimited (Intel `push 4' is AT&T `pushl $4'). + AT&T register operands are preceded by `%'; Intel register operands + are undelimited. AT&T absolute (as opposed to PC relative) + jump/call operands are prefixed by `*'; they are undelimited in + Intel syntax. + + * AT&T and Intel syntax use the opposite order for source and + destination operands. Intel `add eax, 4' is `addl $4, %eax'. The + `source, dest' convention is maintained for compatibility with + previous Unix assemblers. + + * In AT&T syntax the size of memory operands is determined from the + last character of the opcode name. Opcode suffixes of `b', `w', + and `l' specify byte (8-bit), word (16-bit), and long (32-bit) + memory references. Intel syntax accomplishes this by prefixes + memory operands (*not* the opcodes themselves) with `byte ptr', + `word ptr', and `dword ptr'. Thus, Intel `mov al, byte ptr FOO' + is `movb FOO, %al' in AT&T syntax. + + * Immediate form long jumps and calls are `lcall/ljmp $SECTION, + $OFFSET' in AT&T syntax; the Intel syntax is `call/jmp far + SECTION:OFFSET'. Also, the far return instruction is `lret + $STACK-ADJUST' in AT&T syntax; Intel syntax is `ret far + STACK-ADJUST'. + + * The AT&T assembler does not provide support for multiple section + programs. Unix style systems expect all programs to be single + sections. + + +File: as.info, Node: i386-Opcodes, Next: i386-Regs, Prev: i386-Syntax, Up: i386-Dependent + +Opcode Naming +------------- + + Opcode names are suffixed with one character modifiers which specify +the size of operands. The letters `b', `w', and `l' specify byte, +word, and long operands. If no suffix is specified by an instruction +and it contains no memory operands then `as' tries to fill in the +missing suffix based on the destination register operand (the last one +by convention). Thus, `mov %ax, %bx' is equivalent to `movw %ax, %bx'; +also, `mov $1, %bx' is equivalent to `movw $1, %bx'. Note that this is +incompatible with the AT&T Unix assembler which assumes that a missing +opcode suffix implies long operand size. (This incompatibility does +not affect compiler output since compilers always explicitly specify +the opcode suffix.) + + Almost all opcodes have the same names in AT&T and Intel format. +There are a few exceptions. The sign extend and zero extend +instructions need two sizes to specify them. They need a size to +sign/zero extend *from* and a size to zero extend *to*. This is +accomplished by using two opcode suffixes in AT&T syntax. Base names +for sign extend and zero extend are `movs...' and `movz...' in AT&T +syntax (`movsx' and `movzx' in Intel syntax). The opcode suffixes are +tacked on to this base name, the *from* suffix before the *to* suffix. +Thus, `movsbl %al, %edx' is AT&T syntax for "move sign extend *from* +%al *to* %edx." Possible suffixes, thus, are `bl' (from byte to long), +`bw' (from byte to word), and `wl' (from word to long). + + The Intel-syntax conversion instructions + + * `cbw' -- sign-extend byte in `%al' to word in `%ax', + + * `cwde' -- sign-extend word in `%ax' to long in `%eax', + + * `cwd' -- sign-extend word in `%ax' to long in `%dx:%ax', + + * `cdq' -- sign-extend dword in `%eax' to quad in `%edx:%eax', + +are called `cbtw', `cwtl', `cwtd', and `cltd' in AT&T naming. `as' +accepts either naming for these instructions. + + Far call/jump instructions are `lcall' and `ljmp' in AT&T syntax, +but are `call far' and `jump far' in Intel convention. + + +File: as.info, Node: i386-Regs, Next: i386-prefixes, Prev: i386-Opcodes, Up: i386-Dependent + +Register Naming +--------------- + + Register operands are always prefixes with `%'. The 80386 registers +consist of + + * the 8 32-bit registers `%eax' (the accumulator), `%ebx', `%ecx', + `%edx', `%edi', `%esi', `%ebp' (the frame pointer), and `%esp' + (the stack pointer). + + * the 8 16-bit low-ends of these: `%ax', `%bx', `%cx', `%dx', `%di', + `%si', `%bp', and `%sp'. + + * the 8 8-bit registers: `%ah', `%al', `%bh', `%bl', `%ch', `%cl', + `%dh', and `%dl' (These are the high-bytes and low-bytes of `%ax', + `%bx', `%cx', and `%dx') + + * the 6 section registers `%cs' (code section), `%ds' (data + section), `%ss' (stack section), `%es', `%fs', and `%gs'. + + * the 3 processor control registers `%cr0', `%cr2', and `%cr3'. + + * the 6 debug registers `%db0', `%db1', `%db2', `%db3', `%db6', and + `%db7'. + + * the 2 test registers `%tr6' and `%tr7'. + + * the 8 floating point register stack `%st' or equivalently + `%st(0)', `%st(1)', `%st(2)', `%st(3)', `%st(4)', `%st(5)', + `%st(6)', and `%st(7)'. + + +File: as.info, Node: i386-prefixes, Next: i386-Memory, Prev: i386-Regs, Up: i386-Dependent + +Opcode Prefixes +--------------- + + Opcode prefixes are used to modify the following opcode. They are +used to repeat string instructions, to provide section overrides, to +perform bus lock operations, and to give operand and address size +(16-bit operands are specified in an instruction by prefixing what would +normally be 32-bit operands with a "operand size" opcode prefix). +Opcode prefixes are usually given as single-line instructions with no +operands, and must directly precede the instruction they act upon. For +example, the `scas' (scan string) instruction is repeated with: + repne + scas + + Here is a list of opcode prefixes: + + * Section override prefixes `cs', `ds', `ss', `es', `fs', `gs'. + These are automatically added by specifying using the + SECTION:MEMORY-OPERAND form for memory references. + + * Operand/Address size prefixes `data16' and `addr16' change 32-bit + operands/addresses into 16-bit operands/addresses. Note that + 16-bit addressing modes (i.e. 8086 and 80286 addressing modes) are + not supported (yet). + + * The bus lock prefix `lock' inhibits interrupts during execution of + the instruction it precedes. (This is only valid with certain + instructions; see a 80386 manual for details). + + * The wait for coprocessor prefix `wait' waits for the coprocessor + to complete the current instruction. This should never be needed + for the 80386/80387 combination. + + * The `rep', `repe', and `repne' prefixes are added to string + instructions to make them repeat `%ecx' times. + + +File: as.info, Node: i386-Memory, Next: i386-jumps, Prev: i386-prefixes, Up: i386-Dependent + +Memory References +----------------- + + An Intel syntax indirect memory reference of the form + + SECTION:[BASE + INDEX*SCALE + DISP] + +is translated into the AT&T syntax + + SECTION:DISP(BASE, INDEX, SCALE) + +where BASE and INDEX are the optional 32-bit base and index registers, +DISP is the optional displacement, and SCALE, taking the values 1, 2, +4, and 8, multiplies INDEX to calculate the address of the operand. If +no SCALE is specified, SCALE is taken to be 1. SECTION specifies the +optional section register for the memory operand, and may override the +default section register (see a 80386 manual for section register +defaults). Note that section overrides in AT&T syntax *must* have be +preceded by a `%'. If you specify a section override which coincides +with the default section register, `as' will *not* output any section +register override prefixes to assemble the given instruction. Thus, +section overrides can be specified to emphasize which section register +is used for a given memory operand. + + Here are some examples of Intel and AT&T style memory references: + +AT&T: `-4(%ebp)', Intel: `[ebp - 4]' + BASE is `%ebp'; DISP is `-4'. SECTION is missing, and the default + section is used (`%ss' for addressing with `%ebp' as the base + register). INDEX, SCALE are both missing. + +AT&T: `foo(,%eax,4)', Intel: `[foo + eax*4]' + INDEX is `%eax' (scaled by a SCALE 4); DISP is `foo'. All other + fields are missing. The section register here defaults to `%ds'. + +AT&T: `foo(,1)'; Intel `[foo]' + This uses the value pointed to by `foo' as a memory operand. Note + that BASE and INDEX are both missing, but there is only *one* `,'. + This is a syntactic exception. + +AT&T: `%gs:foo'; Intel `gs:foo' + This selects the contents of the variable `foo' with section + register SECTION being `%gs'. + + Absolute (as opposed to PC relative) call and jump operands must be +prefixed with `*'. If no `*' is specified, `as' will always choose PC +relative addressing for jump/call labels. + + Any instruction that has a memory operand *must* specify its size +(byte, word, or long) with an opcode suffix (`b', `w', or `l', +respectively). + + +File: as.info, Node: i386-jumps, Next: i386-Float, Prev: i386-Memory, Up: i386-Dependent + +Handling of Jump Instructions +----------------------------- + + Jump instructions are always optimized to use the smallest possible +displacements. This is accomplished by using byte (8-bit) displacement +jumps whenever the target is sufficiently close. If a byte displacement +is insufficient a long (32-bit) displacement is used. We do not support +word (16-bit) displacement jumps (i.e. prefixing the jump instruction +with the `addr16' opcode prefix), since the 80386 insists upon masking +`%eip' to 16 bits after the word displacement is added. + + Note that the `jcxz', `jecxz', `loop', `loopz', `loope', `loopnz' +and `loopne' instructions only come in byte displacements, so that it +is possible that use of these instructions (`gcc' does not use them) +will cause the assembler to print an error message (and generate +incorrect code). The AT&T 80386 assembler tries to get around this +problem by expanding `jcxz foo' to + jcxz cx_zero + jmp cx_nonzero + cx_zero: jmp foo + cx_nonzero: + + +File: as.info, Node: i386-Float, Next: i386-Notes, Prev: i386-jumps, Up: i386-Dependent + +Floating Point +-------------- + + All 80387 floating point types except packed BCD are supported. +(BCD support may be added without much difficulty). These data types +are 16-, 32-, and 64- bit integers, and single (32-bit), double +(64-bit), and extended (80-bit) precision floating point. Each +supported type has an opcode suffix and a constructor associated with +it. Opcode suffixes specify operand's data types. Constructors build +these data types into memory. + + * Floating point constructors are `.float' or `.single', `.double', + and `.tfloat' for 32-, 64-, and 80-bit formats. These correspond + to opcode suffixes `s', `l', and `t'. `t' stands for temporary + real, and that the 80387 only supports this format via the `fldt' + (load temporary real to stack top) and `fstpt' (store temporary + real and pop stack) instructions. + + * Integer constructors are `.word', `.long' or `.int', and `.quad' + for the 16-, 32-, and 64-bit integer formats. The corresponding + opcode suffixes are `s' (single), `l' (long), and `q' (quad). As + with the temporary real format the 64-bit `q' format is only + present in the `fildq' (load quad integer to stack top) and + `fistpq' (store quad integer and pop stack) instructions. + + Register to register operations do not require opcode suffixes, so +that `fst %st, %st(1)' is equivalent to `fstl %st, %st(1)'. + + Since the 80387 automatically synchronizes with the 80386 `fwait' +instructions are almost never needed (this is not the case for the +80286/80287 and 8086/8087 combinations). Therefore, `as' suppresses +the `fwait' instruction whenever it is implicitly selected by one of +the `fn...' instructions. For example, `fsave' and `fnsave' are +treated identically. In general, all the `fn...' instructions are made +equivalent to `f...' instructions. If `fwait' is desired it must be +explicitly coded. + + +File: as.info, Node: i386-Notes, Prev: i386-Float, Up: i386-Dependent + +Notes +----- + + There is some trickery concerning the `mul' and `imul' instructions +that deserves mention. The 16-, 32-, and 64-bit expanding multiplies +(base opcode `0xf6'; extension 4 for `mul' and 5 for `imul') can be +output only in the one operand form. Thus, `imul %ebx, %eax' does +*not* select the expanding multiply; the expanding multiply would +clobber the `%edx' register, and this would confuse `gcc' output. Use +`imul %ebx' to get the 64-bit product in `%edx:%eax'. + + We have added a two operand form of `imul' when the first operand is +an immediate mode expression and the second operand is a register. +This is just a shorthand, so that, multiplying `%eax' by 69, for +example, can be done with `imul $69, %eax' rather than `imul $69, %eax, +%eax'. + + +File: as.info, Node: Z8000-Dependent, Next: i386-Dependent, Prev: Sparc-Dependent, Up: Machine Dependencies + +Z8000 Dependent Features +======================== + + The Z8000 as supports both members of the Z8000 family: the +unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with +24 bit addresses. + + When the assembler is in unsegmented mode (specified with the +`unsegm' directive), an address will take up one word (16 bit) sized +register. When the assembler is in segmented mode (specified with the +`segm' directive), a 24-bit address takes up a long (32 bit) register. +*Note Assembler Directives for the Z8000: Z8000 Directives, for a list +of other Z8000 specific assembler directives. + +* Menu: + +* Z8000 Options:: No special command-line options for Z8000 +* Z8000 Syntax:: Assembler syntax for the Z8000 +* Z8000 Directives:: Special directives for the Z8000 +* Z8000 Opcodes:: Opcodes + + +File: as.info, Node: Z8000 Options, Next: Z8000 Syntax, Up: Z8000-Dependent + +Options +------- + + `as' has no additional command-line options for the Zilog Z8000 +family. + + +File: as.info, Node: Z8000 Syntax, Next: Z8000 Directives, Prev: Z8000 Options, Up: Z8000-Dependent + +Syntax +------ + +* Menu: + +* Z8000-Chars:: Special Characters +* Z8000-Regs:: Register Names +* Z8000-Addressing:: Addressing Modes + + +File: as.info, Node: Z8000-Chars, Next: Z8000-Regs, Up: Z8000 Syntax + +Special Characters +.................. + + `!' is the line comment character. + + You can use `;' instead of a newline to separate statements. + + +File: as.info, Node: Z8000-Regs, Next: Z8000-Addressing, Prev: Z8000-Chars, Up: Z8000 Syntax + +Register Names +.............. + + The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can +refer to different sized groups of registers by register number, with +the prefix `r' for 16 bit registers, `rr' for 32 bit registers and `rq' +for 64 bit registers. You can also refer to the contents of the first +eight (of the sixteen 16 bit registers) by bytes. They are named `rNh' +and `rNl'. + +*byte registers* + r0l r0h r1h r1l r2h r2l r3h r3l + r4h r4l r5h r5l r6h r6l r7h r7l +*word registers* + r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15 +*long word registers* + rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14 +*quad word registers* + rq0 rq4 rq8 rq12 + + +File: as.info, Node: Z8000-Addressing, Prev: Z8000-Regs, Up: Z8000 Syntax + +Addressing Modes +................ + + as understands the following addressing modes for the Z8000: + +`rN' + Register direct + +`@rN' + Indirect register + +`ADDR' + Direct: the 16 bit or 24 bit address (depending on whether the + assembler is in segmented or unsegmented mode) of the operand is + in the instruction. + +`address(rN)' + Indexed: the 16 or 24 bit address is added to the 16 bit register + to produce the final address in memory of the operand. + +`rN(#IMM)' + Base Address: the 16 or 24 bit register is added to the 16 bit sign + extended immediate displacement to produce the final address in + memory of the operand. + +`rN(rM)' + Base Index: the 16 or 24 bit register rN is added to the sign + extended 16 bit index register rM to produce the final address in + memory of the operand. + +`#XX' + Immediate data XX. + + +File: as.info, Node: Z8000 Directives, Next: Z8000 Opcodes, Prev: Z8000 Syntax, Up: Z8000-Dependent + +Assembler Directives for the Z8000 +---------------------------------- + + The Z8000 port of as includes these additional assembler directives, +for compatibility with other Z8000 assemblers. As shown, these do not +begin with `.' (unlike the ordinary as directives). + +`segm' + Generates code for the segmented Z8001. + +`unsegm' + Generates code for the unsegmented Z8002. + +`name' + Synonym for `.file' + +`global' + Synonum for `.global' + +`wval' + Synonym for `.word' + +`lval' + Synonym for `.long' + +`bval' + Synonym for `.byte' + +`sval' + Assemble a string. `sval' expects one string literal, delimited by + single quotes. It assembles each byte of the string into + consecutive addresses. You can use the escape sequence `%XX' + (where XX represents a two-digit hexadecimal number) to represent + the character whose ASCII value is XX. Use this feature to + describe single quote and other characters that may not appear in + string literals as themselves. For example, the C statement + `char *a = "he said \"it's 50% off\"";' is represented in Z8000 + assembly language (shown with the assembler output in hex at the + left) as + + 68652073 sval 'he said %22it%27s 50%25 off%22%00' + 61696420 + 22697427 + 73203530 + 25206F66 + 662200 + +`rsect' + synonym for `.section' + +`block' + synonym for `.space' + +`even' + synonym for `.align 1' + + +File: as.info, Node: Z8000 Opcodes, Prev: Z8000 Directives, Up: Z8000-Dependent + +Opcodes +------- + + For detailed information on the Z8000 machine instruction set, see +`Z8000 Technical Manual'. + + The following table summarizes the opcodes and their arguments: + + rs 16 bit source register + rd 16 bit destination register + rbs 8 bit source register + rbd 8 bit destination register + rrs 32 bit source register + rrd 32 bit destination register + rqs 64 bit source register + rqd 64 bit destination register + addr 16/24 bit address + imm immediate data + + adc rd,rs clrb addr cpsir @rd,@rs,rr,cc + adcb rbd,rbs clrb addr(rd) cpsirb @rd,@rs,rr,cc + add rd,@rs clrb rbd dab rbd + add rd,addr com @rd dbjnz rbd,disp7 + add rd,addr(rs) com addr dec @rd,imm4m1 + add rd,imm16 com addr(rd) dec addr(rd),imm4m1 + add rd,rs com rd dec addr,imm4m1 + addb rbd,@rs comb @rd dec rd,imm4m1 + addb rbd,addr comb addr decb @rd,imm4m1 + addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1 + addb rbd,imm8 comb rbd decb addr,imm4m1 + addb rbd,rbs comflg flags decb rbd,imm4m1 + addl rrd,@rs cp @rd,imm16 di i2 + addl rrd,addr cp addr(rd),imm16 div rrd,@rs + addl rrd,addr(rs) cp addr,imm16 div rrd,addr + addl rrd,imm32 cp rd,@rs div rrd,addr(rs) + addl rrd,rrs cp rd,addr div rrd,imm16 + and rd,@rs cp rd,addr(rs) div rrd,rs + and rd,addr cp rd,imm16 divl rqd,@rs + and rd,addr(rs) cp rd,rs divl rqd,addr + and rd,imm16 cpb @rd,imm8 divl rqd,addr(rs) + and rd,rs cpb addr(rd),imm8 divl rqd,imm32 + andb rbd,@rs cpb addr,imm8 divl rqd,rrs + andb rbd,addr cpb rbd,@rs djnz rd,disp7 + andb rbd,addr(rs) cpb rbd,addr ei i2 + andb rbd,imm8 cpb rbd,addr(rs) ex rd,@rs + andb rbd,rbs cpb rbd,imm8 ex rd,addr + bit @rd,imm4 cpb rbd,rbs ex rd,addr(rs) + bit addr(rd),imm4 cpd rd,@rs,rr,cc ex rd,rs + bit addr,imm4 cpdb rbd,@rs,rr,cc exb rbd,@rs + bit rd,imm4 cpdr rd,@rs,rr,cc exb rbd,addr + bit rd,rs cpdrb rbd,@rs,rr,cc exb rbd,addr(rs) + bitb @rd,imm4 cpi rd,@rs,rr,cc exb rbd,rbs + bitb addr(rd),imm4 cpib rbd,@rs,rr,cc ext0e imm8 + bitb addr,imm4 cpir rd,@rs,rr,cc ext0f imm8 + bitb rbd,imm4 cpirb rbd,@rs,rr,cc ext8e imm8 + bitb rbd,rs cpl rrd,@rs ext8f imm8 + bpt cpl rrd,addr exts rrd + call @rd cpl rrd,addr(rs) extsb rd + call addr cpl rrd,imm32 extsl rqd + call addr(rd) cpl rrd,rrs halt + calr disp12 cpsd @rd,@rs,rr,cc in rd,@rs + clr @rd cpsdb @rd,@rs,rr,cc in rd,imm16 + clr addr cpsdr @rd,@rs,rr,cc inb rbd,@rs + clr addr(rd) cpsdrb @rd,@rs,rr,cc inb rbd,imm16 + clr rd cpsi @rd,@rs,rr,cc inc @rd,imm4m1 + clrb @rd cpsib @rd,@rs,rr,cc inc addr(rd),imm4m1 + inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs) + inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16 + incb @rd,imm4m1 ldb rd(rx),rbs mult rrd,rs + incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@rs + incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr + incb rbd,imm4m1 ldd @rs,@rd,rr multl rqd,addr(rs) + ind @rd,@rs,ra lddb @rs,@rd,rr multl rqd,imm32 + indb @rd,@rs,rba lddr @rs,@rd,rr multl rqd,rrs + inib @rd,@rs,ra lddrb @rs,@rd,rr neg @rd + inibr @rd,@rs,ra ldi @rd,@rs,rr neg addr + iret ldib @rd,@rs,rr neg addr(rd) + jp cc,@rd ldir @rd,@rs,rr neg rd + jp cc,addr ldirb @rd,@rs,rr negb @rd + jp cc,addr(rd) ldk rd,imm4 negb addr + jr cc,disp8 ldl @rd,rrs negb addr(rd) + ld @rd,imm16 ldl addr(rd),rrs negb rbd + ld @rd,rs ldl addr,rrs nop + ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@rs + ld addr(rd),rs ldl rd(rx),rrs or rd,addr + ld addr,imm16 ldl rrd,@rs or rd,addr(rs) + ld addr,rs ldl rrd,addr or rd,imm16 + ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs + ld rd(rx),rs ldl rrd,imm32 orb rbd,@rs + ld rd,@rs ldl rrd,rrs orb rbd,addr + ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs) + ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8 + ld rd,imm16 ldm @rd,rs,n orb rbd,rbs + ld rd,rs ldm addr(rd),rs,n out @rd,rs + ld rd,rs(imm16) ldm addr,rs,n out imm16,rs + ld rd,rs(rx) ldm rd,@rs,n outb @rd,rbs + lda rd,addr ldm rd,addr(rs),n outb imm16,rbs + lda rd,addr(rs) ldm rd,addr,n outd @rd,@rs,ra + lda rd,rs(imm16) ldps @rs outdb @rd,@rs,rba + lda rd,rs(rx) ldps addr outib @rd,@rs,ra + ldar rd,disp16 ldps addr(rs) outibr @rd,@rs,ra + ldb @rd,imm8 ldr disp16,rs pop @rd,@rs + ldb @rd,rbs ldr rd,disp16 pop addr(rd),@rs + ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@rs + ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@rs + ldb addr,imm8 ldrl disp16,rrs popl @rd,@rs + ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@rs + ldb rbd,@rs mbit popl addr,@rs + ldb rbd,addr mreq rd popl rrd,@rs + ldb rbd,addr(rs) mres push @rd,@rs + ldb rbd,imm8 mset push @rd,addr + ldb rbd,rbs mult rrd,@rs push @rd,addr(rs) + ldb rbd,rs(imm16) mult rrd,addr push @rd,imm16 + push @rd,rs set addr,imm4 subl rrd,imm32 + pushl @rd,@rs set rd,imm4 subl rrd,rrs + pushl @rd,addr set rd,rs tcc cc,rd + pushl @rd,addr(rs) setb @rd,imm4 tccb cc,rbd + pushl @rd,rrs setb addr(rd),imm4 test @rd + res @rd,imm4 setb addr,imm4 test addr + res addr(rd),imm4 setb rbd,imm4 test addr(rd) + res addr,imm4 setb rbd,rs test rd + res rd,imm4 setflg imm4 testb @rd + res rd,rs sinb rbd,imm16 testb addr + resb @rd,imm4 sinb rd,imm16 testb addr(rd) + resb addr(rd),imm4 sind @rd,@rs,ra testb rbd + resb addr,imm4 sindb @rd,@rs,rba testl @rd + resb rbd,imm4 sinib @rd,@rs,ra testl addr + resb rbd,rs sinibr @rd,@rs,ra testl addr(rd) + resflg imm4 sla rd,imm8 testl rrd + ret cc slab rbd,imm8 trdb @rd,@rs,rba + rl rd,imm1or2 slal rrd,imm8 trdrb @rd,@rs,rba + rlb rbd,imm1or2 sll rd,imm8 trib @rd,@rs,rbr + rlc rd,imm1or2 sllb rbd,imm8 trirb @rd,@rs,rbr + rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @ra,@rb,rbr + rldb rbb,rba sout imm16,rs trtib @ra,@rb,rr + rr rd,imm1or2 soutb imm16,rbs trtirb @ra,@rb,rbr + rrb rbd,imm1or2 soutd @rd,@rs,ra trtrb @ra,@rb,rbr + rrc rd,imm1or2 soutdb @rd,@rs,rba tset @rd + rrcb rbd,imm1or2 soutib @rd,@rs,ra tset addr + rrdb rbb,rba soutibr @rd,@rs,ra tset addr(rd) + rsvd36 sra rd,imm8 tset rd + rsvd38 srab rbd,imm8 tsetb @rd + rsvd78 sral rrd,imm8 tsetb addr + rsvd7e srl rd,imm8 tsetb addr(rd) + rsvd9d srlb rbd,imm8 tsetb rbd + rsvd9f srll rrd,imm8 xor rd,@rs + rsvdb9 sub rd,@rs xor rd,addr + rsvdbf sub rd,addr xor rd,addr(rs) + sbc rd,rs sub rd,addr(rs) xor rd,imm16 + sbcb rbd,rbs sub rd,imm16 xor rd,rs + sc imm8 sub rd,rs xorb rbd,@rs + sda rd,rs subb rbd,@rs xorb rbd,addr + sdab rbd,rs subb rbd,addr xorb rbd,addr(rs) + sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8 + sdl rd,rs subb rbd,imm8 xorb rbd,rbs + sdlb rbd,rs subb rbd,rbs xorb rbd,rbs + sdll rrd,rs subl rrd,@rs + set @rd,imm4 subl rrd,addr + set addr(rd),imm4 subl rrd,addr(rs) + + +File: as.info, Node: Acknowledgements, Next: Index, Prev: Copying, Up: Top + +Acknowledgements +**************** + + If you've contributed to `as' and your name isn't listed here, it is +not meant as a slight. We just don't know about it. Send mail to the +maintainer, and we'll correct the situation. Currently (June 1993), the +maintainer is Ken Raeburn (email address `raeburn@cygnus.com'). + + Dean Elsner wrote the original GNU assembler for the VAX.(1) + + Jay Fenlason maintained GAS for a while, adding support for +gdb-specific debug information and the 68k series machines, most of the +preprocessing pass, and extensive changes in messages.c, input-file.c, +write.c. + + K. Richard Pixley maintained GAS for a while, adding various +enhancements and many bug fixes, including merging support for several +processors, breaking GAS up to handle multiple object file format +backends (including heavy rewrite, testing, an integration of the coff +and b.out backends), adding configuration including heavy testing and +verification of cross assemblers and file splits and renaming, +converted GAS to strictly ansi C including full prototypes, added +support for m680[34]0 & cpu32, considerable work on i960 including a +COFF port (including considerable amounts of reverse engineering), a +SPARC opcode file rewrite, DECstation, rs6000, and hp300hpux host +ports, updated "know" assertions and made them work, much other +reorganization, cleanup, and lint. + + Ken Raeburn wrote the high-level BFD interface code to replace most +of the code in format-specific I/O modules. + + The original VMS support was contributed by David L. Kashtan. Eric +Youngdale has done much work with it since. + + The Intel 80386 machine description was written by Eliot Dresselhaus. + + Minh Tran-Le at IntelliCorp contributed some AIX 386 support. + + The Motorola 88k machine description was contributed by Devon Bowen +of Buffalo University and Torbjorn Granlund of the Swedish Institute of +Computer Science. + + Keith Knowles at the Open Software Foundation wrote the original +MIPS back end (tc-mips.c, tc-mips.h), and contributed Rose format +support (which hasn't been merged in yet). Ralph Campbell worked with +the MIPS code to support a.out format. + + Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors +(tc-z8k, tc-h8300, tc-h8500), and IEEE 695 object file format +(obj-ieee), was written by Steve Chamberlain of Cygnus Support. Steve +also modified the COFF back end to use BFD for some low-level +operations, for use with the H8/300 and AMD 29k targets. + + John Gilmore built the AMD 29000 support, added .include support, and +simplified the configuration of which versions accept which pseudo-ops. +He updated the 68k machine description so that Motorola's opcodes +always produced fixed-size instructions (e.g. jsr), while synthetic +instructions remained shrinkable (jbsr). John fixed many bugs, +including true tested cross-compilation support, and one bug in +relaxation that took a week and required the apocryphal one-bit fix. + + Ian Lance Taylor of Cygnus Support merged the Motorola and MIT +syntaxes for the 68k, completed support for some COFF targets (68k, +i386 SVR3, and SCO Unix), and made a few other minor patches. + + Steve Chamberlain made `as' able to generate listings. + + Support for the HP9000/300 was contributed by Hewlett-Packard. + + Support for ELF format files has been worked on by Mark Eichin of +Cygnus Support (original, incomplete implementation for SPARC), Pete +Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), +Michael Meissner of the Open Software Foundation (i386 mainly), and Ken +Raeburn of Cygnus Support (sparc, and some initial 64-bit support). + + Several engineers at Cygnus Support have also provided many small +bug fixes and configuration enhancements. + + Many others have contributed large or small bugfixes and +enhancements. If you've contributed significant work and are not +mentioned on this list, and want to be, let us know. Some of the +history has been lost; we aren't intentionally leaving anyone out. + + ---------- Footnotes ---------- + + (1) Any more details? + diff --git a/gas/doc/as.info-5 b/gas/doc/as.info-5 new file mode 100644 index 0000000..97bcad3 --- /dev/null +++ b/gas/doc/as.info-5 @@ -0,0 +1,394 @@ +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: Copying, Next: Acknowledgements, Prev: Machine Dependencies, Up: Top + + + +GNU GENERAL PUBLIC LICENSE +************************** + + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 + Mass Ave, Cambridge, MA 02139, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +Preamble +======== + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it in +new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, +and (2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 1. This License applies to any program or other work which contains a + notice placed by the copyright holder saying it may be distributed + under the terms of this General Public License. The "Program", + below, refers to any such program or work, and a "work based on + the Program" means either the Program or any derivative work under + copyright law: that is to say, a work containing the Program or a + portion of it, either verbatim or with modifications and/or + translated into another language. (Hereinafter, translation is + included without limitation in the term "modification".) Each + licensee is addressed as "you". + + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running the Program is not restricted, and the output from the + Program is covered only if its contents constitute a work based on + the Program (independent of having been made by running the + Program). Whether that is true depends on what the Program does. + + 2. You may copy and distribute verbatim copies of the Program's + source code as you receive it, in any medium, provided that you + conspicuously and appropriately publish on each copy an appropriate + copyright notice and disclaimer of warranty; keep intact all the + notices that refer to this License and to the absence of any + warranty; and give any other recipients of the Program a copy of + this License along with the Program. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange + for a fee. + + 3. You may modify your copy or copies of the Program or any portion + of it, thus forming a work based on the Program, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b. You must cause any work that you distribute or publish, that + in whole or in part contains or is derived from the Program + or any part thereof, to be licensed as a whole at no charge + to all third parties under the terms of this License. + + c. If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display + an announcement including an appropriate copyright notice and + a notice that there is no warranty (or else, saying that you + provide a warranty) and that users may redistribute the + program under these conditions, and telling the user how to + view a copy of this License. (Exception: if the Program + itself is interactive but does not normally print such an + announcement, your work based on the Program is not required + to print an announcement.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Program, and can be reasonably considered independent and separate + works in themselves, then this License, and its terms, do not + apply to those sections when you distribute them as separate + works. But when you distribute the same sections as part of a + whole which is a work based on the Program, the distribution of + the whole must be on the terms of this License, whose permissions + for other licensees extend to the entire whole, and thus to each + and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Program. + + In addition, mere aggregation of another work not based on the + Program with the Program (or with a work based on the Program) on + a volume of a storage or distribution medium does not bring the + other work under the scope of this License. + + 4. You may copy and distribute the Program (or a work based on it, + under Section 2) in object code or executable form under the terms + of Sections 1 and 2 above provided that you also do one of the + following: + + a. Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of + Sections 1 and 2 above on a medium customarily used for + software interchange; or, + + b. Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a + medium customarily used for software interchange; or, + + c. Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with + such an offer, in accord with Subsection b above.) + + The source code for a work means the preferred form of the work for + making modifications to it. For an executable work, complete + source code means all the source code for all modules it contains, + plus any associated interface definition files, plus the scripts + used to control compilation and installation of the executable. + However, as a special exception, the source code distributed need + not include anything that is normally distributed (in either + source or binary form) with the major components (compiler, + kernel, and so on) of the operating system on which the executable + runs, unless that component itself accompanies the executable. + + If distribution of executable or object code is made by offering + access to copy from a designated place, then offering equivalent + access to copy the source code from the same place counts as + distribution of the source code, even though third parties are not + compelled to copy the source along with the object code. + + 5. You may not copy, modify, sublicense, or distribute the Program + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense or distribute the Program is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 6. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify + or distribute the Program or its derivative works. These actions + are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Program (or any work + based on the Program), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Program or works based on it. + + 7. Each time you redistribute the Program (or any work based on the + Program), the recipient automatically receives a license from the + original licensor to copy, distribute or modify the Program + subject to these terms and conditions. You may not impose any + further restrictions on the recipients' exercise of the rights + granted herein. You are not responsible for enforcing compliance + by third parties to this License. + + 8. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent + issues), conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy simultaneously + your obligations under this License and any other pertinent + obligations, then as a consequence you may not distribute the + Program at all. For example, if a patent license would not permit + royalty-free redistribution of the Program by all those who + receive copies directly or indirectly through you, then the only + way you could satisfy both it and this License would be to refrain + entirely from distribution of the Program. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of + any such claims; this section has the sole purpose of protecting + the integrity of the free software distribution system, which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + + 9. If the distribution and/or use of the Program is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Program under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only + in or among countries not thus excluded. In such case, this + License incorporates the limitation as if written in the body of + this License. + + 10. The Free Software Foundation may publish revised and/or new + versions of the General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the Program + does not specify a version number of this License, you may choose + any version ever published by the Free Software Foundation. + + 11. If you wish to incorporate parts of the Program into other free + programs whose distribution conditions are different, write to the + author to ask for permission. For software which is copyrighted + by the Free Software Foundation, write to the Free Software + Foundation; we sometimes make exceptions for this. Our decision + will be guided by the two goals of preserving the free status of + all derivatives of our free software and of promoting the sharing + and reuse of software generally. + + NO WARRANTY + + 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT + NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE + PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + + 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU + OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY + OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + +How to Apply These Terms to Your New Programs +============================================= + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES. + Copyright (C) 19YY NAME OF AUTHOR + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + Also add information on how to contact you by electronic and paper +mail. + + If the program is interactive, make it output a short notice like +this when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details + type `show w'. This is free software, and you are welcome + to redistribute it under certain conditions; type `show c' + for details. + + The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, the +commands you use may be called something other than `show w' and `show +c'; they could even be mouse-clicks or menu items--whatever suits your +program. + + You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the program, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright + interest in the program `Gnomovision' + (which makes passes at compilers) written + by James Hacker. + + SIGNATURE OF TY COON, 1 April 1989 + Ty Coon, President of Vice + + This General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Library General Public License instead of this License. + diff --git a/ld/ld.info b/ld/ld.info new file mode 100644 index 0000000..91e4d7d --- /dev/null +++ b/ld/ld.info @@ -0,0 +1,65 @@ +This is Info file ld.info, produced by Makeinfo-1.55 from the input +file ./ld.texinfo. + +START-INFO-DIR-ENTRY +* Ld:: The GNU linker. +END-INFO-DIR-ENTRY + + This file documents the GNU linker LD. + + 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 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. + + +Indirect: +ld.info-1: 857 +ld.info-2: 49400 + +Tag Table: +(Indirect) +Node: Top857 +Node: Overview1330 +Node: Invocation2478 +Node: Options2886 +Node: Environment20209 +Node: Commands21154 +Node: Scripts22148 +Node: Expressions23246 +Node: Integers24173 +Node: Symbols25012 +Node: Location Counter25572 +Node: Operators26768 +Node: Evaluation27678 +Node: Assignment28373 +Node: Arithmetic Functions31454 +Node: MEMORY35234 +Node: SECTIONS37821 +Node: Section Definition39419 +Node: Section Placement40867 +Node: Section Data Expressions45560 +Node: Section Options49400 +Node: Entry Point51581 +Node: Option Commands53174 +Node: Machine Dependent56493 +Node: H8/30056913 +Node: i96057708 +Node: BFD58918 +Node: BFD outline62281 +Node: BFD information loss63566 +Node: Canonical format66074 +Node: MRI70420 +Node: Index74894 + +End Tag Table diff --git a/ld/ld.info-1 b/ld/ld.info-1 new file mode 100644 index 0000000..7613997 --- /dev/null +++ b/ld/ld.info-1 @@ -0,0 +1,1255 @@ +This is Info file ld.info, produced by Makeinfo-1.55 from the input +file ./ld.texinfo. + +START-INFO-DIR-ENTRY +* Ld:: The GNU linker. +END-INFO-DIR-ENTRY + + This file documents the GNU linker LD. + + 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 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. + + +File: ld.info, Node: Top, Next: Overview, Prev: (DIR), Up: (DIR) + +Using ld +******** + + This file documents the GNU linker ld. + +* Menu: + +* Overview:: Overview +* Invocation:: Invocation +* Commands:: Command Language + +* Machine Dependent:: Machine Dependent Features + +* BFD:: BFD + +* MRI:: MRI Compatible Script Files +* Index:: Index + + +File: ld.info, Node: Overview, Next: Invocation, Prev: Top, Up: Top + +Overview +******** + + `ld' combines a number of object and archive files, relocates their +data and ties up symbol references. Usually the last step in compiling +a program is to run `ld'. + + `ld' accepts Linker Command Language files written in a superset of +AT&T's Link Editor Command Language syntax, to provide explicit and +total control over the linking process. + + This version of `ld' uses the general purpose BFD libraries to +operate on object files. This allows `ld' to read, combine, and write +object files in many different formats--for example, COFF or `a.out'. +Different formats may be linked together to produce any available kind +of object file. *Note BFD:: for a list of formats supported on various +architectures. + + Aside from its flexibility, the GNU linker is more helpful than other +linkers in providing diagnostic information. Many linkers abandon +execution immediately upon encountering an error; whenever possible, +`ld' continues executing, allowing you to identify other errors (or, in +some cases, to get an output file in spite of the error). + + +File: ld.info, Node: Invocation, Next: Commands, Prev: Overview, Up: Top + +Invocation +********** + + The GNU linker `ld' is meant to cover a broad range of situations, +and to be as compatible as possible with other linkers. As a result, +you have many choices to control its behavior. + +* Menu: + +* Options:: Command Line Options +* Environment:: Environment Variables + + +File: ld.info, Node: Options, Next: Environment, Up: Invocation + +Command Line Options +==================== + + Here is a summary of the options you can use on the `ld' command +line: + + ld [ -o OUTPUT ] OBJFILE... + [ -AARCHITECTURE ] [ -b INPUT-FORMAT ] [ -Bstatic ] + [ -c MRI-COMMANDFILE ] [ -d | -dc | -dp ] + [ -defsym SYMBOL=EXPRESSION ] + [ -e ENTRY ] [ -F ] [ -F FORMAT ] + [ -format INPUT-FORMAT ] [ -g ] [ -G SIZE ] [ --help ] [ -i ] + [ -lARCHIVE ] [ -LSEARCHDIR ] [ -M ] [ -Map MAPFILE ] + [ -m EMULATION ] [ -N | -n ] [ -noinhibit-exec ] + [ -oformat OUTPUT-FORMAT ] [ -R FILENAME ] [ -relax ] + [ -r | -Ur ] [ -S ] [ -s ] [ -sort-common ] [ -T COMMANDFILE ] + [ -Ttext ORG ] [ -Tdata ORG ] + [ -Tbss ORG ] [ -t ] [ -u SYMBOL] [-V] [-v] [ --version ] + [ -warn-common ] [ -ySYMBOL ] [ -X ] [-x ] + + This plethora of command-line options may seem intimidating, but in +actual practice few of them are used in any particular context. For +instance, a frequent use of `ld' is to link standard Unix object files +on a standard, supported Unix system. On such a system, to link a file +`hello.o': + + ld -o OUTPUT /lib/crt0.o hello.o -lc + + This tells `ld' to produce a file called OUTPUT as the result of +linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a', +which will come from the standard search directories. (See the +discussion of the `-l' option below.) + + The command-line options to `ld' may be specified in any order, and +may be repeated at will. Repeating most options with a different +argument will either have no further effect, or override prior +occurrences (those further to the left on the command line) of that +option. + + The exceptions--which may meaningfully be used more than once--are +`-A', `-b' (or its synonym `-format'), `-defsym', `-L', `-l', `-R', and +`-u'. + + The list of object files to be linked together, shown as OBJFILE..., +may follow, precede, or be mixed in with command-line options, except +that an OBJFILE argument may not be placed between an option and its +argument. + + Usually the linker is invoked with at least one object file, but you +can specify other forms of binary input files using `-l', `-R', and the +script command language. If *no* binary input files at all are +specified, the linker does not produce any output, and issues the +message `No input files'. + + Option arguments must either follow the option letter without +intervening whitespace, or be given as separate arguments immediately +following the option that requires them. + +`-AARCHITECTURE' + In the current release of `ld', this option is useful only for the + Intel 960 family of architectures. In that `ld' configuration, the + ARCHITECTURE argument identifies the particular architecture in + the 960 family, enabling some safeguards and modifying the + archive-library search path. *Note `ld' and the Intel 960 family: + i960, for details. + + Future releases of `ld' may support similar functionality for + other architecture families. + +`-b INPUT-FORMAT' + Specify the binary format for input object files that follow this + option on the command line. You don't usually need to specify + this, as `ld' is configured to expect as a default input format + the most usual format on each machine. INPUT-FORMAT is a text + string, the name of a particular format supported by the BFD + libraries. (You can list the available binary formats with + `objdump -i'.) `-format INPUT-FORMAT' has the same effect, as does + the script command `TARGET'. *Note BFD::. + + You may want to use this option if you are linking files with an + unusual binary format. You can also use `-b' to switch formats + explicitly (when linking object files of different formats), by + including `-b INPUT-FORMAT' before each group of object files in a + particular format. + + The default format is taken from the environment variable + `GNUTARGET'. *Note Environment::. You can also define the input + format from a script, using the command `TARGET'; see *Note Option + Commands::. + +`-Bstatic' + Ignored. This option is accepted for command-line compatibility + with the SunOS linker. + +`-c MRI-COMMANDFILE' + For compatibility with linkers produced by MRI, `ld' accepts script + files written in an alternate, restricted command language, + described in *Note MRI Compatible Script Files: MRI. Introduce + MRI script files with the option `-c'; use the `-T' option to run + linker scripts written in the general-purpose `ld' scripting + language. If MRI-CMDFILE does not exist, `ld' looks for it in the + directories specified by any `-L' options. + +`-d' +`-dc' +`-dp' + These three options are equivalent; multiple forms are supported + for compatibility with other linkers. They assign space to common + symbols even if a relocatable output file is specified (with + `-r'). The script command `FORCE_COMMON_ALLOCATION' has the same + effect. *Note Option Commands::. + +`-defsym SYMBOL=EXPRESSION' + Create a global symbol in the output file, containing the absolute + address given by EXPRESSION. You may use this option as many + times as necessary to define multiple symbols in the command line. + A limited form of arithmetic is supported for the EXPRESSION in + this context: you may give a hexadecimal constant or the name of + an existing symbol, or use `+' and `-' to add or subtract + hexadecimal constants or symbols. If you need more elaborate + expressions, consider using the linker command language from a + script (*note Assignment: Symbol Definitions: Assignment.). + *Note:* there should be no white space between SYMBOL, the equals + sign ("="), and EXPRESSION. + +`-e ENTRY' + Use ENTRY as the explicit symbol for beginning execution of your + program, rather than the default entry point. *Note Entry Point::, + for a discussion of defaults and other ways of specifying the + entry point. + +`-F' +`-FFORMAT' + Ignored. Some older linkers used this option throughout a + compilation toolchain for specifying object-file format for both + input and output object files. The mechanisms `ld' uses for this + purpose (the `-b' or `-format' options for input files, `-oformat' + option or the `TARGET' command in linker scripts for output files, + the `GNUTARGET' environment variable) are more flexible, but `ld' + accepts the `-F' option for compatibility with scripts written to + call the old linker. + +`-format INPUT-FORMAT' + Synonym for `-b INPUT-FORMAT'. + +`-g' + Ignored. Provided for compatibility with other tools. + +`-GVALUE' +`-G VALUE' + Set the maximum size of objects to be optimized using the GP + register to SIZE under MIPS ECOFF. Ignored for other object file + formats. + +`--help' + Print a summary of the command-line options on the standard output + and exit. This option and `--version' begin with two dashes + instead of one for compatibility with other GNU programs. The + other options start with only one dash for compatibility with + other linkers. + +`-i' + Perform an incremental link (same as option `-r'). + +`-lAR' + Add archive file ARCHIVE to the list of files to link. This + option may be used any number of times. `ld' will search its + path-list for occurrences of `libAR.a' for every ARCHIVE specified. + +`-LSEARCHDIR' +`-L SEARCHDIR' + Add path SEARCHDIR to the list of paths that `ld' will search for + archive libraries and `ld' control scripts. You may use this + option any number of times. + + The default set of paths searched (without being specified with + `-L') depends on which emulation mode `ld' is using, and in some + cases also on how it was configured. *Note Environment::. + + The paths can also be specified in a link script with the + `SEARCH_DIR' command. + +`-M' + Print (to the standard output) a link map--diagnostic information + about where symbols are mapped by `ld', and information on global + common storage allocation. + +`-Map MAPFILE' + Print to the file MAPFILE a link map--diagnostic information about + where symbols are mapped by `ld', and information on global common + storage allocation. + +`-mEMULATION' +`-m EMULATION' + Emulate the EMULATION linker. You can list the available + emulations with the `-V' option. The default is the system for + which you configured `ld'. + +`-N' + Set the text and data sections to be readable and writable. Also, + do not page-align the data segment. If the output format supports + Unix style magic numbers, mark the output as `OMAGIC'. + +`-n' + Set the text segment to be read only, and mark the output as + `NMAGIC' if possible. + +`-noinhibit-exec' + Retain the executable output file whenever it is still usable. + Normally, the linker will not produce an output file if it + encounters errors during the link process; it exits without + writing an output file when it issues any error whatsoever. + +`-o OUTPUT' + Use OUTPUT as the name for the program produced by `ld'; if this + option is not specified, the name `a.out' is used by default. The + script command `OUTPUT' can also specify the output file name. + +`-oformat OUTPUT-FORMAT' + Specify the binary format for the output object file. You don't + usually need to specify this, as `ld' is configured to produce as + a default output format the most usual format on each machine. + oUTPUT-FORMAT is a text string, the name of a particular format + supported by the BFD libraries. (You can list the available binary + formats with `objdump -i'.) The script command `OUTPUT_FORMAT' + can also specify the output format, but this option overrides it. + *Note BFD::. + +`-R FILENAME' + Read symbol names and their addresses from FILENAME, but do not + relocate it or include it in the output. This allows your output + file to refer symbolically to absolute locations of memory defined + in other programs. + +`-relax' + An option with machine dependent effects. Currently this option + is only supported on the H8/300. *Note `ld' and the H8/300: + H8/300. + + On some platforms, use option performs global optimizations that + become possible when the linker resolves addressing in the + program, such as relaxing address modes and synthesizing new + instructions in the output object file. + + On platforms where this is not supported, `-relax' is accepted, but + ignored. + +`-r' + Generate relocatable output--i.e., generate an output file that + can in turn serve as input to `ld'. This is often called "partial + linking". As a side effect, in environments that support standard + Unix magic numbers, this option also sets the output file's magic + number to `OMAGIC'. If this option is not specified, an absolute + file is produced. When linking C++ programs, this option *will + not* resolve references to constructors; to do that, use `-Ur'. + + This option does the same thing as `-i'. + +`-S' + Omit debugger symbol information (but not all symbols) from the + output file. + +`-s' + Omit all symbol information from the output file. + +`-sort-common' + Normally, when `ld' places the global common symbols in the + appropriate output sections, it sorts them by size. First come + all the one byte symbols, then all the two bytes, then all the + four bytes, and then everything else. This is to prevent gaps + between symbols due to alignment constraints. This option + disables that sorting. + +`-Tbss ORG' +`-Tdata ORG' +`-Ttext ORG' + Use ORG as the starting address for--respectively--the `bss', + `data', or the `text' segment of the output file. ORG must be a + single hexadecimal integer; for compatibility with other linkers, + you may omit the leading `0x' usually associated with hexadecimal + values. + +`-T COMMANDFILE' +`-TCOMMANDFILE' + Read link commands from the file COMMANDFILE. These commands + completely override `ld''s default link format (rather than adding + to it); COMMANDFILE must specify everything necessary to describe + the target format. *Note Commands::. If COMMANDFILE does not + exist, `ld' looks for it in the directories specified by any + preceding `-L' options. Multiple `-T' options accumulate. + +`-t' + Print the names of the input files as `ld' processes them. + +`-u SYMBOL' + Force SYMBOL to be entered in the output file as an undefined + symbol. Doing this may, for example, trigger linking of + additional modules from standard libraries. `-u' may be repeated + with different option arguments to enter additional undefined + symbols. + +`-Ur' + For anything other than C++ programs, this option is equivalent to + `-r': it generates relocatable output--i.e., an output file that + can in turn serve as input to `ld'. When linking C++ programs, + `-Ur' *will* resolve references to constructors, unlike `-r'. It + does not work to use `-Ur' on files that were themselves linked + with `-Ur'; once the constructor table has been built, it can not + be added to. Use `-Ur' only for the last partial link, and `-r' + for the others. + +`-V' + Display the version number for `ld' and list the supported + emulations. Display which input files can and can not be opened. + +`-v' + Display the version number for `ld'. + +`--version' + Display the version number for `ld' and exit. + +`-warn-common' + Warn when a common symbol is combined with another common symbol + or with a symbol definition. Unix linkers allow this somewhat + sloppy practice, but linkers on some other operating systems do + not. This option allows you to find potential problems from + combining global symbols. Unfortunately, some C libraries use + this practice, so you may get some warnings about symbols in the + libraries as well as in your programs. + + There are three kinds of global symbols, illustrated here by C + examples: + + `int i = 1;' + A definition, which goes in the initialized data section of + the output file. + + `extern int i;' + An undefined reference, which does not allocate space. There + must be either a definition or a common symbol for the + variable somewhere. + + `int i;' + A common symbol. If there are only (one or more) common + symbols for a variable, it goes in the uninitialized data + area of the output file. The linker merges multiple common + symbols for the same variable into a single symbol. If they + are of different sizes, it picks the largest size. The + linker turns a common symbol into a declaration, if there is + a definition of the same variable. + + The `-warn-common' option can produce five kinds of warnings. Each + warning consists of a pair of lines: the first describes the + symbol just encountered, and the second describes the previous + symbol encountered with the same name. One or both of the two + symbols will be a common symbol. + + 1. Turning a common symbol into a reference, because there is + already a definition for the symbol. + FILE(SECTION): warning: common of `SYMBOL' + overridden by definition + FILE(SECTION): warning: defined here + + 2. Turning a common symbol into a reference, because a later + definition for the symbol is encountered. This is the same + as the previous case, except that the symbols are encountered + in a different order. + FILE(SECTION): warning: definition of `SYMBOL' + overriding common + FILE(SECTION): warning: common is here + + 3. Merging a common symbol with a previous same-sized common + symbol. + FILE(SECTION): warning: multiple common + of `SYMBOL' + FILE(SECTION): warning: previous common is here + + 4. Merging a common symbol with a previous larger common symbol. + FILE(SECTION): warning: common of `SYMBOL' + overridden by larger common + FILE(SECTION): warning: larger common is here + + 5. Merging a common symbol with a previous smaller common + symbol. This is the same as the previous case, except that + the symbols are encountered in a different order. + FILE(SECTION): warning: common of `SYMBOL' + overriding smaller common + FILE(SECTION): warning: smaller common is here + +`-X' + If `-s' or `-S' is also specified, delete only local symbols + beginning with `L'. + +`-x' + If `-s' or `-S' is also specified, delete all local symbols, not + just those beginning with `L'. + +`-ySYMBOL' + Print the name of each linked file in which SYMBOL appears. This + option may be given any number of times. On many systems it is + necessary to prepend an underscore. + + This option is useful when you have an undefined symbol in your + link but don't know where the reference is coming from. + + +File: ld.info, Node: Environment, Prev: Options, Up: Invocation + +Environment Variables +===================== + + You can change the behavior of `ld' with the environment variable +`GNUTARGET'. + + `GNUTARGET' determines the input-file object format if you don't use +`-b' (or its synonym `-format'). Its value should be one of the BFD +names for an input format (*note BFD::.). If there is no `GNUTARGET' +in the environment, `ld' uses the natural format of the target. If +`GNUTARGET' is set to `default' then BFD attempts to discover the input +format by examining binary input files; this method often succeeds, but +there are potential ambiguities, since there is no method of ensuring +that the magic number used to specify object-file formats is unique. +However, the configuration procedure for BFD on each system places the +conventional format for that system first in the search-list, so +ambiguities are resolved in favor of convention. + + +File: ld.info, Node: Commands, Next: Machine Dependent, Prev: Invocation, Up: Top + +Command Language +**************** + + The command language provides explicit control over the link process, +allowing complete specification of the mapping between the linker's +input files and its output. It controls: + * input files + + * file formats + + * output file layout + + * addresses of sections + + * placement of common blocks + + You may supply a command file (also known as a link script) to the +linker either explicitly through the `-T' option, or implicitly as an +ordinary file. If the linker opens a file which it cannot recognize as +a supported object or archive format, it reports an error. + +* Menu: + +* Scripts:: Linker Scripts +* Expressions:: Expressions +* MEMORY:: MEMORY Command +* SECTIONS:: SECTIONS Command +* Entry Point:: The Entry Point +* Option Commands:: Option Commands + + +File: ld.info, Node: Scripts, Next: Expressions, Up: Commands + +Linker Scripts +============== + + The `ld' command language is a collection of statements; some are +simple keywords setting a particular option, some are used to select and +group input files or name output files; and two statement types have a +fundamental and pervasive impact on the linking process. + + The most fundamental command of the `ld' command language is the +`SECTIONS' command (*note SECTIONS::.). Every meaningful command +script must have a `SECTIONS' command: it specifies a "picture" of the +output file's layout, in varying degrees of detail. No other command +is required in all cases. + + The `MEMORY' command complements `SECTIONS' by describing the +available memory in the target architecture. This command is optional; +if you don't use a `MEMORY' command, `ld' assumes sufficient memory is +available in a contiguous block for all output. *Note MEMORY::. + + You may include comments in linker scripts just as in C: delimited +by `/*' and `*/'. As in C, comments are syntactically equivalent to +whitespace. + + +File: ld.info, Node: Expressions, Next: MEMORY, Prev: Scripts, Up: Commands + +Expressions +=========== + + Many useful commands involve arithmetic expressions. The syntax for +expressions in the command language is identical to that of C +expressions, with the following features: + * All expressions evaluated as integers and are of "long" or + "unsigned long" type. + + * All constants are integers. + + * All of the C arithmetic operators are provided. + + * You may reference, define, and create global variables. + + * You may call special purpose built-in functions. + +* Menu: + +* Integers:: Integers +* Symbols:: Symbol Names +* Location Counter:: The Location Counter +* Operators:: Operators +* Evaluation:: Evaluation +* Assignment:: Assignment: Defining Symbols +* Arithmetic Functions:: Built-In Functions + + +File: ld.info, Node: Integers, Next: Symbols, Up: Expressions + +Integers +-------- + + An octal integer is `0' followed by zero or more of the octal digits +(`01234567'). + _as_octal = 0157255; + + A decimal integer starts with a non-zero digit followed by zero or +more digits (`0123456789'). + _as_decimal = 57005; + + A hexadecimal integer is `0x' or `0X' followed by one or more +hexadecimal digits chosen from `0123456789abcdefABCDEF'. + _as_hex = 0xdead; + + To write a negative integer, use the prefix operator `-'; *note +Operators::.. + _as_neg = -57005; + + Additionally the suffixes `K' and `M' may be used to scale a +constant by `1024' or `1024*1024' respectively. For example, the +following all refer to the same quantity: + + _fourk_1 = 4K; + _fourk_2 = 4096; + _fourk_3 = 0x1000; + + +File: ld.info, Node: Symbols, Next: Location Counter, Prev: Integers, Up: Expressions + +Symbol Names +------------ + + Unless quoted, symbol names start with a letter, underscore, point or +hyphen and may include any letters, underscores, digits, points, and +minus signs. Unquoted symbol names must not conflict with any +keywords. You can specify a symbol which contains odd characters or has +the same name as a keyword, by surrounding the symbol name in double +quotes: + "SECTION" = 9; + "with a space" = "also with a space" + 10; + + +File: ld.info, Node: Location Counter, Next: Operators, Prev: Symbols, Up: Expressions + +The Location Counter +-------------------- + + The special linker variable "dot" `.' always contains the current +output location counter. Since the `.' always refers to a location in +an output section, it must always appear in an expression within a +`SECTIONS' command. The `.' symbol may appear anywhere that an ordinary +symbol is allowed in an expression, but its assignments have a side +effect. Assigning a value to the `.' symbol will cause the location +counter to be moved. This may be used to create holes in the output +section. The location counter may never be moved backwards. + SECTIONS + { + output : + { + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + } = 0x1234; + } + +In the previous example, `file1' is located at the beginning of the +output section, then there is a 1000 byte gap. Then `file2' appears, +also with a 1000 byte gap following before `file3' is loaded. The +notation `= 0x1234' specifies what data to write in the gaps (*note +Section Options::.). + + +File: ld.info, Node: Operators, Next: Evaluation, Prev: Location Counter, Up: Expressions + +Operators +--------- + + The linker recognizes the standard C set of arithmetic operators, +with the standard bindings and precedence levels: + precedence associativity Operators Notes + (highest) + 1 left ! - ~ (1) + 2 left * / % + 3 left + - + 4 left >> << + 5 left == != > < <= >= + 6 left & + 7 left | + 8 left && + 9 left || + 10 right ? : + 11 right &= += -= *= /= (2) + (lowest) + Notes: (1) Prefix operators (2) *Note Assignment:: + + +File: ld.info, Node: Evaluation, Next: Assignment, Prev: Operators, Up: Expressions + +Evaluation +---------- + + The linker uses "lazy evaluation" for expressions; it only calculates +an expression when absolutely necessary. The linker needs the value of +the start address, and the lengths of memory regions, in order to do any +linking at all; these values are computed as soon as possible when the +linker reads in the command file. However, other values (such as symbol +values) are not known or needed until after storage allocation. Such +values are evaluated later, when other information (such as the sizes of +output sections) is available for use in the symbol assignment +expression. + + +File: ld.info, Node: Assignment, Next: Arithmetic Functions, Prev: Evaluation, Up: Expressions + +Assignment: Defining Symbols +---------------------------- + + You may create global symbols, and assign values (addresses) to +global symbols, using any of the C assignment operators: + +`SYMBOL = EXPRESSION ;' +`SYMBOL &= EXPRESSION ;' +`SYMBOL += EXPRESSION ;' +`SYMBOL -= EXPRESSION ;' +`SYMBOL *= EXPRESSION ;' +`SYMBOL /= EXPRESSION ;' + Two things distinguish assignment from other operators in `ld' +expressions. + * Assignment may only be used at the root of an expression; `a=b+3;' + is allowed, but `a+b=3;' is an error. + + * You must place a trailing semicolon (";") at the end of an + assignment statement. + + Assignment statements may appear: + * as commands in their own right in an `ld' script; or + + * as independent statements within a `SECTIONS' command; or + + * as part of the contents of a section definition in a `SECTIONS' + command. + + The first two cases are equivalent in effect--both define a symbol +with an absolute address. The last case defines a symbol whose address +is relative to a particular section (*note SECTIONS::.). + + When a linker expression is evaluated and assigned to a variable, it +is given either an absolute or a relocatable type. An absolute +expression type is one in which the symbol contains the value that it +will have in the output file; a relocatable expression type is one in +which the value is expressed as a fixed offset from the base of a +section. + + The type of the expression is controlled by its position in the +script file. A symbol assigned within a section definition is created +relative to the base of the section; a symbol assigned in any other +place is created as an absolute symbol. Since a symbol created within a +section definition is relative to the base of the section, it will +remain relocatable if relocatable output is requested. A symbol may be +created with an absolute value even when assigned to within a section +definition by using the absolute assignment function `ABSOLUTE'. For +example, to create an absolute symbol whose address is the last byte of +an output section named `.data': + SECTIONS{ ... + .data : + { + *(.data) + _edata = ABSOLUTE(.) ; + } + ... } + + The linker tries to put off the evaluation of an assignment until all +the terms in the source expression are known (*note Evaluation::.). For +instance, the sizes of sections cannot be known until after allocation, +so assignments dependent upon these are not performed until after +allocation. Some expressions, such as those depending upon the location +counter "dot", `.' must be evaluated during allocation. If the result +of an expression is required, but the value is not available, then an +error results. For example, a script like the following + SECTIONS { ... + text 9+this_isnt_constant : + { ... + } + ... } + +will cause the error message "`Non constant expression for initial +address'". + + +File: ld.info, Node: Arithmetic Functions, Prev: Assignment, Up: Expressions + +Arithmetic Functions +-------------------- + + The command language includes a number of built-in functions for use +in link script expressions. +`ABSOLUTE(EXP)' + Return the absolute (non-relocatable, as opposed to non-negative) + value of the expression EXP. Primarily useful to assign an + absolute value to a symbol within a section definition, where + symbol values are normally section-relative. + +`ADDR(SECTION)' + Return the absolute address of the named SECTION. Your script must + previously have defined the location of that section. In the + following example, `symbol_1' and `symbol_2' are assigned identical + values: + SECTIONS{ ... + .output1 : + { + start_of_output_1 = ABSOLUTE(.); + ... + } + .output : + { + symbol_1 = ADDR(.output1); + symbol_2 = start_of_output_1; + } + ... } + +`ALIGN(EXP)' + Return the result of the current location counter (`.') aligned to + the next EXP boundary. EXP must be an expression whose value is a + power of two. This is equivalent to + (. + EXP - 1) & ~(EXP - 1) + + `ALIGN' doesn't change the value of the location counter--it just + does arithmetic on it. As an example, to align the output `.data' + section to the next `0x2000' byte boundary after the preceding + section and to set a variable within the section to the next + `0x8000' boundary after the input sections: + SECTIONS{ ... + .data ALIGN(0x2000): { + *(.data) + variable = ALIGN(0x8000); + } + ... } + + The first use of `ALIGN' in this example specifies the location of + a section because it is used as the optional START attribute of a + section definition (*note Section Options::.). The second use + simply defines the value of a variable. + + The built-in `NEXT' is closely related to `ALIGN'. + +`DEFINED(SYMBOL)' + Return 1 if SYMBOL is in the linker global symbol table and is + defined, otherwise return 0. You can use this function to provide + default values for symbols. For example, the following + command-file fragment shows how to set a global symbol `begin' to + the first location in the `.text' section--but if a symbol called + `begin' already existed, its value is preserved: + SECTIONS{ ... + .text : { + begin = DEFINED(begin) ? begin : . ; + ... + } + ... } + +`NEXT(EXP)' + Return the next unallocated address that is a multiple of EXP. + This function is closely related to `ALIGN(EXP)'; unless you use + the `MEMORY' command to define discontinuous memory for the output + file, the two functions are equivalent. + +`SIZEOF(SECTION)' + Return the size in bytes of the named SECTION, if that section has + been allocated. In the following example, `symbol_1' and + `symbol_2' are assigned identical values: + SECTIONS{ ... + .output { + .start = . ; + ... + .end = . ; + } + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); + ... } + +`SIZEOF_HEADERS' +`sizeof_headers' + Return the size in bytes of the output file's headers. You can + use this number as the start address of the first section, if you + choose, to facilitate paging. + + +File: ld.info, Node: MEMORY, Next: SECTIONS, Prev: Expressions, Up: Commands + +Memory Layout +============= + + The linker's default configuration permits allocation of all +available memory. You can override this configuration by using the +`MEMORY' command. The `MEMORY' command describes the location and size +of blocks of memory in the target. By using it carefully, you can +describe which memory regions may be used by the linker, and which +memory regions it must avoid. The linker does not shuffle sections to +fit into the available regions, but does move the requested sections +into the correct regions and issue errors when the regions become too +full. + + A command file may contain at most one use of the `MEMORY' command; +however, you can define as many blocks of memory within it as you wish. +The syntax is: + + MEMORY + { + NAME (ATTR) : ORIGIN = ORIGIN, LENGTH = LEN + ... + } + +`NAME' + is a name used internally by the linker to refer to the region. Any + symbol name may be used. The region names are stored in a separate + name space, and will not conflict with symbols, file names or + section names. Use distinct names to specify multiple regions. + +`(ATTR)' + is an optional list of attributes, permitted for compatibility + with the AT&T linker but not used by `ld' beyond checking that the + attribute list is valid. Valid attribute lists must be made up of + the characters "`LIRWX'". If you omit the attribute list, you may + omit the parentheses around it as well. + +`ORIGIN' + is the start address of the region in physical memory. It is an + expression that must evaluate to a constant before memory + allocation is performed. The keyword `ORIGIN' may be abbreviated + to `org' or `o' (but not, for example, `ORG'). + +`LEN' + is the size in bytes of the region (an expression). The keyword + `LENGTH' may be abbreviated to `len' or `l'. + + For example, to specify that memory has two regions available for +allocation--one starting at 0 for 256 kilobytes, and the other starting +at `0x40000000' for four megabytes: + + MEMORY + { + rom : ORIGIN = 0, LENGTH = 256K + ram : org = 0x40000000, l = 4M + } + + Once you have defined a region of memory named MEM, you can direct +specific output sections there by using a command ending in `>MEM' +within the `SECTIONS' command (*note Section Options::.). If the +combined output sections directed to a region are too big for the +region, the linker will issue an error message. + + +File: ld.info, Node: SECTIONS, Next: Entry Point, Prev: MEMORY, Up: Commands + +Specifying Output Sections +========================== + + The `SECTIONS' command controls exactly where input sections are +placed into output sections, their order in the output file, and to +which output sections they are allocated. + + You may use at most one `SECTIONS' command in a script file, but you +can have as many statements within it as you wish. Statements within +the `SECTIONS' command can do one of three things: + * define the entry point; + + * assign a value to a symbol; + + * describe the placement of a named output section, and which input + sections go into it. + + You can also use the first two operations--defining the entry point +and defining symbols--outside the `SECTIONS' command: *note Entry +Point::., and *note Assignment::.. They are permitted here as well for +your convenience in reading the script, so that symbols and the entry +point can be defined at meaningful points in your output-file layout. + + When no `SECTIONS' command is given, the linker places each input +section into an identically named output section in the order that the +sections are first encountered in the input files. If all input +sections are present in the first file, for example, the order of +sections in the output file will match the order in the first input +file. + +* Menu: + +* Section Definition:: Section Definitions +* Section Placement:: Section Placement +* Section Data Expressions:: Section Data Expressions +* Section Options:: Optional Section Attributes + + +File: ld.info, Node: Section Definition, Next: Section Placement, Up: SECTIONS + +Section Definitions +------------------- + + The most frequently used statement in the `SECTIONS' command is the +"section definition", which specifies the properties of an output +section: its location, alignment, contents, fill pattern, and target +memory region. Most of these specifications are optional; the simplest +form of a section definition is + SECTIONS { ... + SECNAME : { + CONTENTS + } + ... } + +SECNAME is the name of the output section, and CONTENTS a specification +of what goes there--for example, a list of input files or sections of +input files (*note Section Placement::.). As you might assume, the +whitespace shown is optional. You do need the colon `:' and the braces +`{}', however. + + SECNAME must meet the constraints of your output format. In formats +which only support a limited number of sections, such as `a.out', the +name must be one of the names supported by the format (`a.out', for +example, allows only `.text', `.data' or `.bss'). If the output format +supports any number of sections, but with numbers and not names (as is +the case for Oasys), the name should be supplied as a quoted numeric +string. A section name may consist of any sequence of characters, but +any name which does not conform to the standard `ld' symbol name syntax +must be quoted. *Note Symbol Names: Symbols. + + +File: ld.info, Node: Section Placement, Next: Section Data Expressions, Prev: Section Definition, Up: SECTIONS + +Section Placement +----------------- + + In a section definition, you can specify the contents of an output +section by listing particular input files, by listing particular +input-file sections, or by a combination of the two. You can also +place arbitrary data in the section, and define symbols relative to the +beginning of the section. + + The CONTENTS of a section definition may include any of the +following kinds of statement. You can include as many of these as you +like in a single section definition, separated from one another by +whitespace. + +`FILENAME' + You may simply name a particular input file to be placed in the + current output section; *all* sections from that file are placed + in the current section definition. If the file name has already + been mentioned in another section definition, with an explicit + section name list, then only those sections which have not yet + been allocated are used. + + To specify a list of particular files by name: + .data : { afile.o bfile.o cfile.o } + + The example also illustrates that multiple statements can be + included in the contents of a section definition, since each file + name is a separate statement. + +`FILENAME( SECTION )' +`FILENAME( SECTION, SECTION, ... )' +`FILENAME( SECTION SECTION ... )' + You can name one or more sections from your input files, for + insertion in the current output section. If you wish to specify a + list of input-file sections inside the parentheses, you may + separate the section names by either commas or whitespace. + +`* (SECTION)' +`* (SECTION, SECTION, ...)' +`* (SECTION SECTION ...)' + Instead of explicitly naming particular input files in a link + control script, you can refer to *all* files from the `ld' command + line: use `*' instead of a particular file name before the + parenthesized input-file section list. + + If you have already explicitly included some files by name, `*' + refers to all *remaining* files--those whose places in the output + file have not yet been defined. + + For example, to copy sections `1' through `4' from an Oasys file + into the `.text' section of an `a.out' file, and sections `13' and + `14' into the `.data' section: + SECTIONS { + .text :{ + *("1" "2" "3" "4") + } + + .data :{ + *("13" "14") + } + } + + `[ SECTION ... ]' used to be accepted as an alternate way to + specify named sections from all unallocated input files. Because + some operating systems (VMS) allow brackets in file names, that + notation is no longer supported. + +`FILENAME`( COMMON )'' +`*( COMMON )' + Specify where in your output file to place uninitialized data with + this notation. `*(COMMON)' by itself refers to all uninitialized + data from all input files (so far as it is not yet allocated); + FILENAME`(COMMON)' refers to uninitialized data from a particular + file. Both are special cases of the general mechanisms for + specifying where to place input-file sections: `ld' permits you to + refer to uninitialized data as if it were in an input-file section + named `COMMON', regardless of the input file's format. + + For example, the following command script arranges the output file +into three consecutive sections, named `.text', `.data', and `.bss', +taking the input for each from the correspondingly named sections of +all the input files: + SECTIONS { + .text : { *(.text) } + .data : { *(.data) } + .bss : { *(.bss) *(COMMON) } + } + + The following example reads all of the sections from file `all.o' +and places them at the start of output section `outputa' which starts +at location `0x10000'. All of section `.input1' from file `foo.o' +follows immediately, in the same output section. All of section +`.input2' from `foo.o' goes into output section `outputb', followed by +section `.input1' from `foo1.o'. All of the remaining `.input1' and +`.input2' sections from any files are written to output section +`outputc'. + + SECTIONS { + outputa 0x10000 : + { + all.o + foo.o (.input1) + } + outputb : + { + foo.o (.input2) + foo1.o (.input1) + } + outputc : + { + *(.input1) + *(.input2) + } + } + + +File: ld.info, Node: Section Data Expressions, Next: Section Options, Prev: Section Placement, Up: SECTIONS + +Section Data Expressions +------------------------ + + The foregoing statements arrange, in your output file, data +originating from your input files. You can also place data directly in +an output section from the link command script. Most of these +additional statements involve expressions; *note Expressions::.. +Although these statements are shown separately here for ease of +presentation, no such segregation is needed within a section definition +in the `SECTIONS' command; you can intermix them freely with any of the +statements we've just described. + +`CREATE_OBJECT_SYMBOLS' + Create a symbol for each input file in the current section, set to + the address of the first byte of data written from that input + file. For instance, with `a.out' files it is conventional to have + a symbol for each input file. You can accomplish this by defining + the output `.text' section as follows: + SECTIONS { + .text 0x2020 : + { + CREATE_OBJECT_SYMBOLS + *(.text) + _etext = ALIGN(0x2000); + } + ... + } + + If `sample.ld' is a file containing this script, and `a.o', `b.o', + `c.o', and `d.o' are four input files with contents like the + following-- + /* a.c */ + + afunction() { } + int adata=1; + int abss; + + `ld -M -T sample.ld a.o b.o c.o d.o' would create a map like this, + containing symbols matching the object file names: + 00000000 A __DYNAMIC + 00004020 B _abss + 00004000 D _adata + 00002020 T _afunction + 00004024 B _bbss + 00004008 D _bdata + 00002038 T _bfunction + 00004028 B _cbss + 00004010 D _cdata + 00002050 T _cfunction + 0000402c B _dbss + 00004018 D _ddata + 00002068 T _dfunction + 00004020 D _edata + 00004030 B _end + 00004000 T _etext + 00002020 t a.o + 00002038 t b.o + 00002050 t c.o + 00002068 t d.o + +`SYMBOL = EXPRESSION ;' +`SYMBOL F= EXPRESSION ;' + SYMBOL is any symbol name (*note Symbols::.). "F=" refers to any + of the operators `&= += -= *= /=' which combine arithmetic and + assignment. + + When you assign a value to a symbol within a particular section + definition, the value is relative to the beginning of the section + (*note Assignment::.). If you write + SECTIONS { + abs = 14 ; + ... + .data : { ... rel = 14 ; ... } + abs2 = 14 + ADDR(.data); + ... + } + + `abs' and `rel' do not have the same value; `rel' has the same + value as `abs2'. + +`BYTE(EXPRESSION)' +`SHORT(EXPRESSION)' +`LONG(EXPRESSION)' + By including one of these three statements in a section + definition, you can explicitly place one, two, or four bytes + (respectively) at the current address of that section. + + Multiple-byte quantities are represented in whatever byte order is + appropriate for the output file format (*note BFD::.). + +`FILL(EXPRESSION)' + Specify the "fill pattern" for the current section. Any otherwise + unspecified regions of memory within the section (for example, + regions you skip over by assigning a new value to the location + counter `.') are filled with the two least significant bytes from + the EXPRESSION argument. A `FILL' statement covers memory + locations *after* the point it occurs in the section definition; by + including more than one `FILL' statement, you can have different + fill patterns in different parts of an output section. + diff --git a/ld/ld.info-2 b/ld/ld.info-2 new file mode 100644 index 0000000..5a93f63 --- /dev/null +++ b/ld/ld.info-2 @@ -0,0 +1,941 @@ +This is Info file ld.info, produced by Makeinfo-1.55 from the input +file ./ld.texinfo. + +START-INFO-DIR-ENTRY +* Ld:: The GNU linker. +END-INFO-DIR-ENTRY + + This file documents the GNU linker LD. + + 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 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. + + +File: ld.info, Node: Section Options, Prev: Section Data Expressions, Up: SECTIONS + +Optional Section Attributes +--------------------------- + + Here is the full syntax of a section definition, including all the +optional portions: + + SECTIONS { + ... + SECNAME START BLOCK(ALIGN) (NOLOAD) : { CONTENTS } =FILL >REGION + ... + } + + SECNAME and CONTENTS are required. *Note Section Definition::, and +*note Section Placement::. for details on CONTENTS. The remaining +elements--START, `BLOCK(ALIGN)', `(NOLOAD)' `=FILL', and `>REGION'--are +all optional. + +`START' + You can force the output section to be loaded at a specified + address by specifying START immediately following the section name. + sTART can be represented as any expression. The following example + generates section OUTPUT at location `0x40000000': + SECTIONS { + ... + output 0x40000000: { + ... + } + ... + } + +`BLOCK(ALIGN)' + You can include `BLOCK()' specification to advance the location + counter `.' prior to the beginning of the section, so that the + section will begin at the specified alignment. ALIGN is an + expression. + +`(NOLOAD)' + Use `(NOLOAD)' to prevent a section from being loaded into memory + each time it is accessed. For example, in the script sample + below, the `ROM' segment is addressed at memory location `0' and + does not need to be loaded into each object file: + SECTIONS { + ROM 0 (NOLOAD) : { ... } + ... + } + +`=FILL' + Including `=FILL' in a section definition specifies the initial + fill value for that section. You may use any expression to + specify FILL. Any unallocated holes in the current output section + when written to the output file will be filled with the two least + significant bytes of the value, repeated as necessary. You can + also change the fill value with a `FILL' statement in the CONTENTS + of a section definition. + +`>REGION' + Assign this section to a previously defined region of memory. + *Note MEMORY::. + + +File: ld.info, Node: Entry Point, Next: Option Commands, Prev: SECTIONS, Up: Commands + +The Entry Point +=============== + + The linker command language includes a command specifically for +defining the first executable instruction in an output file (its "entry +point"). Its argument is a symbol name: + ENTRY(SYMBOL) + + Like symbol assignments, the `ENTRY' command may be placed either as +an independent command in the command file, or among the section +definitions within the `SECTIONS' command--whatever makes the most +sense for your layout. + + `ENTRY' is only one of several ways of choosing the entry point. +You may indicate it in any of the following ways (shown in descending +order of priority: methods higher in the list override methods lower +down). + * the `-e' ENTRY command-line option; + + * the `ENTRY(SYMBOL' command in a linker control script; + + * the value of the symbol `start', if present; + + * the value of the symbol `_main', if present; + + * the address of the first byte of the `.text' section, if present; + + * The address `0'. + + For example, you can use these rules to generate an entry point with +an assignment statement: if no symbol `start' is defined within your +input files, you can simply define it, assigning it an appropriate +value-- + start = 0x2020; + +The example shows an absolute address, but you can use any expression. +For example, if your input object files use some other symbol-name +convention for the entry point, you can just assign the value of +whatever symbol contains the start address to `start': + start = other_symbol ; + + +File: ld.info, Node: Option Commands, Prev: Entry Point, Up: Commands + +Option Commands +=============== + + The command language includes a number of other commands that you can +use for specialized purposes. They are similar in purpose to +command-line options. + +`FLOAT' +`NOFLOAT' + These keywords were used in some older linkers to request a + particular math subroutine library. `ld' doesn't use the + keywords, assuming instead that any necessary subroutines are in + libraries specified using the general mechanisms for linking to + archives; but to permit the use of scripts that were written for + the older linkers, the keywords `FLOAT' and `NOFLOAT' are accepted + and ignored. + +`FORCE_COMMON_ALLOCATION' + This command has the same effect as the `-d' command-line option: + to make `ld' assign space to common symbols even if a relocatable + output file is specified (`-r'). + +`INPUT ( FILE, FILE, ... )' +`INPUT ( FILE FILE ... )' + Use this command to include binary input files in the link, without + including them in a particular section definition. Specify the + full name for each FILE, including `.a' if required. + + `ld' searches for each FILE through the archive-library search + path, just as for files you specify on the command line. See the + description of `-L' in *Note Command Line Options: Options. + +`OUTPUT ( FILENAME )' + Use this command to name the link output file FILENAME. The + effect of `OUTPUT(FILENAME)' is identical to the effect of + `-o FILENAME', which overrides it. You can use this command to + supply a default output-file name other than `a.out'. + +`OUTPUT_ARCH ( BFDNAME )' + Specify a particular output machine architecture, with one of the + names used by the BFD back-end routines (*note BFD::.). This + command is often unnecessary; the architecture is most often set + implicitly by either the system BFD configuration or as a side + effect of the `OUTPUT_FORMAT' command. + +`OUTPUT_FORMAT ( BFDNAME )' + Specify a particular output format, with one of the names used by + the BFD back-end routines (*note BFD::.). The effect is identical + to the effect of the `-oformat' command-line option. This + selection will only affect the output file; the related command + `TARGET' affects primarily input files. + +`SEARCH_DIR ( PATH )' + Add PATH to the list of paths where `ld' looks for archive + libraries. `SEARCH_DIR(PATH)' has the same effect as `-LPATH' on + the command line. + +`STARTUP ( FILENAME )' + Ensure that FILENAME is the first input file used in the link + process. + +`TARGET ( FORMAT )' + Change the input-file object code format (like the command-line + option `-b' or its synonym `-format'). The argument FORMAT is one + of the strings used by BFD to name binary formats. If `TARGET' is + specified but `OUTPUT_FORMAT' is not, the last `TARGET' argument + is also used as the default format for the `ld' output file. + *Note BFD::. + + If you don't use the `TARGET' command, `ld' uses the value of the + environment variable `GNUTARGET', if available, to select the + output file format. If that variable is also absent, `ld' uses + the default format configured for your machine in the BFD + libraries. + + +File: ld.info, Node: Machine Dependent, Next: BFD, Prev: Commands, Up: Top + +Machine Dependent Features +************************** + + `ld' has additional features on some platforms; the following +sections describe them. Machines where `ld' has no additional +functionality are not listed. + +* Menu: + +* H8/300:: `ld' and the H8/300 +* i960:: `ld' and the Intel 960 family + + +File: ld.info, Node: H8/300, Next: i960, Up: Machine Dependent + +`ld' and the H8/300 +=================== + + For the H8/300, `ld' can perform these global optimizations when you +specify the `-relax' command-line option. + +*relaxing address modes* + `ld' finds all `jsr' and `jmp' instructions whose targets are + within eight bits, and turns them into eight-bit program-counter + relative `bsr' and `bra' instructions, respectively. + +*synthesizing instructions* + `ld' finds all `mov.b' instructions which use the sixteen-bit + absolute address form, but refer to the top page of memory, and + changes them to use the eight-bit address form. (That is: the + linker turns `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the + address AA is in the top page of memory). + + +File: ld.info, Node: i960, Prev: H8/300, Up: Machine Dependent + +`ld' and the Intel 960 family +============================= + + You can use the `-AARCHITECTURE' command line option to specify one +of the two-letter names identifying members of the 960 family; the +option specifies the desired output target, and warns of any +incompatible instructions in the input files. It also modifies the +linker's search strategy for archive libraries, to support the use of +libraries specific to each particular architecture, by including in the +search loop names suffixed with the string identifying the architecture. + + For example, if your `ld' command line included `-ACA' as well as +`-ltry', the linker would look (in its built-in search paths, and in +any paths you specify with `-L') for a library with the names + + try + libtry.a + tryca + libtryca.a + +The first two possibilities would be considered in any event; the last +two are due to the use of `-ACA'. + + You can meaningfully use `-A' more than once on a command line, since +the 960 architecture family allows combination of target architectures; +each use will add another pair of name variants to search for when `-l' +specifies a library. + + +File: ld.info, Node: BFD, Next: MRI, Prev: Machine Dependent, Up: Top + +BFD +*** + + The linker accesses object and archive files using the BFD libraries. +These libraries allow the linker to use the same routines to operate on +object files whatever the object file format. A different object file +format can be supported simply by creating a new BFD back end and adding +it to the library. You can use `objdump -i' (*note objdump: +(binutils.info)objdump.) to list all the formats available for each +architecture under BFD. This was the list of formats, and of +architectures supported for each format, as of the time this manual was +prepared: + BFD header file version 0.18 + a.out-i386 + (header big endian, data big endian) + m68k:68020 + a29k + sparc + i386 + a.out-sunos-big + (header big endian, data big endian) + m68k:68020 + a29k + sparc + i386 + b.out.big + (header big endian, data little endian) + i960:core + b.out.little + (header little endian, data little endian) + i960:core + coff-a29k-big + (header big endian, data big endian) + a29k + coff-h8300 + (header big endian, data big endian) + H8/300 + coff-i386 + (header little endian, data little endian) + i386 + coff-Intel-big + (header big endian, data little endian) + i960:core + coff-Intel-little + (header little endian, data little endian) + i960:core + coff-m68k + (header big endian, data big endian) + m68k:68020 + coff-m88kbcs + (header big endian, data big endian) + m88k:88100 + ecoff-bigmips + (header big endian, data big endian) + mips + ecoff-littlemips + (header little endian, data little endian) + mips + elf-big + (header big endian, data big endian) + m68k:68020 + vax + i960:core + a29k + sparc + mips + i386 + m88k:88100 + H8/300 + rs6000:6000 + elf-little + (header little endian, data little endian) + m68k:68020 + vax + i960:core + a29k + sparc + mips + i386 + m88k:88100 + H8/300 + rs6000:6000 + ieee + (header big endian, data big endian) + m68k:68020 + vax + i960:core + a29k + sparc + mips + i386 + m88k:88100 + H8/300 + rs6000:6000 + srec + (header big endian, data big endian) + m68k:68020 + vax + i960:core + a29k + sparc + mips + i386 + m88k:88100 + H8/300 + rs6000:6000 + + As with most implementations, BFD is a compromise between several +conflicting requirements. The major factor influencing BFD design was +efficiency: any time used converting between formats is time which +would not have been spent had BFD not been involved. This is partly +offset by abstraction payback; since BFD simplifies applications and +back ends, more time and care may be spent optimizing algorithms for a +greater speed. + + One minor artifact of the BFD solution which you should bear in mind +is the potential for information loss. There are two places where +useful information can be lost using the BFD mechanism: during +conversion and during output. *Note BFD information loss::. + +* Menu: + +* BFD outline:: How it works: an outline of BFD + + +File: ld.info, Node: BFD outline, Up: BFD + +How it works: an outline of BFD +=============================== + + When an object file is opened, BFD subroutines automatically +determine the format of the input object file. They then build a +descriptor in memory with pointers to routines that will be used to +access elements of the object file's data structures. + + As different information from the the object files is required, BFD +reads from different sections of the file and processes them. For +example, a very common operation for the linker is processing symbol +tables. Each BFD back end provides a routine for converting between +the object file's representation of symbols and an internal canonical +format. When the linker asks for the symbol table of an object file, it +calls through a memory pointer to the routine from the relevant BFD +back end which reads and converts the table into a canonical form. The +linker then operates upon the canonical form. When the link is finished +and the linker writes the output file's symbol table, another BFD back +end routine is called to take the newly created symbol table and +convert it into the chosen output format. + +* Menu: + +* BFD information loss:: Information Loss +* Canonical format:: The BFD canonical object-file format + + +File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline + +Information Loss +---------------- + + *Information can be lost during output.* The output formats +supported by BFD do not provide identical facilities, and information +which can be described in one form has nowhere to go in another format. +One example of this is alignment information in `b.out'. There is +nowhere in an `a.out' format file to store alignment information on the +contained data, so when a file is linked from `b.out' and an `a.out' +image is produced, alignment information will not propagate to the +output file. (The linker will still use the alignment information +internally, so the link is performed correctly). + + Another example is COFF section names. COFF files may contain an +unlimited number of sections, each one with a textual section name. If +the target of the link is a format which does not have many sections +(e.g., `a.out') or has sections without names (e.g., the Oasys format), +the link cannot be done simply. You can circumvent this problem by +describing the desired input-to-output section mapping with the linker +command language. + + *Information can be lost during canonicalization.* The BFD internal +canonical form of the external formats is not exhaustive; there are +structures in input formats for which there is no direct representation +internally. This means that the BFD back ends cannot maintain all +possible data richness through the transformation between external to +internal and back to external formats. + + This limitation is only a problem when an application reads one +format and writes another. Each BFD back end is responsible for +maintaining as much data as possible, and the internal BFD canonical +form has structures which are opaque to the BFD core, and exported only +to the back ends. When a file is read in one format, the canonical form +is generated for BFD and the application. At the same time, the back +end saves away any information which may otherwise be lost. If the data +is then written back in the same format, the back end routine will be +able to use the canonical form provided by the BFD core as well as the +information it prepared earlier. Since there is a great deal of +commonality between back ends, there is no information lost when +linking or copying big endian COFF to little endian COFF, or `a.out' to +`b.out'. When a mixture of formats is linked, the information is only +lost from the files whose format differs from the destination. + + +File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline + +The BFD canonical object-file format +------------------------------------ + + The greatest potential for loss of information occurs when there is +the least overlap between the information provided by the source +format, that stored by the canonical format, and that needed by the +destination format. A brief description of the canonical form may help +you understand which kinds of data you can count on preserving across +conversions. + +*files* + Information stored on a per-file basis includes target machine + architecture, particular implementation format type, a demand + pageable bit, and a write protected bit. Information like Unix + magic numbers is not stored here--only the magic numbers' meaning, + so a `ZMAGIC' file would have both the demand pageable bit and the + write protected text bit set. The byte order of the target is + stored on a per-file basis, so that big- and little-endian object + files may be used with one another. + +*sections* + Each section in the input file contains the name of the section, + the section's original address in the object file, size and + alignment information, various flags, and pointers into other BFD + data structures. + +*symbols* + Each symbol contains a pointer to the information for the object + file which originally defined it, its name, its value, and various + flag bits. When a BFD back end reads in a symbol table, it + relocates all symbols to make them relative to the base of the + section where they were defined. Doing this ensures that each + symbol points to its containing section. Each symbol also has a + varying amount of hidden private data for the BFD back end. Since + the symbol points to the original file, the private data format + for that symbol is accessible. `ld' can operate on a collection + of symbols of wildly different formats without problems. + + Normal global and simple local symbols are maintained on output, + so an output file (no matter its format) will retain symbols + pointing to functions and to global, static, and common variables. + Some symbol information is not worth retaining; in `a.out', type + information is stored in the symbol table as long symbol names. + This information would be useless to most COFF debuggers; the + linker has command line switches to allow users to throw it away. + + There is one word of type information within the symbol, so if the + format supports symbol type information within symbols (for + example, COFF, IEEE, Oasys) and the type is simple enough to fit + within one word (nearly everything but aggregates), the + information will be preserved. + +*relocation level* + Each canonical BFD relocation record contains a pointer to the + symbol to relocate to, the offset of the data to relocate, the + section the data is in, and a pointer to a relocation type + descriptor. Relocation is performed by passing messages through + the relocation type descriptor and the symbol pointer. Therefore, + relocations can be performed on output data using a relocation + method that is only available in one of the input formats. For + instance, Oasys provides a byte relocation format. A relocation + record requesting this relocation type would point indirectly to a + routine to perform this, so the relocation may be performed on a + byte being written to a 68k COFF file, even though 68k COFF has no + such relocation type. + +*line numbers* + Object formats can contain, for debugging purposes, some form of + mapping between symbols, source line numbers, and addresses in the + output file. These addresses have to be relocated along with the + symbol information. Each symbol with an associated list of line + number records points to the first record of the list. The head + of a line number list consists of a pointer to the symbol, which + allows finding out the address of the function whose line number + is being described. The rest of the list is made up of pairs: + offsets into the section and line numbers. Any format which can + simply derive this information can pass it successfully between + formats (COFF, IEEE and Oasys). + + +File: ld.info, Node: MRI, Next: Index, Prev: BFD, Up: Top + +MRI Compatible Script Files +*************************** + + To aid users making the transition to GNU `ld' from the MRI linker, +`ld' can use MRI compatible linker scripts as an alternative to the +more general-purpose linker scripting language described in *Note +Command Language: Commands. MRI compatible linker scripts have a much +simpler command set than the scripting language otherwise used with +`ld'. GNU `ld' supports the most commonly used MRI linker commands; +these commands are described here. + + In general, MRI scripts aren't of much use with the `a.out' object +file format, since it only has three sections and MRI scripts lack some +features to make use of them. + + You can specify a file containing an MRI-compatible script using the +`-c' command-line option. + + Each command in an MRI-compatible script occupies its own line; each +command line starts with the keyword that identifies the command (though +blank lines are also allowed for punctuation). If a line of an +MRI-compatible script begins with an unrecognized keyword, `ld' issues +a warning message, but continues processing the script. + + Lines beginning with `*' are comments. + + You can write these commands using all upper-case letters, or all +lower case; for example, `chip' is the same as `CHIP'. The following +list shows only the upper-case form of each command. + +`ABSOLUTE SECNAME' +`ABSOLUTE SECNAME, SECNAME, ... SECNAME' + Normally, `ld' includes in the output file all sections from all + the input files. However, in an MRI-compatible script, you can + use the `ABSOLUTE' command to restrict the sections that will be + present in your output program. If the `ABSOLUTE' command is used + at all in a script, then only the sections named explicitly in + `ABSOLUTE' commands will appear in the linker output. You can + still use other input sections (whatever you select on the command + line, or using `LOAD') to resolve addresses in the output file. + +`ALIAS OUT-SECNAME, IN-SECNAME' + Use this command to place the data from input section IN-SECNAME + in a section called OUT-SECNAME in the linker output file. + + IN-SECNAME may be an integer. + +`BASE EXPRESSION' + Use the value of EXPRESSION as the lowest address (other than + absolute addresses) in the output file. + +`CHIP EXPRESSION' +`CHIP EXPRESSION, EXPRESSION' + This command does nothing; it is accepted only for compatibility. + +`END' + This command does nothing whatever; it's only accepted for + compatibility. + +`FORMAT OUTPUT-FORMAT' + Similar to the `OUTPUT_FORMAT' command in the more general linker + language, but restricted to one of these output formats: + 1. S-records, if OUTPUT-FORMAT is `S' + + 2. IEEE, if OUTPUT-FORMAT is `IEEE' + + 3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is + `COFF' + +`LIST ANYTHING...' + Print (to the standard output file) a link map, as produced by the + `ld' command-line option `-M'. + + The keyword `LIST' may be followed by anything on the same line, + with no change in its effect. + +`LOAD FILENAME' +`LOAD FILENAME, FILENAME, ... FILENAME' + Include one or more object file FILENAME in the link; this has the + same effect as specifying FILENAME directly on the `ld' command + line. + +`NAME OUTPUT-NAME' + OUTPUT-NAME is the name for the program produced by `ld'; the + MRI-compatible command `NAME' is equivalent to the command-line + option `-o' or the general script language command `OUTPUT'. + +`ORDER SECNAME, SECNAME, ... SECNAME' +`ORDER SECNAME SECNAME SECNAME' + Normally, `ld' orders the sections in its output file in the order + in which they first appear in the input files. In an + MRI-compatible script, you can override this ordering with the + `ORDER' command. The sections you list with `ORDER' will appear + first in your output file, in the order specified. + +`PUBLIC NAME=EXPRESSION' +`PUBLIC NAME,EXPRESSION' +`PUBLIC NAME EXPRESSION' + Supply a value (EXPRESSION) for external symbol NAME used in the + linker input files. + +`SECT SECNAME, EXPRESSION' +`SECT SECNAME=EXPRESSION' +`SECT SECNAME EXPRESSION' + You can use any of these three forms of the `SECT' command to + specify the start address (EXPRESSION) for section SECNAME. If + you have more than one `SECT' statement for the same SECNAME, only + the *first* sets the start address. + + +File: ld.info, Node: Index, Prev: MRI, Up: Top + +Index +***** + +* Menu: + +* ": Symbols. +* *( COMMON ): Section Placement. +* *(SECTION): Section Placement. +* -help: Options. +* -version: Options. +* -AARCH: Options. +* -b FORMAT: Options. +* -Bstatic: Options. +* -c MRI-CMDFILE: Options. +* -d: Options. +* -dc: Options. +* -defsym SYMBOL=EXP: Options. +* -dp: Options. +* -e ENTRY: Options. +* -F: Options. +* -format: Options. +* -g: Options. +* -G: Options. +* -i: Options. +* -lARCHIVE: Options. +* -LDIR: Options. +* -M: Options. +* -m EMULATION: Options. +* -Map: Options. +* -N: Options. +* -n: Options. +* -noinhibit-exec: Options. +* -o OUTPUT: Options. +* -oformat: Options. +* -r: Options. +* -R FILE: Options. +* -relax: Options. +* -s: Options. +* -S: Options. +* -t: Options. +* -T SCRIPT: Options. +* -Tbss ORG: Options. +* -Tdata ORG: Options. +* -Ttext ORG: Options. +* -u SYMBOL: Options. +* -Ur: Options. +* -v: Options. +* -V: Options. +* -warn-comon: Options. +* -x: Options. +* -X: Options. +* -ySYMBOL: Options. +* .: Location Counter. +* 0x: Integers. +* ;: Assignment. +* =FILL: Section Options. +* >REGION: Section Options. +* ABSOLUTE (MRI): MRI. +* ALIAS (MRI): MRI. +* BASE (MRI): MRI. +* CHIP (MRI): MRI. +* END (MRI): MRI. +* FORMAT (MRI): MRI. +* LIST (MRI): MRI. +* LOAD (MRI): MRI. +* NAME (MRI): MRI. +* ORDER (MRI): MRI. +* PUBLIC (MRI): MRI. +* SECT (MRI): MRI. +* FILENAME: Section Placement. +* FILENAME(SECTION): Section Placement. +* SYMBOL = EXPRESSION ;: Section Data Expressions. +* SYMBOL F= EXPRESSION ;: Section Data Expressions. +* absolute and relocatable symbols: Assignment. +* ABSOLUTE(EXP): Arithmetic Functions. +* ADDR(SECTION): Arithmetic Functions. +* ALIGN(EXP): Arithmetic Functions. +* aligning sections: Section Options. +* allocating memory: MEMORY. +* architectures: Options. +* architectures available: BFD. +* archive files, from cmd line: Options. +* arithmetic: Expressions. +* arithmetic operators: Operators. +* assignment in scripts: Assignment. +* assignment, in section defn: Section Data Expressions. +* back end: BFD. +* BFD canonical format: Canonical format. +* BFD requirements: BFD. +* binary input files: Option Commands. +* binary input format: Options. +* BLOCK(ALIGN): Section Options. +* BYTE(EXPRESSION): Section Data Expressions. +* combining symbols, warnings on: Options. +* command files: Commands. +* command line: Options. +* commands, fundamental: Scripts. +* comments: Scripts. +* common allocation: Option Commands. +* common allocation: Options. +* commons in output: Section Placement. +* compatibility, MRI: Options. +* constructors: Options. +* contents of a section: Section Placement. +* CREATE_OBJECT_SYMBOLS: Section Data Expressions. +* current output location: Location Counter. +* decimal integers: Integers. +* default input format: Environment. +* DEFINED(SYMBOL): Arithmetic Functions. +* deleting local symbols: Options. +* direct output: Section Data Expressions. +* discontinuous memory: MEMORY. +* dot: Location Counter. +* emulation: Options. +* entry point, defaults: Entry Point. +* entry point, from command line: Options. +* ENTRY(SYMBOL): Entry Point. +* expression evaluation order: Evaluation. +* expression syntax: Expressions. +* expression, absolute: Arithmetic Functions. +* expressions in a section: Section Data Expressions. +* filename symbols: Section Data Expressions. +* files and sections, section defn: Section Placement. +* files, including in output sections: Section Placement. +* fill pattern, entire section: Section Options. +* FILL(EXPRESSION): Section Data Expressions. +* first input file: Option Commands. +* first instruction: Entry Point. +* FLOAT: Option Commands. +* FORCE_COMMON_ALLOCATION: Option Commands. +* format, output file: Option Commands. +* formats available: BFD. +* functions in expression language: Arithmetic Functions. +* fundamental script commands: Scripts. +* GNU linker: Overview. +* GNUTARGET: Option Commands. +* GNUTARGET: Environment. +* H8/300 support: H8/300. +* header size: Arithmetic Functions. +* help: Options. +* hexadecimal integers: Integers. +* holes: Location Counter. +* holes, filling: Section Data Expressions. +* i960 support: i960. +* incremental link: Options. +* INPUT ( FILES ): Option Commands. +* input file format: Option Commands. +* input filename symbols: Section Data Expressions. +* input files, displaying: Options. +* input files, section defn: Section Placement. +* input format: Options. +* input format: Options. +* input sections to output section: Section Placement. +* integer notation: Integers. +* integer suffixes: Integers. +* internal object-file format: Canonical format. +* K and M integer suffixes: Integers. +* l =: MEMORY. +* L, deleting symbols beginning: Options. +* layout of output file: Scripts. +* lazy evaluation: Evaluation. +* len =: MEMORY. +* LENGTH =: MEMORY. +* link map: Options. +* link map: Options. +* local symbols, deleting: Options. +* location counter: Location Counter. +* LONG(EXPRESSION): Section Data Expressions. +* M and K integer suffixes: Integers. +* machine architecture, output: Option Commands. +* machine dependencies: Machine Dependent. +* MEMORY: MEMORY. +* memory region attributes: MEMORY. +* memory regions and sections: Section Options. +* MRI compatibility: MRI. +* names: Symbols. +* naming memory regions: MEMORY. +* naming output sections: Section Definition. +* naming the output file: Options. +* naming the output file: Option Commands. +* negative integers: Integers. +* NEXT(EXP): Arithmetic Functions. +* NMAGIC: Options. +* NOFLOAT: Option Commands. +* NOLOAD: Section Options. +* Non constant expression: Assignment. +* o =: MEMORY. +* object file management: BFD. +* object files: Options. +* object size: Options. +* octal integers: Integers. +* OMAGIC: Options. +* opening object files: BFD outline. +* Operators for arithmetic: Operators. +* options: Options. +* org =: MEMORY. +* ORIGIN =: MEMORY. +* OUTPUT ( FILENAME ): Option Commands. +* output file after errors: Options. +* output file layout: Scripts. +* OUTPUT_ARCH ( BFDNAME ): Option Commands. +* OUTPUT_FORMAT ( BFDNAME ): Option Commands. +* partial link: Options. +* path for libraries: Option Commands. +* precedence in expressions: Operators. +* prevent unnecessary loading: Section Options. +* quoted symbol names: Symbols. +* read-only text: Options. +* read/write from cmd line: Options. +* regions of memory: MEMORY. +* relaxing addressing modes: Options. +* relaxing on H8/300: H8/300. +* relocatable and absolute symbols: Assignment. +* relocatable output: Options. +* requirements for BFD: BFD. +* rounding up location counter: Arithmetic Functions. +* scaled integers: Integers. +* script files: Options. +* search directory, from cmd line: Options. +* search path, libraries: Option Commands. +* SEARCH_DIR ( PATH ): Option Commands. +* section address: Arithmetic Functions. +* section address: Section Options. +* section alignment: Section Options. +* section definition: Section Definition. +* section defn, full syntax: Section Options. +* section fill pattern: Section Options. +* section size: Arithmetic Functions. +* section start: Section Options. +* section, assigning to memory region: Section Options. +* SECTIONS: SECTIONS. +* segment origins, cmd line: Options. +* semicolon: Assignment. +* SHORT(EXPRESSION): Section Data Expressions. +* SIZEOF(SECTION): Arithmetic Functions. +* SIZEOF_HEADERS: Arithmetic Functions. +* sizeof_headers: Arithmetic Functions. +* standard Unix system: Options. +* start address, section: Section Options. +* start of execution: Entry Point. +* STARTUP ( FILENAME ): Option Commands. +* strip all symbols: Options. +* strip debugger symbols: Options. +* suffixes for integers: Integers. +* symbol defaults: Arithmetic Functions. +* symbol definition, scripts: Assignment. +* symbol names: Symbols. +* symbol tracing: Options. +* symbol-only input: Options. +* symbols, from command line: Options. +* symbols, relocatable and absolute: Assignment. +* synthesizing linker: Options. +* synthesizing on H8/300: H8/300. +* TARGET ( FORMAT ): Option Commands. +* unallocated address, next: Arithmetic Functions. +* undefined symbol: Options. +* uninitialized data: Section Placement. +* unspecified memory: Section Data Expressions. +* usage: Options. +* variables, defining: Assignment. +* verbose: Options. +* version: Options. +* version: Options. +* warnings, on combining symbols: Options. +* what is this?: Overview. + + |