diff options
Diffstat (limited to 'contrib/binutils')
| -rw-r--r-- | contrib/binutils/binutils/doc/binutils.7 | 4917 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/as.7 | 8368 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/as.txt | 13924 | ||||
| -rw-r--r-- | contrib/binutils/ld/ld.7 | 7819 | ||||
| -rw-r--r-- | contrib/binutils/ld/ld.txt | 6564 | ||||
| -rw-r--r-- | contrib/binutils/ld/ldint.7 | 1277 |
6 files changed, 22381 insertions, 20488 deletions
diff --git a/contrib/binutils/binutils/doc/binutils.7 b/contrib/binutils/binutils/doc/binutils.7 new file mode 100644 index 000000000000..2c4c0e1b8f2b --- /dev/null +++ b/contrib/binutils/binutils/doc/binutils.7 @@ -0,0 +1,4917 @@ +.Dd 2015-03-02 +.Dt BINUTILS 7 +.Os +.Sh NAME +.Nm binutils +.Nd GNU Binary Utilities +.Sh Introduction +This brief manual contains documentation for the GNU binary utilities version "2.17.50 +[FreeBSD] 2007-07-03": +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled "GNU Free +Documentation License". +.Pp +.Sh ar +.Bd -literal -offset indent +ar [-]p[mod [relpos] [count]] archive [member...] +ar -M [ <mri-script ] +.Ed +.Pp +The GNU +.Xr ar +program creates, modifies, and extracts from archives. An +.Em 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 +.Em members +of the archive). +.Pp +The original files' contents, mode (permissions), timestamp, owner, and group +are preserved in the archive, and can be restored on extraction. +.Pp +GNU +.Xr ar +can maintain archives whose members have names of any length; however, depending +on how +.Xr 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). +.Pp +.Xr ar +is considered a binary utility because archives of this sort are most often +used as +.Em libraries +holding commonly needed subroutines. +.Pp +.Xr ar +creates an index to the symbols defined in relocatable object modules in the +archive when you specify the modifier +.Li s . +Once created, this index is updated in the archive whenever +.Xr ar +makes a change to its contents (save for the +.Li 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. +.Pp +You may use +.Li nm -s +or +.Li nm --print-armap +to list this index table. If an archive lacks the table, another form of +.Xr ar +called +.Xr ranlib +can be used to add just the table. +.Pp +GNU +.Xr ar +is designed to be compatible with two different facilities. You can control +its activity using command-line options, like the different varieties of +.Xr ar +on Unix systems; or, if you specify the single command-line option +.Op -M , +you can control it with a script supplied via standard input, like the MRI +\(lqlibrarian\(rq program. +.Pp +.Ss Controlling Xr ar on the Command Line +.Bd -literal -offset indent +ar [-X32_64] [-]p[mod [relpos] [count]] archive [member...] +.Ed +.Pp +When you use +.Xr ar +in the Unix style, +.Xr ar +insists on at least two arguments to execute: one keyletter specifying the +.Em operation +(optionally accompanied by other keyletters specifying +.Em modifiers ) , +and the archive name to act on. +.Pp +Most operations can also accept further +.Va member +arguments, specifying particular files to operate on. +.Pp +GNU +.Xr ar +allows you to mix the operation code +.Va p +and modifier flags +.Va mod +in any order, within the first command-line argument. +.Pp +If you wish, you may begin the first command-line argument with a dash. +.Pp +The +.Va p +keyletter specifies what operation to execute; it may be any of the following, +but you must specify only one of them: +.Pp +.Bl -tag -width Ds +.It d +.Em Delete +modules from the archive. Specify the names of modules to be deleted as +.Va member +\&...; the archive is untouched if you specify no files to delete. +.Pp +If you specify the +.Li v +modifier, +.Xr ar +lists each module as it is deleted. +.Pp +.It m +Use this operation to +.Em move +members in an archive. +.Pp +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. +.Pp +If no modifiers are used with +.Li m , +any members you name in the +.Va member +arguments are moved to the +.Em end +of the archive; you can use the +.Li a , +.Li b , +or +.Li i +modifiers to move them to a specified place instead. +.Pp +.It p +.Em Print +the specified members of the archive, to the standard output file. If the +.Li v +modifier is specified, show the member name before copying its contents to +standard output. +.Pp +If you specify no +.Va member +arguments, all the files in the archive are printed. +.Pp +.It q +.Em Quick append ; +Historically, add the files +.Va member +\&...to the end of +.Va archive , +without checking for replacement. +.Pp +The modifiers +.Li a , +.Li b , +and +.Li i +do +.Em not +affect this operation; new members are always placed at the end of the archive. +.Pp +The modifier +.Li v +makes +.Xr ar +list each file as it is appended. +.Pp +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 +.Li ar s +or +.Xr ranlib +explicitly to update the symbol table index. +.Pp +However, too many different systems assume quick append rebuilds the index, +so GNU +.Xr ar +implements +.Li q +as a synonym for +.Li r . +.Pp +.It r +Insert the files +.Va member +\&...into +.Va archive +(with +.Em replacement ) . +This operation differs from +.Li q +in that any previously existing members are deleted if their names match those +being added. +.Pp +If one of the files named in +.Va member +\&...does not exist, +.Xr ar +displays an error message, and leaves undisturbed any existing members of +the archive matching that name. +.Pp +By default, new members are added at the end of the file; but you may use +one of the modifiers +.Li a , +.Li b , +or +.Li i +to request placement relative to some existing member. +.Pp +The modifier +.Li v +used with this operation elicits a line of output for each file inserted, +along with one of the letters +.Li a +or +.Li r +to indicate whether the file was appended (no old member deleted) or replaced. +.Pp +.It t +Display a +.Em table +listing the contents of +.Va archive , +or those of the files listed in +.Va 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 +.Li v +modifier. +.Pp +If you do not specify a +.Va member , +all files in the archive are listed. +.Pp +If there is more than one file with the same name (say, +.Li fie ) +in an archive (say +.Li b.a ) , +.Li ar t b.a fie +lists only the first instance; to see them all, you must ask for a complete +listing---in our example, +.Li ar t b.a . +.Pp +.It x +.Em Extract +members (named +.Va member ) +from the archive. You can use the +.Li v +modifier with this operation, to request that +.Xr ar +list each name as it extracts it. +.Pp +If you do not specify a +.Va member , +all files in the archive are extracted. +.Pp +.El +A number of modifiers ( +.Va mod ) +may immediately follow the +.Va p +keyletter, to specify variations on an operation's behavior: +.Pp +.Bl -tag -width Ds +.It a +Add new files +.Em after +an existing member of the archive. If you use the modifier +.Li a , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. +.Pp +.It b +Add new files +.Em before +an existing member of the archive. If you use the modifier +.Li b , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. (same as +.Li i ) . +.Pp +.It c +.Em Create +the archive. The specified +.Va 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. +.Pp +.It f +Truncate names in the archive. GNU +.Xr ar +will normally permit file names of any length. This will cause it to create +archives which are not compatible with the native +.Xr ar +program on some systems. If this is a concern, the +.Li f +modifier may be used to truncate file names when putting them in the archive. +.Pp +.It i +Insert new files +.Em before +an existing member of the archive. If you use the modifier +.Li i , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. (same as +.Li b ) . +.Pp +.It l +This modifier is accepted but not used. +.Pp +.It N +Uses the +.Va count +parameter. This is used if there are multiple entries in the archive with +the same name. Extract or delete instance +.Va count +of the given name from the archive. +.Pp +.It o +Preserve the +.Em 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. +.Pp +.It P +Use the full path name when matching names in the archive. GNU +.Xr ar +can not create an archive with a full path name (such archives are not POSIX +complaint), but other archive creators can. This option will cause GNU +.Xr ar +to match file names using a complete path name, which can be convenient when +extracting a single file from an archive created by another tool. +.Pp +.It 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 +.Li ar s +on an archive is equivalent to running +.Li ranlib +on it. +.Pp +.It S +Do not generate an archive symbol table. This can speed up building a large +library in several steps. The resulting archive can not be used with the linker. +In order to build a symbol table, you must omit the +.Li S +modifier on the last execution of +.Li ar , +or you must run +.Li ranlib +on the archive. +.Pp +.It u +Normally, +.Li ar r +\&...inserts all files listed into the archive. If you would like to insert +.Em only +those of the files you list that are newer than existing members of the same +names, use this modifier. The +.Li u +modifier is allowed only for the operation +.Li r +(replace). In particular, the combination +.Li qu +is not allowed, since checking the timestamps would lose any speed advantage +from the operation +.Li q . +.Pp +.It v +This modifier requests the +.Em verbose +version of an operation. Many operations display additional information, such +as filenames processed, when the modifier +.Li v +is appended. +.Pp +.It V +This modifier shows the version number of +.Xr ar . +.El +.Pp +.Xr ar +ignores an initial option spelt +.Li -X32_64 , +for compatibility with AIX. The behaviour produced by this option is the default +for GNU +.Xr ar . +.Xr ar +does not support any of the other +.Li -X +options; in particular, it does not support +.Op -X32 +which is the default for AIX +.Xr ar . +.Pp +.Ss Controlling Xr ar with a Script +.Bd -literal -offset indent +ar -M [ <script ] +.Ed +.Pp +If you use the single command-line option +.Li -M +with +.Xr ar , +you can control its operation with a rudimentary command language. This form +of +.Xr ar +operates interactively if standard input is coming directly from a terminal. +During interactive use, +.Xr ar +prompts for input (the prompt is +.Li AR > ) , +and continues executing even after errors. If you redirect standard input +to a script file, no prompts are issued, and +.Xr ar +abandons execution (with a nonzero exit code) on any error. +.Pp +The +.Xr ar +command language is +.Em 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 +.Xr ar +for developers who already have scripts written for the MRI \(lqlibrarian\(rq program. +.Pp +The syntax for the +.Xr ar +command language is straightforward: +.Bl -bullet +.It +commands are recognized in upper or lower case; for example, +.Li LIST +is the same as +.Li list . +In the following descriptions, commands are shown in upper case for clarity. +.Pp +.It +a single command may appear on each line; it is the first word on the line. +.Pp +.It +empty lines are allowed, and have no effect. +.Pp +.It +comments are allowed; text after either of the characters +.Li * +or +.Li ; +is ignored. +.Pp +.It +Whenever you use a list of names as part of the argument to an +.Xr ar +command, you can separate the individual names with either commas or blanks. +Commas are shown in the explanations below, for clarity. +.Pp +.It +.Li + +is used as a line continuation character; if +.Li + +appears at the end of a line, the text on the following line is considered +part of the current command. +.El +.Pp +Here are the commands you can use in +.Xr ar +scripts, or when using +.Xr ar +interactively. Three of them have special significance: +.Pp +.Li OPEN +or +.Li CREATE +specify a +.Em current archive , +which is a temporary file required for most of the other commands. +.Pp +.Li SAVE +commits the changes so far specified by the script. Prior to +.Li SAVE , +commands affect only the temporary copy of the current archive. +.Pp +.Bl -tag -width Ds +.It ADDLIB Va archive +.It ADDLIB Va archive ( Va module, Va module, ... Va module) +Add all the contents of +.Va archive +(or, if specified, each named +.Va module +from +.Va archive ) +to the current archive. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It ADDMOD Va member, Va member, ... Va member +Add each named +.Va member +as a module in the current archive. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It CLEAR +Discard the contents of the current archive, canceling the effect of any operations +since the last +.Li SAVE . +May be executed (with no effect) even if no current archive is specified. +.Pp +.It CREATE Va 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 +.Va archive +until you use +.Li SAVE . +You can overwrite existing archives; similarly, the contents of any existing +file named +.Va archive +will not be destroyed until +.Li SAVE . +.Pp +.It DELETE Va module, Va module, ... Va module +Delete each listed +.Va module +from the current archive; equivalent to +.Li ar -d Va archive Va module ... Va module . +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It DIRECTORY Va archive ( Va module, ... Va module) +.It DIRECTORY Va archive ( Va module, ... Va module) Va outputfile +List each named +.Va module +present in +.Va archive . +The separate command +.Li VERBOSE +specifies the form of the output: when verbose output is off, output is like +that of +.Li ar -t Va archive Va module... . +When verbose output is on, the listing is like +.Li ar -tv Va archive Va module... . +.Pp +Output normally goes to the standard output stream; however, if you specify +.Va outputfile +as a final argument, +.Xr ar +directs the output to that file. +.Pp +.It END +Exit from +.Xr ar , +with a +.Li 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 +.Li SAVE +command, those changes are lost. +.Pp +.It EXTRACT Va module, Va module, ... Va module +Extract each named +.Va module +from the current archive, writing them into the current directory as separate +files. Equivalent to +.Li ar -x Va archive Va module... . +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It LIST +Display full contents of the current archive, in \(lqverbose\(rq style regardless +of the state of +.Li VERBOSE . +The effect is like +.Li ar tv Va archive . +(This single command is a GNU +.Xr ar +enhancement, rather than present for MRI compatibility.) +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It OPEN Va 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 +.Va archive +until you next use +.Li SAVE . +.Pp +.It REPLACE Va module, Va module, ... Va module +In the current archive, replace each existing +.Va module +(named in the +.Li 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. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It VERBOSE +Toggle an internal flag governing the output from +.Li DIRECTORY . +When the flag is on, +.Li DIRECTORY +output matches output from +.Li ar -tv +\&...\&. +.Pp +.It SAVE +Commit your changes to the current archive, and actually save it as a file +with the name specified in the last +.Li CREATE +or +.Li OPEN +command. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.El +.Sh nm +.Bd -literal -offset indent +nm [-a|--debug-syms] [-g|--extern-only] + [-B] [-C|--demangle[=style]] [-D|--dynamic] + [-S|--print-size] [-s|--print-armap] + [-A|-o|--print-file-name][--special-syms] + [-n|-v|--numeric-sort] [-p|--no-sort] + [-r|--reverse-sort] [--size-sort] [-u|--undefined-only] + [-t radix|--radix=radix] [-P|--portability] + [--target=bfdname] [-fformat|--format=format] + [--defined-only] [-l|--line-numbers] [--no-demangle] + [-V|--version] [-X 32_64] [--help] [objfile...] +.Ed +.Pp +GNU +.Xr nm +lists the symbols from object files +.Va objfile +\&...\&. If no object files are listed as arguments, +.Xr nm +assumes the file +.Pa a.out . +.Pp +For each symbol, +.Xr nm +shows: +.Pp +.Bl -bullet +.It +The symbol value, in the radix selected by options (see below), or hexadecimal +by default. +.Pp +.It +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). +.Pp +.Bl -tag -width Ds +.It A +The symbol's value is absolute, and will not be changed by further linking. +.Pp +.It B +The symbol is in the uninitialized data section (known as BSS). +.Pp +.It C +The symbol is common. Common symbols are uninitialized data. When linking, +multiple common symbols may appear with the same name. If the symbol is defined +anywhere, the common symbols are treated as undefined references. For more +details on common symbols, see the discussion of --warn-common in Options,,Linker +options,ld.info,The GNU linker. +.Pp +.It D +The symbol is in the initialized data section. +.Pp +.It G +The symbol is in an initialized data section for small objects. Some object +file formats permit more efficient access to small data objects, such as a +global int variable as opposed to a large global array. +.Pp +.It I +The symbol is an indirect reference to another symbol. This is a GNU extension +to the a.out object file format which is rarely used. +.Pp +.It N +The symbol is a debugging symbol. +.Pp +.It R +The symbol is in a read only data section. +.Pp +.It S +The symbol is in an uninitialized data section for small objects. +.Pp +.It T +The symbol is in the text (code) section. +.Pp +.It U +The symbol is undefined. +.Pp +.It V +The symbol is a weak object. When a weak defined symbol is linked with a normal +defined symbol, the normal defined symbol is used with no error. When a weak +undefined symbol is linked and the symbol is not defined, the value of the +weak symbol becomes zero with no error. +.Pp +.It W +The symbol is a weak symbol that has not been specifically tagged as a weak +object symbol. When a weak defined symbol is linked with a normal defined +symbol, the normal defined symbol is used with no error. When a weak undefined +symbol is linked and the symbol is not defined, the value of the symbol is +determined in a system-specific manner without error. On some systems, uppercase +indicates that a default value has been specified. +.Pp +.It - +The symbol is a stabs symbol in an a.out object file. In this case, the next +values printed are the stabs other field, the stabs desc field, and the stab +type. Stabs symbols are used to hold debugging information. For more information, +see Top,Stabs,Stabs Overview,stabs.info, The \(lqstabs\(rq debug format. +.Pp +.It ? +The symbol type is unknown, or object file format specific. +.El +.Pp +.It +The symbol name. +.El +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +.Pp +.Bl -tag -width Ds +.It -A +.It -o +.It --print-file-name +Precede each symbol by the name of the input file (or archive member) in which +it was found, rather than identifying the input file once only, before all +of its symbols. +.Pp +.It -a +.It --debug-syms +Display all symbols, even debugger-only symbols; normally these are not listed. +.Pp +.It -B +The same as +.Op --format=bsd +(for compatibility with the MIPS +.Xr nm ) . +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It --no-demangle +Do not demangle low-level symbol names. This is the default. +.Pp +.It -D +.It --dynamic +Display the dynamic symbols rather than the normal symbols. This is only meaningful +for dynamic objects, such as certain types of shared libraries. +.Pp +.It -f Va format +.It --format= Va format +Use the output format +.Va format , +which can be +.Li bsd , +.Li sysv , +or +.Li posix . +The default is +.Li bsd . +Only the first character of +.Va format +is significant; it can be either upper or lower case. +.Pp +.It -g +.It --extern-only +Display only external symbols. +.Pp +.It -l +.It --line-numbers +For each symbol, use debugging information to try to find a filename and line +number. For a defined symbol, look for the line number of the address of the +symbol. For an undefined symbol, look for the line number of a relocation +entry which refers to the symbol. If line number information can be found, +print it after the other symbol information. +.Pp +.It -n +.It -v +.It --numeric-sort +Sort symbols numerically by their addresses, rather than alphabetically by +their names. +.Pp +.It -p +.It --no-sort +Do not bother to sort the symbols in any order; print them in the order encountered. +.Pp +.It -P +.It --portability +Use the POSIX.2 standard output format instead of the default format. Equivalent +to +.Li -f posix . +.Pp +.It -S +.It --print-size +Print size, not the value, of defined symbols for the +.Li bsd +output format. +.Pp +.It -s +.It --print-armap +When listing symbols from archive members, include the index: a mapping (stored +in the archive by +.Xr ar +or +.Xr ranlib ) +of which modules contain definitions for which names. +.Pp +.It -r +.It --reverse-sort +Reverse the order of the sort (whether numeric or alphabetic); let the last +come first. +.Pp +.It --size-sort +Sort symbols by size. The size is computed as the difference between the value +of the symbol and the value of the symbol with the next higher value. If the +.Li bsd +output format is used the size of the symbol is printed, rather than the value, +and +.Li -S +must be used in order both size and value to be printed. +.Pp +.It --special-syms +Display symbols which have a target-specific special meaning. These symbols +are usually used by the target for some special processing and are not normally +helpful when included included in the normal symbol lists. For example for +ARM targets this option would skip the mapping symbols used to mark transitions +between ARM code, THUMB code and data. +.Pp +.It -t Va radix +.It --radix= Va radix +Use +.Va radix +as the radix for printing the symbol values. It must be +.Li d +for decimal, +.Li o +for octal, or +.Li x +for hexadecimal. +.Pp +.It --target= Va bfdname +Specify an object code format other than your system's default format.See Section +.Dq Target Selection , +for more information. +.Pp +.It -u +.It --undefined-only +Display only undefined symbols (those external to each object file). +.Pp +.It --defined-only +Display only defined symbols for each object file. +.Pp +.It -V +.It --version +Show the version number of +.Xr nm +and exit. +.Pp +.It -X +This option is ignored for compatibility with the AIX version of +.Xr nm . +It takes one parameter which must be the string +.Op 32_64 . +The default mode of AIX +.Xr nm +corresponds to +.Op -X 32 , +which is not supported by GNU +.Xr nm . +.Pp +.It --help +Show a summary of the options to +.Xr nm +and exit. +.El +.Pp +.Sh objcopy +.Bd -literal -offset indent +objcopy [-F bfdname|--target=bfdname] + [-I bfdname|--input-target=bfdname] + [-O bfdname|--output-target=bfdname] + [-B bfdarch|--binary-architecture=bfdarch] + [-S|--strip-all] + [-g|--strip-debug] + [-K symbolname|--keep-symbol=symbolname] + [-N symbolname|--strip-symbol=symbolname] + [--strip-unneeded-symbol=symbolname] + [-G symbolname|--keep-global-symbol=symbolname] + [--localize-hidden] + [-L symbolname|--localize-symbol=symbolname] + [--globalize-symbol=symbolname] + [-W symbolname|--weaken-symbol=symbolname] + [-w|--wildcard] + [-x|--discard-all] + [-X|--discard-locals] + [-b byte|--byte=byte] + [-i interleave|--interleave=interleave] + [-j sectionname|--only-section=sectionname] + [-R sectionname|--remove-section=sectionname] + [-p|--preserve-dates] + [--debugging] + [--gap-fill=val] + [--pad-to=address] + [--set-start=val] + [--adjust-start=incr] + [--change-addresses=incr] + [--change-section-address section{=,+,-}val] + [--change-section-lma section{=,+,-}val] + [--change-section-vma section{=,+,-}val] + [--change-warnings] [--no-change-warnings] + [--set-section-flags section=flags] + [--add-section sectionname=filename] + [--rename-section oldname=newname[,flags]] + [--change-leading-char] [--remove-leading-char] + [--reverse-bytes=num] + [--srec-len=ival] [--srec-forceS3] + [--redefine-sym old=new] + [--redefine-syms=filename] + [--weaken] + [--keep-symbols=filename] + [--strip-symbols=filename] + [--strip-unneeded-symbols=filename] + [--keep-global-symbols=filename] + [--localize-symbols=filename] + [--globalize-symbols=filename] + [--weaken-symbols=filename] + [--alt-machine-code=index] + [--prefix-symbols=string] + [--prefix-sections=string] + [--prefix-alloc-sections=string] + [--add-GNU-debuglink=path-to-file] + [--keep-file-symbols] + [--only-keep-debug] + [--extract-symbol] + [--writable-text] + [--readonly-text] + [--pure] + [--impure] + [-v|--verbose] + [-V|--version] + [--help] [--info] + infile [outfile] +.Ed +.Pp +The GNU +.Xr objcopy +utility copies the contents of an object file to another. +.Xr 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 +.Xr objcopy +is controlled by command-line options. Note that +.Xr objcopy +should be able to copy a fully linked file between any two formats. However, +copying a relocatable object file between any two formats may not work as +expected. +.Pp +.Xr objcopy +creates temporary files to do its translations and deletes them afterward. +.Xr objcopy +uses bfd to do all its translation work; it has access to all the formats +described in bfd and thus is able to recognize most formats without being +told explicitly.See Section +.Dq BFD . +.Pp +.Xr objcopy +can be used to generate S-records by using an output target of +.Li srec +(e.g., use +.Li -O srec ) . +.Pp +.Xr objcopy +can be used to generate a raw binary file by using an output target of +.Li binary +(e.g., use +.Op -O binary ) . +When +.Xr objcopy +generates a raw binary file, it will essentially produce a memory dump of +the contents of the input object file. All symbols and relocation information +will be discarded. The memory dump will start at the load address of the lowest +section copied into the output file. +.Pp +When generating an S-record or a raw binary file, it may be helpful to use +.Op -S +to remove sections containing debugging information. In some cases +.Op -R +will be useful to remove sections which contain information that is not needed +by the binary file. +.Pp +Note--- +.Xr objcopy +is not able to change the endianness of its input files. If the input format +has an endianness (some formats do not), +.Xr objcopy +can only copy the inputs into file formats that have the same endianness or +which have no endianness (e.g., +.Li srec ) . +(However, see the +.Op --reverse-bytes +option.) +.Pp +.Bl -tag -width Ds +.It Va infile +.It Va outfile +The input and output files, respectively. If you do not specify +.Va outfile , +.Xr objcopy +creates a temporary file and destructively renames the result with the name +of +.Va infile . +.Pp +.It -I Va bfdname +.It --input-target= Va bfdname +Consider the source file's object format to be +.Va bfdname , +rather than attempting to deduce it.See Section +.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Write the output file using the object format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -F Va bfdname +.It --target= Va bfdname +Use +.Va bfdname +as the object format for both the input and the output file; i.e., simply +transfer data from source to destination with no translation.See Section +.Dq Target Selection , +for more information. +.Pp +.It -B Va bfdarch +.It --binary-architecture= Va bfdarch +Useful when transforming a raw binary input file into an object file. In this +case the output architecture can be set to +.Va bfdarch . +This option will be ignored if the input file has a known +.Va bfdarch . +You can access this binary data inside a program by referencing the special +symbols that are created by the conversion process. These symbols are called +_binary_ +.Va objfile +_start, _binary_ +.Va objfile +_end and _binary_ +.Va objfile +_size. e.g. you can transform a picture file into an object file and then +access it in your code using these symbols. +.Pp +.It -j Va sectionname +.It --only-section= Va sectionname +Copy only the named section from the input file to the output file. This option +may be given more than once. Note that using this option inappropriately may +make the output file unusable. +.Pp +.It -R Va sectionname +.It --remove-section= Va sectionname +Remove any section named +.Va sectionname +from the output file. This option may be given more than once. Note that using +this option inappropriately may make the output file unusable. +.Pp +.It -S +.It --strip-all +Do not copy relocation and symbol information from the source file. +.Pp +.It -g +.It --strip-debug +Do not copy debugging symbols or sections from the source file. +.Pp +.It --strip-unneeded +Strip all symbols that are not needed for relocation processing. +.Pp +.It -K Va symbolname +.It --keep-symbol= Va symbolname +When stripping symbols, keep symbol +.Va symbolname +even if it would normally be stripped. This option may be given more than +once. +.Pp +.It -N Va symbolname +.It --strip-symbol= Va symbolname +Do not copy symbol +.Va symbolname +from the source file. This option may be given more than once. +.Pp +.It --strip-unneeded-symbol= Va symbolname +Do not copy symbol +.Va symbolname +from the source file unless it is needed by a relocation. This option may +be given more than once. +.Pp +.It -G Va symbolname +.It --keep-global-symbol= Va symbolname +Keep only symbol +.Va symbolname +global. Make all other symbols local to the file, so that they are not visible +externally. This option may be given more than once. +.Pp +.It --localize-hidden +In an ELF object, mark all symbols that have hidden or internal visibility +as local. This option applies on top of symbol-specific localization options +such as +.Op -L . +.Pp +.It -L Va symbolname +.It --localize-symbol= Va symbolname +Make symbol +.Va symbolname +local to the file, so that it is not visible externally. This option may be +given more than once. +.Pp +.It -W Va symbolname +.It --weaken-symbol= Va symbolname +Make symbol +.Va symbolname +weak. This option may be given more than once. +.Pp +.It --globalize-symbol= Va symbolname +Give symbol +.Va symbolname +global scoping so that it is visible outside of the file in which it is defined. +This option may be given more than once. +.Pp +.It -w +.It --wildcard +Permit regular expressions in +.Va symbolname +s used in other command line options. The question mark (?), asterisk (*), +backslash (\e) and square brackets ([]) operators can be used anywhere in the +symbol name. If the first character of the symbol name is the exclamation +point (!) then the sense of the switch is reversed for that symbol. For example: +.Pp +.Bd -literal -offset indent + -w -W !foo -W fo* +.Ed +.Pp +would cause objcopy to weaken all symbols that start with \(lqfo\(rq except for the +symbol \(lqfoo\(rq. +.Pp +.It -x +.It --discard-all +Do not copy non-global symbols from the source file. +.Pp +.It -X +.It --discard-locals +Do not copy compiler-generated local symbols. (These usually start with +.Li L +or +.Li . . ) +.Pp +.It -b Va byte +.It --byte= Va byte +Keep only every +.Va byte +th byte of the input file (header data is not affected). +.Va byte +can be in the range from 0 to +.Va interleave +-1, where +.Va interleave +is given by the +.Op -i +or +.Op --interleave +option, or the default of 4. This option is useful for creating files to program +rom. It is typically used with an +.Li srec +output target. +.Pp +.It -i Va interleave +.It --interleave= Va interleave +Only copy one out of every +.Va interleave +bytes. Select which byte to copy with the +.Op -b +or +.Op --byte +option. The default is 4. +.Xr objcopy +ignores this option if you do not specify either +.Op -b +or +.Op --byte . +.Pp +.It -p +.It --preserve-dates +Set the access and modification dates of the output file to be the same as +those of the input file. +.Pp +.It --debugging +Convert debugging information, if possible. This is not the default because +only certain debugging formats are supported, and the conversion process can +be time consuming. +.Pp +.It --gap-fill Va val +Fill gaps between sections with +.Va val . +This operation applies to the +.Em load address +(LMA) of the sections. It is done by increasing the size of the section with +the lower address, and filling in the extra space created with +.Va val . +.Pp +.It --pad-to Va address +Pad the output file up to the load address +.Va address . +This is done by increasing the size of the last section. The extra space is +filled in with the value specified by +.Op --gap-fill +(default zero). +.Pp +.It --set-start Va val +Set the start address of the new file to +.Va val . +Not all object file formats support setting the start address. +.Pp +.It --change-start Va incr +.It --adjust-start Va incr +Change the start address by adding +.Va incr . +Not all object file formats support setting the start address. +.Pp +.It --change-addresses Va incr +.It --adjust-vma Va incr +Change the VMA and LMA addresses of all sections, as well as the start address, +by adding +.Va incr . +Some object file formats do not permit section addresses to be changed arbitrarily. +Note that this does not relocate the sections; if the program expects sections +to be loaded at a certain address, and this option is used to change the sections +such that they are loaded at a different address, the program may fail. +.Pp +.It --change-section-address Va section{=,+,-} Va val +.It --adjust-section-vma Va section{=,+,-} Va val +Set or change both the VMA address and the LMA address of the named +.Va section . +If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-section-lma Va section{=,+,-} Va val +Set or change the LMA address of the named +.Va section . +The LMA address is the address where the section will be loaded into memory +at program load time. Normally this is the same as the VMA address, which +is the address of the section at program run time, but on some systems, especially +those where a program is held in ROM, the two can be different. If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-section-vma Va section{=,+,-} Va val +Set or change the VMA address of the named +.Va section . +The VMA address is the address where the section will be located once the +program has started executing. Normally this is the same as the LMA address, +which is the address where the section will be loaded into memory, but on +some systems, especially those where a program is held in ROM, the two can +be different. If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-warnings +.It --adjust-warnings +If +.Op --change-section-address +or +.Op --change-section-lma +or +.Op --change-section-vma +is used, and the named section does not exist, issue a warning. This is the +default. +.Pp +.It --no-change-warnings +.It --no-adjust-warnings +Do not issue a warning if +.Op --change-section-address +or +.Op --adjust-section-lma +or +.Op --adjust-section-vma +is used, even if the named section does not exist. +.Pp +.It --set-section-flags Va section= Va flags +Set the flags for the named section. The +.Va flags +argument is a comma separated string of flag names. The recognized names are +.Li alloc , +.Li contents , +.Li load , +.Li noload , +.Li readonly , +.Li code , +.Li data , +.Li rom , +.Li share , +and +.Li debug . +You can set the +.Li contents +flag for a section which does not have contents, but it is not meaningful +to clear the +.Li contents +flag of a section which does have contents--just remove the section instead. +Not all flags are meaningful for all object file formats. +.Pp +.It --add-section Va sectionname= Va filename +Add a new section named +.Va sectionname +while copying the file. The contents of the new section are taken from the +file +.Va filename . +The size of the section will be the size of the file. This option only works +on file formats which can support sections with arbitrary names. +.Pp +.It --rename-section Va oldname= Va newname[, Va flags] +Rename a section from +.Va oldname +to +.Va newname , +optionally changing the section's flags to +.Va flags +in the process. This has the advantage over usng a linker script to perform +the rename in that the output stays as an object file and does not become +a linked executable. +.Pp +This option is particularly helpful when the input format is binary, since +this will always create a section called .data. If for example, you wanted +instead to create a section called .rodata containing binary data you could +use the following command line to achieve it: +.Pp +.Bd -literal -offset indent + objcopy -I binary -O <output_format> -B <architecture> \e + --rename-section .data=.rodata,alloc,load,readonly,data,contents \e + <input_binary_file> <output_object_file> +.Ed +.Pp +.It --change-leading-char +Some object file formats use special characters at the start of symbols. The +most common such character is underscore, which compilers often add before +every symbol. This option tells +.Xr objcopy +to change the leading character of every symbol when it converts between object +file formats. If the object file formats use the same leading character, this +option has no effect. Otherwise, it will add a character, or remove a character, +or change a character, as appropriate. +.Pp +.It --remove-leading-char +If the first character of a global symbol is a special symbol leading character +used by the object file format, remove the character. The most common symbol +leading character is underscore. This option will remove a leading underscore +from all global symbols. This can be useful if you want to link together objects +of different file formats with different conventions for symbol names. This +is different from +.Op --change-leading-char +because it always changes the symbol name when appropriate, regardless of +the object file format of the output file. +.Pp +.It --reverse-bytes= Va num +Reverse the bytes in a section with output contents. A section length must +be evenly divisible by the value given in order for the swap to be able to +take place. Reversing takes place before the interleaving is performed. +.Pp +This option is used typically in generating ROM images for problematic target +systems. For example, on some target boards, the 32-bit words fetched from +8-bit ROMs are re-assembled in little-endian byte order regardless of the +CPU byte order. Depending on the programming model, the endianness of the +ROM may need to be modified. +.Pp +Consider a simple file with a section containing the following eight bytes: +.Li 12345678 . +.Pp +Using +.Li --reverse-bytes=2 +for the above example, the bytes in the output file would be ordered +.Li 21436587 . +.Pp +Using +.Li --reverse-bytes=4 +for the above example, the bytes in the output file would be ordered +.Li 43218765 . +.Pp +By using +.Li --reverse-bytes=2 +for the above example, followed by +.Li --reverse-bytes=4 +on the output file, the bytes in the second output file would be ordered +.Li 34127856 . +.Pp +.It --srec-len= Va ival +Meaningful only for srec output. Set the maximum length of the Srecords being +produced to +.Va ival . +This length covers both address, data and crc fields. +.Pp +.It --srec-forceS3 +Meaningful only for srec output. Avoid generation of S1/S2 records, creating +S3-only record format. +.Pp +.It --redefine-sym Va old= Va new +Change the name of a symbol +.Va old , +to +.Va new . +This can be useful when one is trying link two things together for which you +have no source, and there are name collisions. +.Pp +.It --redefine-syms= Va filename +Apply +.Op --redefine-sym +to each symbol pair " +.Va old +.Va new " +listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol pair per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --weaken +Change all global symbols in the file to be weak. This can be useful when +building an object which will be linked against other objects using the +.Op -R +option to the linker. This option is only effective when using an object file +format which supports weak symbols. +.Pp +.It --keep-symbols= Va filename +Apply +.Op --keep-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --strip-symbols= Va filename +Apply +.Op --strip-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --strip-unneeded-symbols= Va filename +Apply +.Op --strip-unneeded-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --keep-global-symbols= Va filename +Apply +.Op --keep-global-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --localize-symbols= Va filename +Apply +.Op --localize-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --globalize-symbols= Va filename +Apply +.Op --globalize-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --weaken-symbols= Va filename +Apply +.Op --weaken-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --alt-machine-code= Va index +If the output architecture has alternate machine codes, use the +.Va index +th code instead of the default one. This is useful in case a machine is assigned +an official code and the tool-chain adopts the new code, but other applications +still depend on the original code being used. For ELF based architectures +if the +.Va index +alternative does not exist then the value is treated as an absolute number +to be stored in the e_machine field of the ELF header. +.Pp +.It --writable-text +Mark the output text as writable. This option isn't meaningful for all object +file formats. +.Pp +.It --readonly-text +Make the output text write protected. This option isn't meaningful for all +object file formats. +.Pp +.It --pure +Mark the output file as demand paged. This option isn't meaningful for all +object file formats. +.Pp +.It --impure +Mark the output file as impure. This option isn't meaningful for all object +file formats. +.Pp +.It --prefix-symbols= Va string +Prefix all symbols in the output file with +.Va string . +.Pp +.It --prefix-sections= Va string +Prefix all section names in the output file with +.Va string . +.Pp +.It --prefix-alloc-sections= Va string +Prefix all the names of all allocated sections in the output file with +.Va string . +.Pp +.It --add-GNU-debuglink= Va path-to-file +Creates a .GNU_debuglink section which contains a reference to +.Va path-to-file +and adds it to the output file. +.Pp +.It --keep-file-symbols +When stripping a file, perhaps with +.Op --strip-debug +or +.Op --strip-unneeded , +retain any symbols specifying source file names, which would otherwise get +stripped. +.Pp +.It --only-keep-debug +Strip a file, removing contents of any sections that would not be stripped +by +.Op --strip-debug +and leaving the debugging sections intact. In ELF files, this preserves all +note sections in the output. +.Pp +The intention is that this option will be used in conjunction with +.Op --add-GNU-debuglink +to create a two part executable. One a stripped binary which will occupy less +space in RAM and in a distribution and the second a debugging information +file which is only needed if debugging abilities are required. The suggested +procedure to create these files is as follows: +.Pp +.Bl -enum +.It +Link the executable as normal. Assuming that is is called +.Li foo +then... +.It +Run +.Li objcopy --only-keep-debug foo foo.dbg +to +create a file containing the debugging info. +.It +Run +.Li objcopy --strip-debug foo +to create a +stripped executable. +.It +Run +.Li objcopy --add-GNU-debuglink=foo.dbg foo +to add a link to the debugging info into the stripped executable. +.El +.Pp +Note - the choice of +.Li .dbg +as an extension for the debug info file is arbitrary. Also the +.Li --only-keep-debug +step is optional. You could instead do this: +.Pp +.Bl -enum +.It +Link the executable as normal. +.It +Copy +.Li foo +to +.Li foo.full +.It +Run +.Li objcopy --strip-debug foo +.It +Run +.Li objcopy --add-GNU-debuglink=foo.full foo +.El +.Pp +i.e., the file pointed to by the +.Op --add-GNU-debuglink +can be the full executable. It does not have to be a file created by the +.Op --only-keep-debug +switch. +.Pp +Note - this switch is only intended for use on fully linked files. It does +not make sense to use it on object files where the debugging information may +be incomplete. Besides the GNU_debuglink feature currently only supports the +presence of one filename containing debugging information, not multiple filenames +on a one-per-object-file basis. +.Pp +.It --extract-symbol +Keep the file's section flags and symbols but remove all section data. Specifically, +the option: +.Pp +.Bl -bullet +.It +sets the virtual and load addresses of every section to zero; +.It +removes the contents of all sections; +.It +sets the size of every section to zero; and +.It +sets the file's start address to zero. +.El +.Pp +This option is used to build a +.Pa .sym +file for a VxWorks kernel. It can also be a useful way of reducing the size +of a +.Op --just-symbols +linker input file. +.Pp +.It -V +.It --version +Show the version number of +.Xr objcopy . +.Pp +.It -v +.It --verbose +Verbose output: list all object files modified. In the case of archives, +.Li objcopy -V +lists all members of the archive. +.Pp +.It --help +Show a summary of the options to +.Xr objcopy . +.Pp +.It --info +Display a list showing all architectures and object formats available. +.El +.Pp +.Sh objdump +.Bd -literal -offset indent +objdump [-a|--archive-headers] + [-b bfdname|--target=bfdname] + [-C|--demangle[=style] ] + [-d|--disassemble] + [-D|--disassemble-all] + [-z|--disassemble-zeroes] + [-EB|-EL|--endian={big | little }] + [-f|--file-headers] + [--file-start-context] + [-g|--debugging] + [-e|--debugging-tags] + [-h|--section-headers|--headers] + [-i|--info] + [-j section|--section=section] + [-l|--line-numbers] + [-S|--source] + [-m machine|--architecture=machine] + [-M options|--disassembler-options=options] + [-p|--private-headers] + [-r|--reloc] + [-R|--dynamic-reloc] + [-s|--full-contents] + [-W|--dwarf] + [-G|--stabs] + [-t|--syms] + [-T|--dynamic-syms] + [-x|--all-headers] + [-w|--wide] + [--start-address=address] + [--stop-address=address] + [--prefix-addresses] + [--[no-]show-raw-insn] + [--adjust-vma=offset] + [--special-syms] + [-V|--version] + [-H|--help] + objfile... +.Ed +.Pp +.Xr 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. +.Pp +.Va objfile +\&...are the object files to be examined. When you specify archives, +.Xr objdump +shows information on each of the member object files. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +At least one option from the list +.Op -a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x +must be given. +.Pp +.Bl -tag -width Ds +.It -a +.It --archive-header +If any of the +.Va objfile +files are archives, display the archive header information (in a format similar +to +.Li ls -l ) . +Besides the information you could list with +.Li ar tv , +.Li objdump -a +shows the object file format of each archive member. +.Pp +.It --adjust-vma= Va offset +When dumping information, first add +.Va offset +to all the section addresses. This is useful if the section addresses do not +correspond to the symbol table, which can happen when putting sections at +particular addresses when using a format which can not represent section addresses, +such as a.out. +.Pp +.It -b Va bfdname +.It --target= Va bfdname +Specify that the object-code format for the object files is +.Va bfdname . +This option may not be necessary; +.Va objdump +can automatically recognize many formats. +.Pp +For example, +.Bd -literal -offset indent +objdump -b oasys -m vax -h fu.o +.Ed +displays summary information from the section headers ( +.Op -h ) +of +.Pa fu.o , +which is explicitly identified ( +.Op -m ) +as a VAX object file in the format produced by Oasys compilers. You can list +the formats available with the +.Op -i +option.See Section +.Dq Target Selection , +for more information. +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It -g +.It --debugging +Display debugging information. This attempts to parse debugging information +stored in the file and print it out using a C like syntax. Only certain types +of debugging information have been implemented. Some other types are supported +by +.Xr readelf -w . +See Section.Dq readelf . +.Pp +.It -e +.It --debugging-tags +Like +.Op -g , +but the information is generated in a format compatible with ctags tool. +.Pp +.It -d +.It --disassemble +Display the assembler mnemonics for the machine instructions from +.Va objfile . +This option only disassembles those sections which are expected to contain +instructions. +.Pp +.It -D +.It --disassemble-all +Like +.Op -d , +but disassemble the contents of all sections, not just those expected to contain +instructions. +.Pp +.It --prefix-addresses +When disassembling, print the complete address on each line. This is the older +disassembly format. +.Pp +.It -EB +.It -EL +.It --endian={big|little} +Specify the endianness of the object files. This only affects disassembly. +This can be useful when disassembling a file format which does not describe +endianness information, such as S-records. +.Pp +.It -f +.It --file-headers +Display summary information from the overall header of each of the +.Va objfile +files. +.Pp +.It --file-start-context +Specify that when displaying interlisted source code/disassembly (assumes +.Op -S ) +from a file that has not yet been displayed, extend the context to the start +of the file. +.Pp +.It -h +.It --section-headers +.It --headers +Display summary information from the section headers of the object file. +.Pp +File segments may be relocated to nonstandard addresses, for example by using +the +.Op -Ttext , +.Op -Tdata , +or +.Op -Tbss +options to +.Xr ld . +However, some object file formats, such as a.out, do not store the starting +address of the file segments. In those situations, although +.Xr ld +relocates the sections correctly, using +.Li objdump -h +to list the file section headers cannot show the correct addresses. Instead, +it shows the usual addresses, which are implicit for the target. +.Pp +.It -H +.It --help +Print a summary of the options to +.Xr objdump +and exit. +.Pp +.It -i +.It --info +Display a list showing all architectures and object formats available for +specification with +.Op -b +or +.Op -m . +.Pp +.It -j Va name +.It --section= Va name +Display information only for section +.Va name . +.Pp +.It -l +.It --line-numbers +Label the display (using debugging information) with the filename and source +line numbers corresponding to the object code or relocs shown. Only useful +with +.Op -d , +.Op -D , +or +.Op -r . +.Pp +.It -m Va machine +.It --architecture= Va machine +Specify the architecture to use when disassembling object files. This can +be useful when disassembling object files which do not describe architecture +information, such as S-records. You can list the available architectures with +the +.Op -i +option. +.Pp +.It -M Va options +.It --disassembler-options= Va options +Pass target specific information to the disassembler. Only supported on some +targets. If it is necessary to specify more than one disassembler option then +multiple +.Op -M +options can be used or can be placed together into a comma separated list. +.Pp +If the target is an ARM architecture then this switch can be used to select +which register name set is used during disassembler. Specifying +.Op -M reg-names-std +(the default) will select the register names as used in ARM's instruction +set documentation, but with register 13 called 'sp', register 14 called 'lr' +and register 15 called 'pc'. Specifying +.Op -M reg-names-apcs +will select the name set used by the ARM Procedure Call Standard, whilst specifying +.Op -M reg-names-raw +will just use +.Li r +followed by the register number. +.Pp +There are also two variants on the APCS register naming scheme enabled by +.Op -M reg-names-atpcs +and +.Op -M reg-names-special-atpcs +which use the ARM/Thumb Procedure Call Standard naming conventions. (Either +with the normal register names or the special register names). +.Pp +This option can also be used for ARM architectures to force the disassembler +to interpret all instructions as Thumb instructions by using the switch +.Op --disassembler-options=force-thumb . +This can be useful when attempting to disassemble thumb code produced by other +compilers. +.Pp +For the x86, some of the options duplicate functions of the +.Op -m +switch, but allow finer grained control. Multiple selections from the following +may be specified as a comma separated string. +.Op x86-64 , +.Op i386 +and +.Op i8086 +select disassembly for the given architecture. +.Op intel +and +.Op att +select between intel syntax mode and AT&T syntax mode. +.Op addr64 , +.Op addr32 , +.Op addr16 , +.Op data32 +and +.Op data16 +specify the default address size and operand size. These four options will +be overridden if +.Op x86-64 , +.Op i386 +or +.Op i8086 +appear later in the option string. Lastly, +.Op suffix , +when in AT&T mode, instructs the disassembler to print a mnemonic suffix even +when the suffix could be inferred by the operands. +.Pp +For PPC, +.Op booke , +.Op booke32 +and +.Op booke64 +select disassembly of BookE instructions. +.Op 32 +and +.Op 64 +select PowerPC and PowerPC64 disassembly, respectively. +.Op e300 +selects disassembly for the e300 family. +.Op 440 +selects disassembly for the PowerPC 440. +.Pp +For MIPS, this option controls the printing of instruction mnemonic names +and register names in disassembled instructions. Multiple selections from +the following may be specified as a comma separated string, and invalid options +are ignored: +.Pp +.Bl -tag -width Ds +.It no-aliases +Print the 'raw' instruction mnemonic instead of some pseudo instruction mnemonic. +I.e., print 'daddu' or 'or' instead of 'move', 'sll' instead of 'nop', etc. +.Pp +.It gpr-names= Va ABI +Print GPR (general-purpose register) names as appropriate for the specified +ABI. By default, GPR names are selected according to the ABI of the binary +being disassembled. +.Pp +.It fpr-names= Va ABI +Print FPR (floating-point register) names as appropriate for the specified +ABI. By default, FPR numbers are printed rather than names. +.Pp +.It cp0-names= Va ARCH +Print CP0 (system control coprocessor; coprocessor 0) register names as appropriate +for the CPU or architecture specified by +.Va ARCH . +By default, CP0 register names are selected according to the architecture +and CPU of the binary being disassembled. +.Pp +.It hwr-names= Va ARCH +Print HWR (hardware register, used by the +.Li rdhwr +instruction) names as appropriate for the CPU or architecture specified by +.Va ARCH . +By default, HWR names are selected according to the architecture and CPU of +the binary being disassembled. +.Pp +.It reg-names= Va ABI +Print GPR and FPR names as appropriate for the selected ABI. +.Pp +.It reg-names= Va ARCH +Print CPU-specific register names (CP0 register and HWR names) as appropriate +for the selected CPU or architecture. +.El +.Pp +For any of the options listed above, +.Va ABI +or +.Va ARCH +may be specified as +.Li numeric +to have numbers printed rather than names, for the selected types of registers. +You can list the available values of +.Va ABI +and +.Va ARCH +using the +.Op --help +option. +.Pp +For VAX, you can specify function entry addresses with +.Op -M entry:0xf00ba . +You can use this multiple times to properly disassemble VAX binary files that +don't contain symbol tables (like ROM dumps). In these cases, the function +entry mask would otherwise be decoded as VAX instructions, which would probably +lead the rest of the function being wrongly disassembled. +.Pp +.It -p +.It --private-headers +Print information that is specific to the object file format. The exact information +printed depends upon the object file format. For some object file formats, +no additional information is printed. +.Pp +.It -r +.It --reloc +Print the relocation entries of the file. If used with +.Op -d +or +.Op -D , +the relocations are printed interspersed with the disassembly. +.Pp +.It -R +.It --dynamic-reloc +Print the dynamic relocation entries of the file. This is only meaningful +for dynamic objects, such as certain types of shared libraries. +.Pp +.It -s +.It --full-contents +Display the full contents of any sections requested. By default all non-empty +sections are displayed. +.Pp +.It -S +.It --source +Display source code intermixed with disassembly, if possible. Implies +.Op -d . +.Pp +.It --show-raw-insn +When disassembling instructions, print the instruction in hex as well as in +symbolic form. This is the default except when +.Op --prefix-addresses +is used. +.Pp +.It --no-show-raw-insn +When disassembling instructions, do not print the instruction bytes. This +is the default when +.Op --prefix-addresses +is used. +.Pp +.It -W +.It --dwarf +Displays the contents of the DWARF debug sections in the file, if any are +present. +.Pp +.It -G +.It --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 +.Li .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 +.Op --syms +output. For more information on stabs symbols, see Top,Stabs,Stabs Overview,stabs.info, +The \(lqstabs\(rq debug format. +.Pp +.It --start-address= Va address +Start displaying data at the specified address. This affects the output of +the +.Op -d , +.Op -r +and +.Op -s +options. +.Pp +.It --stop-address= Va address +Stop displaying data at the specified address. This affects the output of +the +.Op -d , +.Op -r +and +.Op -s +options. +.Pp +.It -t +.It --syms +Print the symbol table entries of the file. This is similar to the information +provided by the +.Li nm +program. +.Pp +.It -T +.It --dynamic-syms +Print the dynamic symbol table entries of the file. This is only meaningful +for dynamic objects, such as certain types of shared libraries. This is similar +to the information provided by the +.Li nm +program when given the +.Op -D +( +.Op --dynamic ) +option. +.Pp +.It --special-syms +When displaying symbols include those which the target considers to be special +in some way and which would not normally be of interest to the user. +.Pp +.It -V +.It --version +Print the version number of +.Xr objdump +and exit. +.Pp +.It -x +.It --all-headers +Display all available header information, including the symbol table and relocation +entries. Using +.Op -x +is equivalent to specifying all of +.Op -a -f -h -p -r -t . +.Pp +.It -w +.It --wide +Format some lines for output devices that have more than 80 columns. Also +do not truncate symbol names when they are displayed. +.Pp +.It -z +.It --disassemble-zeroes +Normally the disassembly output will skip blocks of zeroes. This option directs +the disassembler to disassemble those blocks, just like any other data. +.El +.Pp +.Sh ranlib +.Bd -literal -offset indent +ranlib [-vV] archive +.Ed +.Pp +.Xr 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. +.Pp +You may use +.Li nm -s +or +.Li nm --print-armap +to list this index. +.Pp +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. +.Pp +The GNU +.Xr ranlib +program is another form of GNU +.Xr ar ; +running +.Xr ranlib +is completely equivalent to executing +.Li ar -s . +See Section.Dq ar . +.Pp +.Bl -tag -width Ds +.It -v +.It -V +.It --version +Show the version number of +.Xr ranlib . +.El +.Pp +.Sh size +.Bd -literal -offset indent +size [-A|-B|--format=compatibility] + [--help] + [-d|-o|-x|--radix=number] + [-t|--totals] + [--target=bfdname] [-V|--version] + [objfile...] +.Ed +.Pp +The GNU +.Xr size +utility lists the section sizes---and the total size---for each of the object +or archive files +.Va objfile +in its argument list. By default, one line of output is generated for each +object file or each module in an archive. +.Pp +.Va objfile +\&...are the object files to be examined. If none are specified, the file +.Li a.out +will be used. +.Pp +The command line options have the following meanings: +.Pp +.Bl -tag -width Ds +.It -A +.It -B +.It --format= Va compatibility +Using one of these options, you can choose whether the output from GNU +.Xr size +resembles output from System V +.Xr size +(using +.Op -A , +or +.Op --format=sysv ) , +or Berkeley +.Xr size +(using +.Op -B , +or +.Op --format=berkeley ) . +The default is the one-line format similar to Berkeley's. +.Pp +Here is an example of the Berkeley (default) format of output from +.Xr size : +.Bd -literal -offset indent +$ size --format=Berkeley ranlib size +text data bss dec hex filename +294880 81920 11592 388392 5ed28 ranlib +294880 81920 11888 388688 5ee50 size +.Ed +.Pp +This is the same data, but displayed closer to System V conventions: +.Pp +.Bd -literal -offset indent +$ 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 +.Ed +.Pp +.It --help +Show a summary of acceptable arguments and options. +.Pp +.It -d +.It -o +.It -x +.It --radix= Va number +Using one of these options, you can control whether the size of each section +is given in decimal ( +.Op -d , +or +.Op --radix=10 ) ; +octal ( +.Op -o , +or +.Op --radix=8 ) ; +or hexadecimal ( +.Op -x , +or +.Op --radix=16 ) . +In +.Op --radix= Va number , +only the three values (8, 10, 16) are supported. The total size is always +given in two radices; decimal and hexadecimal for +.Op -d +or +.Op -x +output, or octal and hexadecimal if you're using +.Op -o . +.Pp +.It -t +.It --totals +Show totals of all objects listed (Berkeley format listing mode only). +.Pp +.It --target= Va bfdname +Specify that the object-code format for +.Va objfile +is +.Va bfdname . +This option may not be necessary; +.Xr size +can automatically recognize many formats.See Section +.Dq Target Selection , +for more information. +.Pp +.It -V +.It --version +Display the version number of +.Xr size . +.El +.Pp +.Sh strings +.Bd -literal -offset indent +strings [-afov] [-min-len] + [-n min-len] [--bytes=min-len] + [-t radix] [--radix=radix] + [-e encoding] [--encoding=encoding] + [-] [--all] [--print-file-name] + [-T bfdname] [--target=bfdname] + [--help] [--version] file... +.Ed +.Pp +For each +.Va file +given, GNU +.Xr 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 an unprintable +character. By default, it only prints the strings from the initialized and +loaded sections of object files; for other types of files, it prints the strings +from the whole file. +.Pp +.Xr strings +is mainly useful for determining the contents of non-text files. +.Pp +.Bl -tag -width Ds +.It -a +.It --all +.It - +Do not scan only the initialized and loaded sections of object files; scan +the whole files. +.Pp +.It -f +.It --print-file-name +Print the name of the file before each string. +.Pp +.It --help +Print a summary of the program usage on the standard output and exit. +.Pp +.It - Va min-len +.It -n Va min-len +.It --bytes= Va min-len +Print sequences of characters that are at least +.Va min-len +characters long, instead of the default 4. +.Pp +.It -o +Like +.Li -t o . +Some other versions of +.Xr strings +have +.Op -o +act like +.Li -t d +instead. Since we can not be compatible with both ways, we simply chose one. +.Pp +.It -t Va radix +.It --radix= Va radix +Print the offset within the file before each string. The single character +argument specifies the radix of the offset--- +.Li o +for octal, +.Li x +for hexadecimal, or +.Li d +for decimal. +.Pp +.It -e Va encoding +.It --encoding= Va encoding +Select the character encoding of the strings that are to be found. Possible +values for +.Va encoding +are: +.Li s += single-7-bit-byte characters (ASCII, ISO 8859, etc., default), +.Li S += single-8-bit-byte characters, +.Li b += 16-bit bigendian, +.Li l += 16-bit littleendian, +.Li B += 32-bit bigendian, +.Li L += 32-bit littleendian. Useful for finding wide character strings. +.Pp +.It -T Va bfdname +.It --target= Va bfdname +Specify an object code format other than your system's default format.See Section +.Dq Target Selection , +for more information. +.Pp +.It -v +.It --version +Print the program version number on the standard output and exit. +.El +.Pp +.Sh strip +.Bd -literal -offset indent +strip [-F bfdname |--target=bfdname] + [-I bfdname |--input-target=bfdname] + [-O bfdname |--output-target=bfdname] + [-s|--strip-all] + [-S|-g|-d|--strip-debug] + [-K symbolname |--keep-symbol=symbolname] + [-N symbolname |--strip-symbol=symbolname] + [-w|--wildcard] + [-x|--discard-all] [-X |--discard-locals] + [-R sectionname |--remove-section=sectionname] + [-o file] [-p|--preserve-dates] + [--keep-file-symbols] + [--only-keep-debug] + [-v |--verbose] [-V|--version] + [--help] [--info] + objfile... +.Ed +.Pp +GNU +.Xr strip +discards all symbols from object files +.Va objfile . +The list of object files may include archives. At least one object file must +be given. +.Pp +.Xr strip +modifies the files named in its argument, rather than writing modified copies +under different names. +.Pp +.Bl -tag -width Ds +.It -F Va bfdname +.It --target= Va bfdname +Treat the original +.Va objfile +as a file with the object code format +.Va bfdname , +and rewrite it in the same format.See Section +.Dq Target Selection , +for more information. +.Pp +.It --help +Show a summary of the options to +.Xr strip +and exit. +.Pp +.It --info +Display a list showing all architectures and object formats available. +.Pp +.It -I Va bfdname +.It --input-target= Va bfdname +Treat the original +.Va objfile +as a file with the object code format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Replace +.Va objfile +with a file in the output format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -R Va sectionname +.It --remove-section= Va sectionname +Remove any section named +.Va sectionname +from the output file. This option may be given more than once. Note that using +this option inappropriately may make the output file unusable. +.Pp +.It -s +.It --strip-all +Remove all symbols. +.Pp +.It -g +.It -S +.It -d +.It --strip-debug +Remove debugging symbols only. +.Pp +.It --strip-unneeded +Remove all symbols that are not needed for relocation processing. +.Pp +.It -K Va symbolname +.It --keep-symbol= Va symbolname +When stripping symbols, keep symbol +.Va symbolname +even if it would normally be stripped. This option may be given more than +once. +.Pp +.It -N Va symbolname +.It --strip-symbol= Va symbolname +Remove symbol +.Va symbolname +from the source file. This option may be given more than once, and may be +combined with strip options other than +.Op -K . +.Pp +.It -o Va file +Put the stripped output in +.Va file , +rather than replacing the existing file. When this argument is used, only +one +.Va objfile +argument may be specified. +.Pp +.It -p +.It --preserve-dates +Preserve the access and modification dates of the file. +.Pp +.It -w +.It --wildcard +Permit regular expressions in +.Va symbolname +s used in other command line options. The question mark (?), asterisk (*), +backslash (\e) and square brackets ([]) operators can be used anywhere in the +symbol name. If the first character of the symbol name is the exclamation +point (!) then the sense of the switch is reversed for that symbol. For example: +.Pp +.Bd -literal -offset indent + -w -K !foo -K fo* +.Ed +.Pp +would cause strip to only keep symbols that start with the letters \(lqfo\(rq, but +to discard the symbol \(lqfoo\(rq. +.Pp +.It -x +.It --discard-all +Remove non-global symbols. +.Pp +.It -X +.It --discard-locals +Remove compiler-generated local symbols. (These usually start with +.Li L +or +.Li . . ) +.Pp +.It --keep-file-symbols +When stripping a file, perhaps with +.Op --strip-debug +or +.Op --strip-unneeded , +retain any symbols specifying source file names, which would otherwise get +stripped. +.Pp +.It --only-keep-debug +Strip a file, removing contents of any sections that would not be stripped +by +.Op --strip-debug +and leaving the debugging sections intact. In ELF files, this preserves all +note sections in the output. +.Pp +The intention is that this option will be used in conjunction with +.Op --add-GNU-debuglink +to create a two part executable. One a stripped binary which will occupy less +space in RAM and in a distribution and the second a debugging information +file which is only needed if debugging abilities are required. The suggested +procedure to create these files is as follows: +.Pp +.Bl -enum +.It +Link the executable as normal. Assuming that is is called +.Li foo +then... +.It +Run +.Li objcopy --only-keep-debug foo foo.dbg +to +create a file containing the debugging info. +.It +Run +.Li objcopy --strip-debug foo +to create a +stripped executable. +.It +Run +.Li objcopy --add-GNU-debuglink=foo.dbg foo +to add a link to the debugging info into the stripped executable. +.El +.Pp +Note - the choice of +.Li .dbg +as an extension for the debug info file is arbitrary. Also the +.Li --only-keep-debug +step is optional. You could instead do this: +.Pp +.Bl -enum +.It +Link the executable as normal. +.It +Copy +.Li foo +to +.Li foo.full +.It +Run +.Li strip --strip-debug foo +.It +Run +.Li objcopy --add-GNU-debuglink=foo.full foo +.El +.Pp +ie the file pointed to by the +.Op --add-GNU-debuglink +can be the full executable. It does not have to be a file created by the +.Op --only-keep-debug +switch. +.Pp +Note - this switch is only intended for use on fully linked files. It does +not make sense to use it on object files where the debugging information may +be incomplete. Besides the GNU_debuglink feature currently only supports the +presence of one filename containing debugging information, not multiple filenames +on a one-per-object-file basis. +.Pp +.It -V +.It --version +Show the version number for +.Xr strip . +.Pp +.It -v +.It --verbose +Verbose output: list all object files modified. In the case of archives, +.Li strip -v +lists all members of the archive. +.El +.Pp +.Sh c++filt +.Bd -literal -offset indent +c++filt [-_|--strip-underscores] + [-n|--no-strip-underscores] + [-p|--no-params] + [-t|--types] + [-i|--no-verbose] + [-s format|--format=format] + [--help] [--version] [symbol...] +.Ed +.Pp +The C++ and Java languages provide function overloading, which means that +you can write many functions with the same name, providing that each function +takes parameters of different types. In order to be able to distinguish these +similarly named functions C++ and Java encode them into a low-level assembler +name which uniquely identifies each different version. This process is known +as +.Em mangling . +The +.Xr c++filt +program does the inverse mapping: it decodes ( +.Em demangles ) +low-level names into user-level names so that they can be read. +.Pp +Every alphanumeric word (consisting of letters, digits, underscores, dollars, +or periods) seen in the input is a potential mangled name. If the name decodes +into a C++ name, the C++ name replaces the low-level name in the output, otherwise +the original word is output. In this way you can pass an entire assembler +source file, containing mangled names, through +.Xr c++filt +and see the same source file containing demangled names. +.Pp +You can also use +.Xr c++filt +to decipher individual symbols by passing them on the command line: +.Pp +.Bd -literal -offset indent +c++filt symbol +.Ed +.Pp +If no +.Va symbol +arguments are given, +.Xr c++filt +reads symbol names from the standard input instead. All the results are printed +on the standard output. The difference between reading names from the command +line versus reading names from the standard input is that command line arguments +are expected to be just mangled names and no checking is performed to separate +them from surrounding text. Thus for example: +.Pp +.Bd -literal -offset indent +c++filt -n _Z1fv +.Ed +.Pp +will work and demangle the name to \(lqf()\(rq whereas: +.Pp +.Bd -literal -offset indent +c++filt -n _Z1fv, +.Ed +.Pp +will not work. (Note the extra comma at the end of the mangled name which +makes it invalid). This command however will work: +.Pp +.Bd -literal -offset indent +echo _Z1fv, | c++filt -n +.Ed +.Pp +and will display \(lqf(),\(rq ie the demangled name followed by a trailing comma. +This behaviour is because when the names are read from the standard input +it is expected that they might be part of an assembler source file where there +might be extra, extraneous characters trailing after a mangled name. eg: +.Pp +.Bd -literal -offset indent + .type _Z1fv, @function +.Ed +.Pp +.Bl -tag -width Ds +.It -_ +.It --strip-underscores +On some systems, both the C and C++ compilers put an underscore in front of +every name. For example, the C name +.Li foo +gets the low-level name +.Li _foo . +This option removes the initial underscore. Whether +.Xr c++filt +removes the underscore by default is target dependent. +.Pp +.It -j +.It --java +Prints demangled names using Java syntax. The default is to use C++ syntax. +.Pp +.It -n +.It --no-strip-underscores +Do not remove the initial underscore. +.Pp +.It -p +.It --no-params +When demangling the name of a function, do not display the types of the function's +parameters. +.Pp +.It -t +.It --types +Attempt to demangle types as well as function names. This is disabled by default +since mangled types are normally only used internally in the compiler, and +they can be confused with non-mangled names. eg a function called \(lqa\(rq treated +as a mangled type name would be demangled to \(lqsigned char\(rq. +.Pp +.It -i +.It --no-verbose +Do not include implementation details (if any) in the demangled output. +.Pp +.It -s Va format +.It --format= Va format +.Xr c++filt +can decode various methods of mangling, used by different compilers. The argument +to this option selects which method it uses: +.Pp +.Bl -tag -width Ds +.It auto +Automatic selection based on executable (the default method) +.It GNU +the one used by the GNU C++ compiler (g++) +.It lucid +the one used by the Lucid compiler (lcc) +.It arm +the one specified by the C++ Annotated Reference Manual +.It hp +the one used by the HP compiler (aCC) +.It edg +the one used by the EDG compiler +.It GNU-v3 +the one used by the GNU C++ compiler (g++) with the V3 ABI. +.It java +the one used by the GNU Java compiler (gcj) +.It gnat +the one used by the GNU Ada compiler (GNAT). +.El +.Pp +.It --help +Print a summary of the options to +.Xr c++filt +and exit. +.Pp +.It --version +Print the version number of +.Xr c++filt +and exit. +.El +.Pp +.Qo +.Em Warning: +.Xr 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 future to decode a name passed as an argument on the command line; in +other words, +.Pp +.Bd -literal -offset indent +c++filt symbol +.Ed +.Pp +may in a future release become +.Pp +.Bd -literal -offset indent +c++filt option symbol +.Ed +.Qc +.Pp +.Sh addr2line +.Bd -literal -offset indent +addr2line [-b bfdname|--target=bfdname] + [-C|--demangle[=style]] + [-e filename|--exe=filename] + [-f|--functions] [-s|--basename] + [-i|--inlines] + [-j|--section=name] + [-H|--help] [-V|--version] + [addr addr ...] +.Ed +.Pp +.Xr addr2line +translates addresses into file names and line numbers. Given an address in +an executable or an offset in a section of a relocatable object, it uses the +debugging information to figure out which file name and line number are associated +with it. +.Pp +The executable or relocatable object to use is specified with the +.Op -e +option. The default is the file +.Pa a.out . +The section in the relocatable object to use is specified with the +.Op -j +option. +.Pp +.Xr addr2line +has two modes of operation. +.Pp +In the first, hexadecimal addresses are specified on the command line, and +.Xr addr2line +displays the file name and line number for each address. +.Pp +In the second, +.Xr addr2line +reads hexadecimal addresses from standard input, and prints the file name +and line number for each address on standard output. In this mode, +.Xr addr2line +may be used in a pipe to convert dynamically chosen addresses. +.Pp +The format of the output is +.Li FILENAME:LINENO . +The file name and line number for each address is printed on a separate line. +If the +.Xr -f +option is used, then each +.Li FILENAME:LINENO +line is preceded by a +.Li FUNCTIONNAME +line which is the name of the function containing the address. +.Pp +If the file name or function name can not be determined, +.Xr addr2line +will print two question marks in their place. If the line number can not be +determined, +.Xr addr2line +will print 0. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +.Pp +.Bl -tag -width Ds +.It -b Va bfdname +.It --target= Va bfdname +Specify that the object-code format for the object files is +.Va bfdname . +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It -e Va filename +.It --exe= Va filename +Specify the name of the executable for which addresses should be translated. +The default file is +.Pa a.out . +.Pp +.It -f +.It --functions +Display function names as well as file and line number information. +.Pp +.It -s +.It --basenames +Display only the base of each file name. +.Pp +.It -i +.It --inlines +If the address belongs to a function that was inlined, the source information +for all enclosing scopes back to the first non-inlined function will also +be printed. For example, if +.Li main +inlines +.Li callee1 +which inlines +.Li callee2 , +and address is from +.Li callee2 , +the source information for +.Li callee1 +and +.Li main +will also be printed. +.Pp +.It -j +.It --section +Read offsets relative to the specified section instead of absolute addresses. +.El +.Pp +.Sh nlmconv +.Xr nlmconv +converts a relocatable object file into a NetWare Loadable Module. +.Pp +.Qo +.Em Warning: +.Xr nlmconv +is not always built as part of the binary utilities, since it is only useful +for NLM targets. +.Qc +.Pp +.Bd -literal -offset indent +nlmconv [-I bfdname|--input-target=bfdname] + [-O bfdname|--output-target=bfdname] + [-T headerfile|--header-file=headerfile] + [-d|--debug] [-l linker|--linker=linker] + [-h|--help] [-V|--version] + infile outfile +.Ed +.Pp +.Xr nlmconv +converts the relocatable +.Li i386 +object file +.Va infile +into the NetWare Loadable Module +.Va outfile , +optionally reading +.Va headerfile +for NLM header information. For instructions on writing the NLM command file +language used in header files, see the +.Li linkers +section, +.Li NLMLINK +in particular, of the +.Em NLM Development and Tools Overview , +which is part of the NLM Software Developer's Kit (\(lqNLM SDK\(rq), available from +Novell, Inc. +.Xr nlmconv +uses the GNU Binary File Descriptor library to read +.Va infile ; +see BFD,,BFD,ld.info,Using LD, for more information. +.Pp +.Xr nlmconv +can perform a link step. In other words, you can list more than one object +file for input if you list them in the definitions file (rather than simply +specifying one input file on the command line). In this case, +.Xr nlmconv +calls the linker for you. +.Pp +.Bl -tag -width Ds +.It -I Va bfdname +.It --input-target= Va bfdname +Object format of the input file. +.Xr nlmconv +can usually determine the format of a given file (so no default is necessary).See Section +.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Object format of the output file. +.Xr nlmconv +infers the output format based on the input format, e.g. for a +.Li i386 +input file the output format is +.Li nlm32-i386 . +See Section.Dq Target Selection , +for more information. +.Pp +.It -T Va headerfile +.It --header-file= Va headerfile +Reads +.Va headerfile +for NLM header information. For instructions on writing the NLM command file +language used in header files, see see the +.Li linkers +section, of the +.Em NLM Development and Tools Overview , +which is part of the NLM Software Developer's Kit, available from Novell, +Inc. +.Pp +.It -d +.It --debug +Displays (on standard error) the linker command line used by +.Xr nlmconv . +.Pp +.It -l Va linker +.It --linker= Va linker +Use +.Va linker +for any linking. +.Va linker +can be an absolute or a relative pathname. +.Pp +.It -h +.It --help +Prints a usage summary. +.Pp +.It -V +.It --version +Prints the version number for +.Xr nlmconv . +.El +.Pp +.Sh windmc +.Xr windmc +may be used to generator Windows message resources. +.Pp +.Qo +.Em Warning: +.Xr windmc +is not always built as part of the binary utilities, since it is only useful +for Windows targets. +.Qc +.Pp +.Bd -literal -offset indent +windmc [options] input-file +.Ed +.Pp +.Xr windmc +reads message definitions from an input file (.mc) and translate them into +a set of output files. The output files may be of four kinds: +.Pp +.Bl -tag -width Ds +.It h +A C header file containing the message definitions. +.Pp +.It rc +A resource file compilable by the +.Xr windres +tool. +.Pp +.It bin +One or more binary files containing the resource data for a specific message +language. +.Pp +.It dbg +A C include file that maps message id's to their symbolic name. +.El +.Pp +The exact description of these different formats is available in documentation +from Microsoft. +.Pp +When +.Xr windmc +converts from the +.Li mc +format to the +.Li bin +format, +.Li rc , +.Li h , +and optional +.Li dbg +it is acting like the Windows Message Compiler. +.Pp +.Bl -tag -width Ds +.It -a +.It --ascii_in +Specifies that the input file specified is ANSI. This is the default behaviour. +.Pp +.It -A +.It --ascii_out +Specifies that messages in the output +.Li bin +files should be in ANSI format. +.Pp +.It -b +.It --binprefix +Specifies that +.Li bin +filenames should have to be prefixed by the basename of the source file. +.Pp +.It -c +.It --customflag +Sets the customer bit in all message id's. +.Pp +.It -C Va codepage +.It --codepage_in Va codepage +Sets the default codepage to be used to convert input file to UTF16. The default +is ocdepage 1252. +.Pp +.It -d +.It --decimal_values +Outputs the constants in the header file in decimal. Default is using hexadecimal +output. +.Pp +.It -e Va ext +.It --extension Va ext +The extension for the header file. The default is .h extension. +.Pp +.It -F Va target +.It --target Va target +Specify the BFD format to use for a bin file as output. This is a BFD target +name; you can use the +.Op --help +option to see a list of supported targets. Normally +.Xr windmc +will use the default format, which is the first one listed by the +.Op --help +option. Target Selection. +.Pp +.It -h Va path +.It --headerdir Va path +The target directory of the generated header file. The default is the current +directory. +.Pp +.It -H +.It --help +Displays a list of command line options and then exits. +.Pp +.It -m Va characters +.It --maxlength Va characters +Instructs +.Xr windmc +to generate a warning if the length of any message exceeds the number specified. +.Pp +.It -n +.It --nullterminate +Terminate message text in +.Li bin +files by zero. By default they are terminated by CR/LF. +.Pp +.It -o +.It --hresult_use +Not yet implemented. Instructs +.Li windmc +to generate an OLE2 header file, using HRESULT definitions. Status codes are +used if the flag is not specified. +.Pp +.It -O Va codepage +.It --codepage_out Va codepage +Sets the default codepage to be used to output text files. The default is +ocdepage 1252. +.Pp +.It -r Va path +.It --rcdir Va path +The target directory for the generated +.Li rc +script and the generated +.Li bin +files that the resource compiler script includes. The default is the current +directory. +.Pp +.It -u +.It --unicode_in +Specifies that the input file is UTF16. +.Pp +.It -U +.It --unicode_out +Specifies that messages in the output +.Li bin +file should be in UTF16 format. This is the default behaviour. +.Pp +.It -v +.It --verbose +Enable verbose mode. This tells you what the preprocessor is if you didn't +specify one. +.Pp +.It -V +.It --version +Prints the version number for +.Xr windres . +.Pp +.It -x Va path +.It --xdgb Va path +The path of the +.Li dbg +C include file that maps message id's to the symbolic name. No such file is +generated without specifying the switch. +.El +.Pp +.Sh windres +.Xr windres +may be used to manipulate Windows resources. +.Pp +.Qo +.Em Warning: +.Xr windres +is not always built as part of the binary utilities, since it is only useful +for Windows targets. +.Qc +.Pp +.Bd -literal -offset indent +windres [options] [input-file] [output-file] +.Ed +.Pp +.Xr windres +reads resources from an input file and copies them into an output file. Either +file may be in one of three formats: +.Pp +.Bl -tag -width Ds +.It rc +A text format read by the Resource Compiler. +.Pp +.It res +A binary format generated by the Resource Compiler. +.Pp +.It coff +A COFF object or executable. +.El +.Pp +The exact description of these different formats is available in documentation +from Microsoft. +.Pp +When +.Xr windres +converts from the +.Li rc +format to the +.Li res +format, it is acting like the Windows Resource Compiler. When +.Xr windres +converts from the +.Li res +format to the +.Li coff +format, it is acting like the Windows +.Li CVTRES +program. +.Pp +When +.Xr windres +generates an +.Li rc +file, the output is similar but not identical to the format expected for the +input. When an input +.Li rc +file refers to an external filename, an output +.Li rc +file will instead include the file contents. +.Pp +If the input or output format is not specified, +.Xr windres +will guess based on the file name, or, for the input file, the file contents. +A file with an extension of +.Pa .rc +will be treated as an +.Li rc +file, a file with an extension of +.Pa .res +will be treated as a +.Li res +file, and a file with an extension of +.Pa .o +or +.Pa .exe +will be treated as a +.Li coff +file. +.Pp +If no output file is specified, +.Xr windres +will print the resources in +.Li rc +format to standard output. +.Pp +The normal use is for you to write an +.Li rc +file, use +.Xr windres +to convert it to a COFF object file, and then link the COFF file into your +application. This will make the resources described in the +.Li rc +file available to Windows. +.Pp +.Bl -tag -width Ds +.It -i Va filename +.It --input Va filename +The name of the input file. If this option is not used, then +.Xr windres +will use the first non-option argument as the input file name. If there are +no non-option arguments, then +.Xr windres +will read from standard input. +.Xr windres +can not read a COFF file from standard input. +.Pp +.It -o Va filename +.It --output Va filename +The name of the output file. If this option is not used, then +.Xr windres +will use the first non-option argument, after any used for the input file +name, as the output file name. If there is no non-option argument, then +.Xr windres +will write to standard output. +.Xr windres +can not write a COFF file to standard output. Note, for compatibility with +.Xr rc +the option +.Op -fo +is also accepted, but its use is not recommended. +.Pp +.It -J Va format +.It --input-format Va format +The input format to read. +.Va format +may be +.Li res , +.Li rc , +or +.Li coff . +If no input format is specified, +.Xr windres +will guess, as described above. +.Pp +.It -O Va format +.It --output-format Va format +The output format to generate. +.Va format +may be +.Li res , +.Li rc , +or +.Li coff . +If no output format is specified, +.Xr windres +will guess, as described above. +.Pp +.It -F Va target +.It --target Va target +Specify the BFD format to use for a COFF file as input or output. This is +a BFD target name; you can use the +.Op --help +option to see a list of supported targets. Normally +.Xr windres +will use the default format, which is the first one listed by the +.Op --help +option. Target Selection. +.Pp +.It --preprocessor Va program +When +.Xr windres +reads an +.Li rc +file, it runs it through the C preprocessor first. This option may be used +to specify the preprocessor to use, including any leading arguments. The default +preprocessor argument is +.Li gcc -E -xc-header -DRC_INVOKED . +.Pp +.It -I Va directory +.It --include-dir Va directory +Specify an include directory to use when reading an +.Li rc +file. +.Xr windres +will pass this to the preprocessor as an +.Op -I +option. +.Xr windres +will also search this directory when looking for files named in the +.Li rc +file. If the argument passed to this command matches any of the supported +.Va formats +(as described in the +.Op -J +option), it will issue a deprecation warning, and behave just like the +.Op -J +option. New programs should not use this behaviour. If a directory happens +to match a +.Va format , +simple prefix it with +.Li ./ +to disable the backward compatibility. +.Pp +.It -D Va target +.It --define Va sym[= Va val] +Specify a +.Op -D +option to pass to the preprocessor when reading an +.Li rc +file. +.Pp +.It -U Va target +.It --undefine Va sym +Specify a +.Op -U +option to pass to the preprocessor when reading an +.Li rc +file. +.Pp +.It -r +Ignored for compatibility with rc. +.Pp +.It -v +Enable verbose mode. This tells you what the preprocessor is if you didn't +specify one. +.Pp +.It -c Va val +.It --codepage Va val +Specify the default codepage to use when reading an +.Li rc +file. +.Va val +should be a hexadecimal prefixed by +.Li 0x +or decimal codepage code. The valid range is from zero up to 0xffff, but the +validity of the codepage is host and configuration dependent. +.Pp +.It -l Va val +.It --language Va val +Specify the default language to use when reading an +.Li rc +file. +.Va val +should be a hexadecimal language code. The low eight bits are the language, +and the high eight bits are the sublanguage. +.Pp +.It --use-temp-file +Use a temporary file to instead of using popen to read the output of the preprocessor. +Use this option if the popen implementation is buggy on the host (eg., certain +non-English language versions of Windows 95 and Windows 98 are known to have +buggy popen where the output will instead go the console). +.Pp +.It --no-use-temp-file +Use popen, not a temporary file, to read the output of the preprocessor. This +is the default behaviour. +.Pp +.It -h +.It --help +Prints a usage summary. +.Pp +.It -V +.It --version +Prints the version number for +.Xr windres . +.Pp +.It --yydebug +If +.Xr windres +is compiled with +.Li YYDEBUG +defined as +.Li 1 , +this will turn on parser debugging. +.El +.Pp +.Sh dlltool +.Xr dlltool +is used to create the files needed to create dynamic link libraries (DLLs) +on systems which understand PE format image files such as Windows. A DLL contains +an export table which contains information that the runtime loader needs to +resolve references from a referencing program. +.Pp +The export table is generated by this program by reading in a +.Pa .def +file or scanning the +.Pa .a +and +.Pa .o +files which will be in the DLL. A +.Pa .o +file can contain information in special +.Li .drectve +sections with export information. +.Pp +.Qo +.Em Note: +.Xr dlltool +is not always built as part of the binary utilities, since it is only useful +for those targets which support DLLs. +.Qc +.Pp +.Bd -literal -offset indent +dlltool [-d|--input-def def-file-name] + [-b|--base-file base-file-name] + [-e|--output-exp exports-file-name] + [-z|--output-def def-file-name] + [-l|--output-lib library-file-name] + [--export-all-symbols] [--no-export-all-symbols] + [--exclude-symbols list] + [--no-default-excludes] + [-S|--as path-to-assembler] [-f|--as-flags options] + [-D|--dllname name] [-m|--machine machine] + [-a|--add-indirect] + [-U|--add-underscore] [--add-stdcall-underscore] + [-k|--kill-at] [-A|--add-stdcall-alias] + [-p|--ext-prefix-alias prefix] + [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork] + [-n|--nodelete] [-t|--temp-prefix prefix] + [-v|--verbose] + [-h|--help] [-V|--version] + [object-file ...] +.Ed +.Pp +.Xr dlltool +reads its inputs, which can come from the +.Op -d +and +.Op -b +options as well as object files specified on the command line. It then processes +these inputs and if the +.Op -e +option has been specified it creates a exports file. If the +.Op -l +option has been specified it creates a library file and if the +.Op -z +option has been specified it creates a def file. Any or all of the +.Op -e , +.Op -l +and +.Op -z +options can be present in one invocation of dlltool. +.Pp +When creating a DLL, along with the source for the DLL, it is necessary to +have three other files. +.Xr dlltool +can help with the creation of these files. +.Pp +The first file is a +.Pa .def +file which specifies which functions are exported from the DLL, which functions +the DLL imports, and so on. This is a text file and can be created by hand, +or +.Xr dlltool +can be used to create it using the +.Op -z +option. In this case +.Xr dlltool +will scan the object files specified on its command line looking for those +functions which have been specially marked as being exported and put entries +for them in the +.Pa .def +file it creates. +.Pp +In order to mark a function as being exported from a DLL, it needs to have +an +.Op -export:<name_of_function> +entry in the +.Li .drectve +section of the object file. This can be done in C by using the asm() operator: +.Pp +.Bd -literal -offset indent + asm (".section .drectve"); + asm (".ascii \e"-export:my_func\e""); + + int my_func (void) { ... } +.Ed +.Pp +The second file needed for DLL creation is an exports file. This file is linked +with the object files that make up the body of the DLL and it handles the +interface between the DLL and the outside world. This is a binary file and +it can be created by giving the +.Op -e +option to +.Xr dlltool +when it is creating or reading in a +.Pa .def +file. +.Pp +The third file needed for DLL creation is the library file that programs will +link with in order to access the functions in the DLL. This file can be created +by giving the +.Op -l +option to dlltool when it is creating or reading in a +.Pa .def +file. +.Pp +.Xr dlltool +builds the library file by hand, but it builds the exports file by creating +temporary files containing assembler statements and then assembling these. +The +.Op -S +command line option can be used to specify the path to the assembler that +dlltool will use, and the +.Op -f +option can be used to pass specific flags to that assembler. The +.Op -n +can be used to prevent dlltool from deleting these temporary assembler files +when it is done, and if +.Op -n +is specified twice then this will prevent dlltool from deleting the temporary +object files it used to build the library. +.Pp +Here is an example of creating a DLL from a source file +.Li dll.c +and also creating a program (from an object file called +.Li program.o ) +that uses that DLL: +.Pp +.Bd -literal -offset indent + gcc -c dll.c + dlltool -e exports.o -l dll.lib dll.o + gcc dll.o exports.o -o dll.dll + gcc program.o dll.lib -o program +.Ed +.Pp +The command line options have the following meanings: +.Pp +.Bl -tag -width Ds +.It -d Va filename +.It --input-def Va filename +Specifies the name of a +.Pa .def +file to be read in and processed. +.Pp +.It -b Va filename +.It --base-file Va filename +Specifies the name of a base file to be read in and processed. The contents +of this file will be added to the relocation section in the exports file generated +by dlltool. +.Pp +.It -e Va filename +.It --output-exp Va filename +Specifies the name of the export file to be created by dlltool. +.Pp +.It -z Va filename +.It --output-def Va filename +Specifies the name of the +.Pa .def +file to be created by dlltool. +.Pp +.It -l Va filename +.It --output-lib Va filename +Specifies the name of the library file to be created by dlltool. +.Pp +.It --export-all-symbols +Treat all global and weak defined symbols found in the input object files +as symbols to be exported. There is a small list of symbols which are not +exported by default; see the +.Op --no-default-excludes +option. You may add to the list of symbols to not export by using the +.Op --exclude-symbols +option. +.Pp +.It --no-export-all-symbols +Only export symbols explicitly listed in an input +.Pa .def +file or in +.Li .drectve +sections in the input object files. This is the default behaviour. The +.Li .drectve +sections are created by +.Li dllexport +attributes in the source code. +.Pp +.It --exclude-symbols Va list +Do not export the symbols in +.Va list . +This is a list of symbol names separated by comma or colon characters. The +symbol names should not contain a leading underscore. This is only meaningful +when +.Op --export-all-symbols +is used. +.Pp +.It --no-default-excludes +When +.Op --export-all-symbols +is used, it will by default avoid exporting certain special symbols. The current +list of symbols to avoid exporting is +.Li DllMain@12 , +.Li DllEntryPoint@0 , +.Li impure_ptr . +You may use the +.Op --no-default-excludes +option to go ahead and export these special symbols. This is only meaningful +when +.Op --export-all-symbols +is used. +.Pp +.It -S Va path +.It --as Va path +Specifies the path, including the filename, of the assembler to be used to +create the exports file. +.Pp +.It -f Va options +.It --as-flags Va options +Specifies any specific command line options to be passed to the assembler +when building the exports file. This option will work even if the +.Op -S +option is not used. This option only takes one argument, and if it occurs +more than once on the command line, then later occurrences will override earlier +occurrences. So if it is necessary to pass multiple options to the assembler +they should be enclosed in double quotes. +.Pp +.It -D Va name +.It --dll-name Va name +Specifies the name to be stored in the +.Pa .def +file as the name of the DLL when the +.Op -e +option is used. If this option is not present, then the filename given to +the +.Op -e +option will be used as the name of the DLL. +.Pp +.It -m Va machine +.It -machine Va machine +Specifies the type of machine for which the library file should be built. +.Xr dlltool +has a built in default type, depending upon how it was created, but this option +can be used to override that. This is normally only useful when creating DLLs +for an ARM processor, when the contents of the DLL are actually encode using +Thumb instructions. +.Pp +.It -a +.It --add-indirect +Specifies that when +.Xr dlltool +is creating the exports file it should add a section which allows the exported +functions to be referenced without using the import library. Whatever the +hell that means! +.Pp +.It -U +.It --add-underscore +Specifies that when +.Xr dlltool +is creating the exports file it should prepend an underscore to the names +of +.Em all +exported symbols. +.Pp +.It --add-stdcall-underscore +Specifies that when +.Xr dlltool +is creating the exports file it should prepend an underscore to the names +of exported +.Em stdcall +functions. Variable names and non-stdcall function names are not modified. +This option is useful when creating GNU-compatible import libs for third party +DLLs that were built with MS-Windows tools. +.Pp +.It -k +.It --kill-at +Specifies that when +.Xr dlltool +is creating the exports file it should not append the string +.Li @ <number> . +These numbers are called ordinal numbers and they represent another way of +accessing the function in a DLL, other than by name. +.Pp +.It -A +.It --add-stdcall-alias +Specifies that when +.Xr dlltool +is creating the exports file it should add aliases for stdcall symbols without +.Li @ <number> +in addition to the symbols with +.Li @ <number> . +.Pp +.It -p +.It --ext-prefix-alias Va prefix +Causes +.Xr dlltool +to create external aliases for all DLL imports with the specified prefix. +The aliases are created for both external and import symbols with no leading +underscore. +.Pp +.It -x +.It --no-idata4 +Specifies that when +.Xr dlltool +is creating the exports and library files it should omit the +.Li .idata4 +section. This is for compatibility with certain operating systems. +.Pp +.It -c +.It --no-idata5 +Specifies that when +.Xr dlltool +is creating the exports and library files it should omit the +.Li .idata5 +section. This is for compatibility with certain operating systems. +.Pp +.It -i +.It --interwork +Specifies that +.Xr dlltool +should mark the objects in the library file and exports file that it produces +as supporting interworking between ARM and Thumb code. +.Pp +.It -n +.It --nodelete +Makes +.Xr dlltool +preserve the temporary assembler files it used to create the exports file. +If this option is repeated then dlltool will also preserve the temporary object +files it uses to create the library file. +.Pp +.It -t Va prefix +.It --temp-prefix Va prefix +Makes +.Xr dlltool +use +.Va prefix +when constructing the names of temporary assembler and object files. By default, +the temp file prefix is generated from the pid. +.Pp +.It -v +.It --verbose +Make dlltool describe what it is doing. +.Pp +.It -h +.It --help +Displays a list of command line options and then exits. +.Pp +.It -V +.It --version +Displays dlltool's version number and then exits. +.Pp +.El +.Ss The format of the Xr dlltool Pa .def file +A +.Pa .def +file contains any number of the following commands: +.Pp +.Bl -tag -width Ds +.It Li NAME Va name Li [ , Va base Li ] +The result is going to be named +.Va name +.Li .exe . +.Pp +.It Li LIBRARY Va name Li [ , Va base Li ] +The result is going to be named +.Va name +.Li .dll . +.Pp +.It Li EXPORTS ( ( ( Va name1 Li [ = Va name2 Li ] ) | ( Va name1 Li = Va module-name Li . Va external-name Li ) ) +.It Li [ Va integer Li ] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) * +Declares +.Va name1 +as an exported symbol from the DLL, with optional ordinal number +.Va integer , +or declares +.Va name1 +as an alias (forward) of the function +.Va external-name +in the DLL +.Va module-name . +.Pp +.It Li IMPORTS ( ( Va internal-name Li = Va module-name Li . Va integer Li ) | [ Va internal-name Li = ] Va module-name Li . Va external-name Li ) ) * +Declares that +.Va external-name +or the exported function whose ordinal number is +.Va integer +is to be imported from the file +.Va module-name . +If +.Va internal-name +is specified then this is the name that the imported function will be referred +to in the body of the DLL. +.Pp +.It Li DESCRIPTION Va string +Puts +.Va string +into the output +.Pa .exp +file in the +.Li .rdata +section. +.Pp +.It Li STACKSIZE Va number-reserve Li [, Va number-commit Li ] +.It Li HEAPSIZE Va number-reserve Li [, Va number-commit Li ] +Generates +.Li --stack +or +.Li --heap +.Va number-reserve +, +.Va number-commit +in the output +.Li .drectve +section. The linker will see this and act upon it. +.Pp +.It Li CODE Va attr Li + +.It Li DATA Va attr Li + +.It Li SECTIONS ( Va section-name Va attr Li + ) * +Generates +.Li --attr +.Va section-name +.Va attr +in the output +.Li .drectve +section, where +.Va attr +is one of +.Li READ , +.Li WRITE , +.Li EXECUTE +or +.Li SHARED . +The linker will see this and act upon it. +.Pp +.El +.Sh readelf +.Bd -literal -offset indent +readelf [-a|--all] + [-h|--file-header] + [-l|--program-headers|--segments] + [-S|--section-headers|--sections] + [-g|--section-groups] + [-t|--section-details] + [-e|--headers] + [-s|--syms|--symbols] + [-n|--notes] + [-r|--relocs] + [-u|--unwind] + [-d|--dynamic] + [-V|--version-info] + [-A|--arch-specific] + [-D|--use-dynamic] + [-x <number or name>|--hex-dump=<number or name>] + [-w[liaprmfFsoR]| + --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]] + [-I|-histogram] + [-v|--version] + [-W|--wide] + [-H|--help] + elffile... +.Ed +.Pp +.Xr readelf +displays information about one or more ELF format object files. The options +control what particular information to display. +.Pp +.Va elffile +\&...are the object files to be examined. 32-bit and 64-bit ELF files are supported, +as are archives containing ELF files. +.Pp +This program performs a similar function to +.Xr objdump +but it goes into more detail and it exists independently of the bfd library, +so if there is a bug in bfd then readelf will not be affected. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +At least one option besides +.Li -v +or +.Li -H +must be given. +.Pp +.Bl -tag -width Ds +.It -a +.It --all +Equivalent to specifying +.Op --file-header , +.Op --program-headers , +.Op --sections , +.Op --symbols , +.Op --relocs , +.Op --dynamic , +.Op --notes +and +.Op --version-info . +.Pp +.It -h +.It --file-header +Displays the information contained in the ELF header at the start of the file. +.Pp +.It -l +.It --program-headers +.It --segments +Displays the information contained in the file's segment headers, if it has +any. +.Pp +.It -S +.It --sections +.It --section-headers +Displays the information contained in the file's section headers, if it has +any. +.Pp +.It -g +.It --section-groups +Displays the information contained in the file's section groups, if it has +any. +.Pp +.It -t +.It --section-details +Displays the detailed section information. Implies +.Op -S . +.Pp +.It -s +.It --symbols +.It --syms +Displays the entries in symbol table section of the file, if it has one. +.Pp +.It -e +.It --headers +Display all the headers in the file. Equivalent to +.Op -h -l -S . +.Pp +.It -n +.It --notes +Displays the contents of the NOTE segments and/or sections, if any. +.Pp +.It -r +.It --relocs +Displays the contents of the file's relocation section, if it has one. +.Pp +.It -u +.It --unwind +Displays the contents of the file's unwind section, if it has one. Only the +unwind sections for IA64 ELF files are currently supported. +.Pp +.It -d +.It --dynamic +Displays the contents of the file's dynamic section, if it has one. +.Pp +.It -V +.It --version-info +Displays the contents of the version sections in the file, it they exist. +.Pp +.It -A +.It --arch-specific +Displays architecture-specific information in the file, if there is any. +.Pp +.It -D +.It --use-dynamic +When displaying symbols, this option makes +.Xr readelf +use the symbol table in the file's dynamic section, rather than the one in +the symbols section. +.Pp +.It -x <number or name> +.It --hex-dump=<number or name> +Displays the contents of the indicated section as a hexadecimal dump. A number +identifies a particular section by index in the section table; any other string +identifies all sections with that name in the object file. +.Pp +.It -w[liaprmfFsoR] +.It --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges] +Displays the contents of the debug sections in the file, if any are present. +If one of the optional letters or words follows the switch then only data +found in those specific sections will be dumped. +.Pp +.It -I +.It --histogram +Display a histogram of bucket list lengths when displaying the contents of +the symbol tables. +.Pp +.It -v +.It --version +Display the version number of readelf. +.Pp +.It -W +.It --wide +Don't break output lines to fit into 80 columns. By default +.Xr readelf +breaks section header and segment listing lines for 64-bit ELF files, so that +they fit into 80 columns. This option causes +.Xr readelf +to print each section header resp. each segment one a single line, which is +far more readable on terminals wider than 80 columns. +.Pp +.It -H +.It --help +Display the command line options understood by +.Xr readelf . +.Pp +.El +.Sh Common Options +The following command-line options are supported by all of the programs described +in this manual. +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +are separated by whitespace. A whitespace character may be included in an +option by surrounding the entire option in either single or double quotes. +Any character (including a backslash) may be included by prefixing the character +to be included with a backslash. The +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It --help +Display the command-line options supported by the program. +.Pp +.It --version +Display the version number of the program. +.Pp +.El +.Sh Selecting the Target System +You can specify two aspects of the target system to the GNU binary file utilities, +each in several ways: +.Pp +.Bl -bullet +.It +the target +.Pp +.It +the architecture +.El +.Pp +In the following summaries, the lists of ways to specify values are in order +of decreasing precedence. The ways listed first override those listed later. +.Pp +The commands to list valid values only list the values for which the programs +you are running were configured. If they were configured with +.Op --enable-targets=all , +the commands list most of the available values, but a few are left out; not +all targets can be configured in at once because some of them can only be +configured +.Em native +(on hosts with the same type as the target system). +.Pp +.Ss Target Selection +A +.Em target +is an object file format. A given target may be supported for multiple architectures +(see Section +.Dq Architecture Selection ) . +A target selection may also have variations for different operating systems +or architectures. +.Pp +The command to list valid target values is +.Li objdump -i +(the first column of output contains the relevant information). +.Pp +Some sample values are: +.Li a.out-hp300bsd , +.Li ecoff-littlemips , +.Li a.out-sunos-big . +.Pp +You can also specify a target using a configuration triplet. This is the same +sort of name that is passed to +.Pa configure +to specify a target. When you use a configuration triplet as an argument, +it must be fully canonicalized. You can see the canonical version of a triplet +by running the shell script +.Pa config.sub +which is included with the sources. +.Pp +Some sample configuration triplets are: +.Li m68k-hp-bsd , +.Li mips-dec-ultrix , +.Li sparc-sun-sunos . +.Pp +.Em Xr objdump Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op -b +or +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy and Xr strip Input Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line options: +.Op -I +or +.Op --input-target , +or +.Op -F +or +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy and Xr strip Output Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line options: +.Op -O +or +.Op --output-target , +or +.Op -F +or +.Op --target +.Pp +.It +the input target (see \(lq +.Xr objcopy +and +.Xr strip +Input Target\(rq above) +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr nm, Xr size, and Xr strings Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Ss Architecture Selection +An +.Em architecture +is a type of cpu on which an object file is to run. Its name may contain a +colon, separating the name of the processor family from the name of the particular +cpu. +.Pp +The command to list valid architecture values is +.Li objdump -i +(the second column contains the relevant information). +.Pp +Sample values: +.Li m68k:68020 , +.Li mips:3000 , +.Li sparc . +.Pp +.Em Xr objdump Architecture +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op -m +or +.Op --architecture +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy, Xr nm, Xr size, Xr strings Architecture +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +deduced from the input file +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making the binary utilities reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of the binary utilities work +better. Bug reports are your contribution to their maintenance. +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If a binary utility gets a fatal signal, for any input whatever, that is a +bug. Reliable utilities never crash. +.Pp +.It +If a binary utility produces an error message for valid input, that is a bug. +.Pp +.It +If you are an experienced user of binary utilities, your suggestions for improvement +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained the binary utilities from a support organization, we recommend you +contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a file you use in an example does not matter. Well, probably it does +not, but one cannot be sure. Perhaps the bug is a stray memory reference which +happens to fetch from the location where that pathname is stored in memory; +perhaps, if the pathname were different, the contents of that location would +fool the utility into doing the right thing despite the bug. Play it safe +and give a specific, complete example. That is the easiest thing for you to +do, and the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of the utility. Each utility announces it if you start it with +the +.Op --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of the binary utilities. +.Pp +.It +Any patches you may have applied to the source, including any patches made +to the +.Li BFD +library. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile the utilities---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the utility to observe the bug. To guarantee +you will not omit something important, list them all. A copy of the Makefile +(or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file, or set of input files, that will reproduce the bug. +If the utility is reading an object file or files, then it is generally most +helpful to send the actual object files. +.Pp +If the source files were produced exclusively using GNU programs (e.g., +.Xr gcc , +.Xr gas , +and/or the GNU +.Xr ld ) , +then it may be OK to send the source files rather than the object files. In +this case, be sure to say exactly what version of +.Xr gcc , +or whatever, was used to produce the object files. Also say how +.Xr gcc , +or whatever, was configured. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that the utility gets a fatal signal, then we will +certainly notice it. But if the bug is incorrect output, we might not notice +unless it is glaringly wrong. You might as well not give us a chance to make +a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as your copy of +the utility is out of sync, or you have encountered a bug in the C library +on your system. (This has happened!) Your copy might crash and ours would +not. If you told us to expect a crash, then when ours fails to crash, we would +know that the bug was not happening for us. If you had not told us to expect +a crash, then we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the source, send us context diffs, as generated +by +.Xr diff +with the +.Op -u , +.Op -c , +or +.Op -p +option. Always send diffs from the old file to the new file. If you wish to +discuss something in the +.Xr ld +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with programs as complicated as the binary utilities it is very +hard to construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be able to +construct one, so we will not be able to verify that the bug is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document 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. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation 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. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh Binutils Index diff --git a/contrib/binutils/gas/doc/as.7 b/contrib/binutils/gas/doc/as.7 new file mode 100644 index 000000000000..4d335576d060 --- /dev/null +++ b/contrib/binutils/gas/doc/as.7 @@ -0,0 +1,8368 @@ +.Dd 2015-03-02 +.Dt AS 7 +.Os +.Sh NAME +.Nm as +.Nd Using as (machine specific) +.Sh Using as +This file is a user guide to the GNU assembler +.Xr as +version "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes +.Xr as +configured to generate code for machine specific architectures. +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled \(lqGNU Free +Documentation License\(rq. +.Pp +.Sh Overview +Here is a brief summary of how to invoke +.Xr as . +For details, see Invoking,,Command-Line Options. +.Pp +.Bd -literal -offset indent +as [-a[cdhlns][=file]] [--alternate] [-D] + [--defsym sym=val] [-f] [-g] [--gstabs] + [--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J] + [-K] [-L] [--listing-lhs-width=NUM] + [--listing-lhs-width2=NUM] [--listing-rhs-width=NUM] + [--listing-cont-lines=NUM] [--keep-locals] [-o + objfile] [-R] [--reduce-memory-overheads] [--statistics] + [-v] [-version] [--version] [-W] [--warn] + [--fatal-warnings] [-w] [-x] [-Z] [@FILE] + [--target-help] [target-options] + [--|files ...] + +Target ARM options: + [-mcpu=processor[+extension...]] + [-march=architecture[+extension...]] + [-mfpu=floating-point-format] + [-mfloat-abi=abi] + [-meabi=ver] + [-mthumb] + [-EB|-EL] + [-mapcs-32|-mapcs-26|-mapcs-float| + -mapcs-reentrant] + [-mthumb-interwork] [-k] + + +Target i386 options: + [--32|--64] [-n] + [-march=CPU] [-mtune=CPU] + + +Target IA-64 options: + [-mconstant-gp|-mauto-pic] + [-milp32|-milp64|-mlp64|-mp64] + [-mle|mbe] + [-mtune=itanium1|-mtune=itanium2] + [-munwind-check=warning|-munwind-check=error] + [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] + [-x|-xexplicit] [-xauto] [-xdebug] + + +Target MIPS options: + [-nocpp] [-EL] [-EB] [-O[optimization level]] + [-g[debug level]] [-G num] [-KPIC] [-call_shared] + [-non_shared] [-xgot [-mvxworks-pic] + [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] + [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] + [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] + [-mips64] [-mips64r2] + [-construct-floats] [-no-construct-floats] + [-trap] [-no-break] [-break] [-no-trap] + [-mfix7000] [-mno-fix7000] + [-mips16] [-no-mips16] + [-msmartmips] [-mno-smartmips] + [-mips3d] [-no-mips3d] + [-mdmx] [-no-mdmx] + [-mdsp] [-mno-dsp] + [-mdspr2] [-mno-dspr2] + [-mmt] [-mno-mt] + [-mdebug] [-no-mdebug] + [-mpdr] [-mno-pdr] + + +Target PowerPC options: + [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| + -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| + -mbooke32|-mbooke64] + [-mcom|-many|-maltivec] [-memb] + [-mregnames|-mno-regnames] + [-mrelocatable|-mrelocatable-lib] + [-mlittle|-mlittle-endian|-mbig|-mbig-endian] + [-msolaris|-mno-solaris] + + +Target SPARC options: + [-Av6|-Av7|-Av8|-Asparclet|-Asparclite + -Av8plus|-Av8plusa|-Av9|-Av9a] + [-xarch=v8plus|-xarch=v8plusa] [-bump] + [-32|-64] + + + +.Ed +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +are separated by whitespace. A whitespace character may be included in an +option by surrounding the entire option in either single or double quotes. +Any character (including a backslash) may be included by prefixing the character +to be included with a backslash. The +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It -a[cdhlmns] +Turn on listings, in any of a variety of ways: +.Pp +.Bl -tag -width Ds +.It -ac +omit false conditionals +.Pp +.It -ad +omit debugging directives +.Pp +.It -ah +include high-level source +.Pp +.It -al +include assembly +.Pp +.It -am +include macro expansions +.Pp +.It -an +omit forms processing +.Pp +.It -as +include symbols +.Pp +.It =file +set the name of the listing file +.El +.Pp +You may combine these options; for example, use +.Li -aln +for assembly listing without forms processing. The +.Li =file +option, if used, must be the last one. By itself, +.Li -a +defaults to +.Li -ahls . +.Pp +.It --alternate +Begin in alternate macro mode.See Section +.Dq Altmacro . +.Pp +.It -D +Ignored. This option is accepted for script compatibility with calls to other +assemblers. +.Pp +.It --defsym Va sym= Va value +Define the symbol +.Va sym +to be +.Va value +before assembling the input file. +.Va value +must be an integer constant. As in C, a leading +.Li 0x +indicates a hexadecimal value, and a leading +.Li 0 +indicates an octal value. The value of the symbol can be overridden inside +a source file via the use of a +.Li .set +pseudo-op. +.Pp +.It -f +\(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler +output). +.Pp +.It -g +.It --gen-debug +Generate debugging information for each assembler source line using whichever +debug format is preferred by the target. This currently means either STABS, +ECOFF or DWARF2. +.Pp +.It --gstabs +Generate stabs debugging information for each assembler line. This may help +debugging assembler code, if the debugger can handle it. +.Pp +.It --gstabs+ +Generate stabs debugging information for each assembler line, with GNU extensions +that probably only gdb can handle, and that could make other debuggers crash +or refuse to read your program. This may help debugging assembler code. Currently +the only GNU extension is the location of the current working directory at +assembling time. +.Pp +.It --gdwarf-2 +Generate DWARF2 debugging information for each assembler line. This may help +debugging assembler code, if the debugger can handle it. Note---this option +is only supported by some targets, not all of them. +.Pp +.It --help +Print a summary of the command line options and exit. +.Pp +.It --target-help +Print a summary of all target specific options and exit. +.Pp +.It -I Va dir +Add directory +.Va dir +to the search list for +.Li .include +directives. +.Pp +.It -J +Don't warn about signed overflow. +.Pp +.It -K +This option is accepted but has no effect on the machine specific family. +.Pp +.It -L +.It --keep-locals +Keep (in the symbol table) local symbols. These symbols start with system-specific +local label prefixes, typically +.Li .L +for ELF systems or +.Li L +for traditional a.out systems.See Section +.Dq Symbol Names . +.Pp +.It --listing-lhs-width= Va number +Set the maximum width, in words, of the output data column for an assembler +listing to +.Va number . +.Pp +.It --listing-lhs-width2= Va number +Set the maximum width, in words, of the output data column for continuation +lines in an assembler listing to +.Va number . +.Pp +.It --listing-rhs-width= Va number +Set the maximum width of an input source line, as displayed in a listing, +to +.Va number +bytes. +.Pp +.It --listing-cont-lines= Va number +Set the maximum number of lines printed in a listing for a single line of +input to +.Va number ++ 1. +.Pp +.It -o Va objfile +Name the object-file output from +.Xr as +.Va objfile . +.Pp +.It -R +Fold the data section into the text section. +.Pp +Set the default size of GAS's hash tables to a prime number close to +.Va number . +Increasing this value can reduce the length of time it takes the assembler +to perform its tasks, at the expense of increasing the assembler's memory +requirements. Similarly reducing this value can reduce the memory requirements +at the expense of speed. +.Pp +.It --reduce-memory-overheads +This option reduces GAS's memory requirements, at the expense of making the +assembly processes slower. Currently this switch is a synonym for +.Li --hash-size=4051 , +but in the future it may have other effects as well. +.Pp +.It --statistics +Print the maximum space (in bytes) and total time (in seconds) used by assembly. +.Pp +.It --strip-local-absolute +Remove local absolute symbols from the outgoing symbol table. +.Pp +.It -v +.It -version +Print the +.Xr as +version. +.Pp +.It --version +Print the +.Xr as +version and exit. +.Pp +.It -W +.It --no-warn +Suppress warning messages. +.Pp +.It --fatal-warnings +Treat warnings as errors. +.Pp +.It --warn +Don't suppress warning messages or treat them as errors. +.Pp +.It -w +Ignored. +.Pp +.It -x +Ignored. +.Pp +.It -Z +Generate an object file even after errors. +.Pp +.It -- | Va files ... +Standard input, or source files to assemble. +.Pp +.El +The following options are available when as is configured for the ARM processor +family. +.Pp +.Bl -tag -width Ds +.It -mcpu= Va processor[+ Va extension...] +Specify which ARM processor variant is the target. +.It -march= Va architecture[+ Va extension...] +Specify which ARM architecture variant is used by the target. +.It -mfpu= Va floating-point-format +Select which Floating Point architecture is the target. +.It -mfloat-abi= Va abi +Select which floating point ABI is in use. +.It -mthumb +Enable Thumb only instruction decoding. +.It -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant +Select which procedure calling convention is in use. +.It -EB | -EL +Select either big-endian (-EB) or little-endian (-EL) output. +.It -mthumb-interwork +Specify that the code has been generated with interworking between Thumb and +ARM code in mind. +.It -k +Specify that PIC code has been generated. +.El +.Pp +The following options are available when +.Xr as +is configured for the SPARC architecture: +.Pp +.Bl -tag -width Ds +.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite +.It -Av8plus | -Av8plusa | -Av9 | -Av9a +Explicitly select a variant of the SPARC architecture. +.Pp +.Li -Av8plus +and +.Li -Av8plusa +select a 32 bit environment. +.Li -Av9 +and +.Li -Av9a +select a 64 bit environment. +.Pp +.Li -Av8plusa +and +.Li -Av9a +enable the SPARC V9 instruction set with UltraSPARC extensions. +.Pp +.It -xarch=v8plus | -xarch=v8plusa +For compatibility with the Solaris v9 assembler. These options are equivalent +to -Av8plus and -Av8plusa, respectively. +.Pp +.It -bump +Warn when the assembler switches to another architecture. +.El +.Pp +The following options are available when as is configured for a mips processor. +.Pp +.Bl -tag -width Ds +.It -G Va num +This option sets the largest size of an object that can be referenced implicitly +with the +.Li gp +register. It is only accepted for targets that use ECOFF format, such as a +DECstation running Ultrix. The default value is 8. +.Pp +.It -EB +Generate \(lqbig endian\(rq format output. +.Pp +.It -EL +Generate \(lqlittle endian\(rq format output. +.Pp +.It -mips1 +.It -mips2 +.It -mips3 +.It -mips4 +.It -mips5 +.It -mips32 +.It -mips32r2 +.It -mips64 +.It -mips64r2 +Generate code for a particular mips Instruction Set Architecture level. +.Li -mips1 +is an alias for +.Li -march=r3000 , +.Li -mips2 +is an alias for +.Li -march=r6000 , +.Li -mips3 +is an alias for +.Li -march=r4000 +and +.Li -mips4 +is an alias for +.Li -march=r8000 . +.Li -mips5 , +.Li -mips32 , +.Li -mips32r2 , +.Li -mips64 , +and +.Li -mips64r2 +correspond to generic +.Li MIPS V , +.Li MIPS32 , +.Li MIPS32 Release 2 , +.Li MIPS64 , +and +.Li MIPS64 Release 2 +ISA processors, respectively. +.Pp +.It -march= Va CPU +Generate code for a particular mips cpu. +.Pp +.It -mtune= Va cpu +Schedule and tune for a particular mips cpu. +.Pp +.It -mfix7000 +.It -mno-fix7000 +Cause nops to be inserted if the read of the destination register of an mfhi +or mflo instruction occurs in the following two instructions. +.Pp +.It -mdebug +.It -no-mdebug +Cause stabs-style debugging output to go into an ECOFF-style .mdebug section +instead of the standard ELF .stabs sections. +.Pp +.It -mpdr +.It -mno-pdr +Control generation of +.Li .pdr +sections. +.Pp +.It -mgp32 +.It -mfp32 +The register sizes are normally inferred from the ISA and ABI, but these flags +force a certain group of registers to be treated as 32 bits wide at all times. +.Li -mgp32 +controls the size of general-purpose registers and +.Li -mfp32 +controls the size of floating-point registers. +.Pp +.It -mips16 +.It -no-mips16 +Generate code for the MIPS 16 processor. This is equivalent to putting +.Li .set mips16 +at the start of the assembly file. +.Li -no-mips16 +turns off this option. +.Pp +.It -msmartmips +.It -mno-smartmips +Enables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent +to putting +.Li .set smartmips +at the start of the assembly file. +.Li -mno-smartmips +turns off this option. +.Pp +.It -mips3d +.It -no-mips3d +Generate code for the MIPS-3D Application Specific Extension. This tells the +assembler to accept MIPS-3D instructions. +.Li -no-mips3d +turns off this option. +.Pp +.It -mdmx +.It -no-mdmx +Generate code for the MDMX Application Specific Extension. This tells the +assembler to accept MDMX instructions. +.Li -no-mdmx +turns off this option. +.Pp +.It -mdsp +.It -mno-dsp +Generate code for the DSP Release 1 Application Specific Extension. This tells +the assembler to accept DSP Release 1 instructions. +.Li -mno-dsp +turns off this option. +.Pp +.It -mdspr2 +.It -mno-dspr2 +Generate code for the DSP Release 2 Application Specific Extension. This option +implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. +.Li -mno-dspr2 +turns off this option. +.Pp +.It -mmt +.It -mno-mt +Generate code for the MT Application Specific Extension. This tells the assembler +to accept MT instructions. +.Li -mno-mt +turns off this option. +.Pp +.It --construct-floats +.It --no-construct-floats +The +.Li --no-construct-floats +option disables the construction of double width floating point constants +by loading the two halves of the value into the two single width floating +point registers that make up the double width register. By default +.Li --construct-floats +is selected, allowing construction of these floating point constants. +.Pp +.It --emulation= Va name +This option causes +.Xr as +to emulate +.Xr as +configured for some other target, in all respects, including output format +(choosing between ELF and ECOFF only), handling of pseudo-opcodes which may +generate debugging information or store symbol table information, and default +endianness. The available configuration names are: +.Li mipsecoff , +.Li mipself , +.Li mipslecoff , +.Li mipsbecoff , +.Li mipslelf , +.Li mipsbelf . +The first two do not alter the default endianness from that of the primary +target for which the assembler was configured; the others change the default +to little- or big-endian as indicated by the +.Li b +or +.Li l +in the name. Using +.Li -EB +or +.Li -EL +will override the endianness selection in any case. +.Pp +This option is currently supported only when the primary target +.Xr as +is configured for is a mips ELF or ECOFF target. Furthermore, the primary +target or others specified with +.Li --enable-targets=... +at configuration time must include support for the other format, if both are +to be available. For example, the Irix 5 configuration includes support for +both. +.Pp +Eventually, this option will support more configurations, with more fine-grained +control over the assembler's behavior, and will be supported for more processors. +.Pp +.It -nocpp +.Xr as +ignores this option. It is accepted for compatibility with the native tools. +.Pp +.It --trap +.It --no-trap +.It --break +.It --no-break +Control how to deal with multiplication overflow and division by zero. +.Li --trap +or +.Li --no-break +(which are synonyms) take a trap exception (and only work for Instruction +Set Architecture level 2 and higher); +.Li --break +or +.Li --no-trap +(also synonyms, and the default) take a break exception. +.Pp +.It -n +When this option is used, +.Xr as +will issue a warning every time it generates a nop instruction from a macro. +.El +.Pp +.Ss Structure of this Manual +This manual is intended to describe what you need to know to use GNU +.Xr as . +We cover the syntax expected in source files, including notation for symbols, +constants, and expressions; the directives that +.Xr as +understands; and of course how to invoke +.Xr as . +.Pp +We also cover special features in the machine specific configuration of +.Xr as , +including assembler directives. +.Pp +On the other hand, this manual is +.Em 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 +.Em not +describe the instruction set, standard mnemonics, registers or addressing +modes that are standard to a particular architecture. +.Pp +.Ss The GNU Assembler +GNU +.Xr as +is really a family of assemblers. This manual describes +.Xr as , +a member of that family which is configured for the machine specific architectures. +If you use (or have used) the GNU assembler on one architecture, you should +find a fairly similar environment when you use it on another architecture. +Each version has much in common with the others, including object file formats, +most assembler directives (often called +.Em pseudo-ops ) +and assembler syntax. +.Pp +.Xr as +is primarily intended to assemble the output of the GNU C compiler +.Li gcc +for use by the linker +.Li ld . +Nevertheless, we've tried to make +.Xr as +assemble correctly everything that other assemblers for the same machine would +assemble. +.Pp +Unlike older assemblers, +.Xr as +is designed to assemble a source program in one pass of the source file. This +has a subtle impact on the +.Li .org +directive (see Section +.Dq Org ) . +.Pp +.Ss 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.See Section +.Dq Symbol Attributes . +For the machine specific target, +.Xr as +is configured to produce ELF format object files. +.Pp +.Ss Command Line +After the program name +.Xr 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. +.Pp +.Pa -- +(two hyphens) by itself names the standard input file explicitly, as one of +the files for +.Xr as +to assemble. +.Pp +Except for +.Li -- +any command line argument that begins with a hyphen ( +.Li - ) +is an option. Each option changes the behavior of +.Xr as . +No option changes the way another option works. An option is a +.Li - +followed by one or more letters; the case of the letter is important. All +options are optional. +.Pp +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: +.Pp +.Bd -literal -offset indent +as -o my-object-file.o mumble.s +as -omy-object-file.o mumble.s +.Ed +.Pp +.Ss Input Files +We use the phrase +.Em source program , +abbreviated +.Em source , +to describe the program input to one run of +.Xr 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. +.Pp +The source program is a concatenation of the text in all the files, in the +order specified. +.Pp +Each time you run +.Xr 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.) +.Pp +You give +.Xr 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. +.Pp +If you give +.Xr as +no file names it attempts to read one input file from the +.Xr as +standard input, which is normally your terminal. You may have to type ctl-D +to tell +.Xr as +there is no more program to assemble. +.Pp +Use +.Li -- +if you need to explicitly name the standard input file in your command line. +.Pp +If the source is empty, +.Xr as +produces a small, empty object file. +.Pp +.Em Filenames and Line-numbers +.Pp +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 \(lqlogical\(rq file.See Section +.Dq Errors . +.Pp +.Em Physical files +are those files named in the command line given to +.Xr as . +.Pp +.Em 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 +.Xr as +source is itself synthesized from other files. +.Xr as +understands the +.Li # +directives emitted by the +.Li gcc +preprocessor. See also File,, +.Li .file +\&. +.Pp +.Ss Output (Object) File +Every time you run +.Xr as +it produces an output file, which is your assembly language program translated +into numbers. This file is the object file. Its default name is +.Li a.out . +You can give it another name by using the +.Op -o +option. Conventionally, object file names end with +.Pa .o . +The default name is used for historical reasons: older assemblers were capable +of assembling self-contained programs directly into a runnable program. (For +some formats, this isn't currently possible, but it can be done for the +.Li a.out +format.) +.Pp +The object file is meant for input to the linker +.Li ld . +It contains assembled program code, information to help +.Li ld +integrate the assembled program into a runnable file, and (optionally) symbolic +information for the debugger. +.Pp +.Ss Error and Warning Messages +.Xr as +may write warnings and error messages to the standard error file (usually +your terminal). This should not happen when a compiler runs +.Xr as +automatically. Warnings report an assumption made so that +.Xr as +could keep assembling a flawed program; errors report a grave problem that +stops the assembly. +.Pp +Warning messages have the format +.Pp +.Bd -literal -offset indent +file_name:NNN:Warning Message Text +.Ed +.Pp +(where +.Sy NNN +is a line number). If a logical file name has been given (see Section +.Dq File ) +it is used for the filename, otherwise the name of the current input file +is used. If a logical line number was given then it is used to calculate the +number printed, otherwise the actual line in the current source file is printed. +The message text is intended to be self explanatory (in the grand Unix tradition). +.Pp +Error messages have the format +.Bd -literal -offset indent +file_name:NNN:FATAL:Error Message Text +.Ed +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. +.Pp +.Sh Command-Line Options +This chapter describes command-line options available in +.Em all +versions of the GNU assembler; see Machine Dependencies, for options specific +to the machine specific target. +.Pp +If you are invoking +.Xr as +via the GNU C compiler, you can use the +.Li -Wa +option to pass arguments through to the assembler. The assembler arguments +must be separated from each other (and the +.Li -Wa ) +by commas. For example: +.Pp +.Bd -literal -offset indent +gcc -c -g -O -Wa,-alh,-L file.c +.Ed +.Pp +This passes two options to the assembler: +.Li -alh +(emit a listing to standard output with high-level and assembly source) and +.Li -L +(retain local symbols in the symbol table). +.Pp +Usually you do not need to use this +.Li -Wa +mechanism, since many compiler command-line options are automatically passed +to the assembler by the compiler. (You can call the GNU compiler driver with +the +.Li -v +option to see precisely what options it passes to each compilation pass, including +the assembler.) +.Pp +.Ss Enable Listings: Op -a[cdhlns] +These options enable listing output from the assembler. By itself, +.Li -a +requests high-level, assembly, and symbols listing. You can use other letters +to select specific options for the list: +.Li -ah +requests a high-level language listing, +.Li -al +requests an output-program assembly listing, and +.Li -as +requests a symbol table listing. High-level listings require that a compiler +debugging option like +.Li -g +be used, and that assembly listings ( +.Li -al ) +be requested also. +.Pp +Use the +.Li -ac +option to omit false conditionals from a listing. Any lines which are not +assembled because of a false +.Li .if +(or +.Li .ifdef , +or any other conditional), or a true +.Li .if +followed by an +.Li .else , +will be omitted from the listing. +.Pp +Use the +.Li -ad +option to omit debugging directives from the listing. +.Pp +Once you have specified one of these options, you can further control listing +output and its appearance using the directives +.Li .list , +.Li .nolist , +.Li .psize , +.Li .eject , +.Li .title , +and +.Li .sbttl . +The +.Li -an +option turns off all forms processing. If you do not request listing output +with one of the +.Li -a +options, the listing-control directives have no effect. +.Pp +The letters after +.Li -a +may be combined into one option, +.Em e.g. , +.Li -aln . +.Pp +Note if the assembler source is coming from the standard input (e.g., because +it is being created by +.Li gcc +and the +.Li -pipe +command line switch is being used) then the listing will not contain any comments +or preprocessor directives. This is because the listing code buffers input +source lines from stdin only after they have been preprocessed by the assembler. +This reduces memory usage and makes the code more efficient. +.Pp +.Ss Op --alternate +Begin in alternate macro mode, see Altmacro,, +.Li .altmacro +\&. +.Pp +.Ss Op -D +This option has no effect whatsoever, but it is accepted to make it more likely +that scripts written for other assemblers also work with +.Xr as . +.Pp +.Ss Work Faster: Op -f +.Li -f +should only be used when assembling programs written by a (trusted) compiler. +.Li -f +stops the assembler from doing whitespace and comment preprocessing on the +input file(s) before assembling them.See Section +.Dq Preprocessing . +.Pp +.Qo +.Em Warning: +if you use +.Li -f +when the files actually need to be preprocessed (if they contain comments, +for example), +.Xr as +does not work correctly. +.Qc +.Pp +.Ss Li .include Search Path: Op -I Va path +Use this option to add a +.Va path +to the list of directories +.Xr as +searches for files specified in +.Li .include +directives (see Section +.Dq Include ) . +You may use +.Op -I +as many times as necessary to include a variety of paths. The current working +directory is always searched first; after that, +.Xr as +searches any +.Li -I +directories in the same order as they were specified (left to right) on the +command line. +.Pp +.Ss Difference Tables: Op -K +On the machine specific family, this option is allowed, but has no effect. +It is permitted for compatibility with the GNU assembler on other platforms, +where it can be used to warn when the assembler alters the machine code generated +for +.Li .word +directives in difference tables. The machine specific family does not have +the addressing limitations that sometimes lead to this alteration on other +platforms. +.Pp +.Ss Include Local Symbols: Op -L +Symbols beginning with system-specific local label prefixes, typically +.Li .L +for ELF systems or +.Li L +for traditional a.out systems, are called +.Em local symbols . +See Section.Dq Symbol Names . +Normally you do not see such symbols when debugging, because they are intended +for the use of programs (like compilers) that compose assembler programs, +not for your notice. Normally both +.Xr as +and +.Li ld +discard such symbols, so you do not normally debug with them. +.Pp +This option tells +.Xr as +to retain those local symbols in the object file. Usually if you do this you +also tell the linker +.Li ld +to preserve those symbols. +.Pp +.Ss Configuring listing output: Op --listing +The listing feature of the assembler can be enabled via the command line switch +.Li -a +(see Section +.Dq a ) . +This feature combines the input source file(s) with a hex dump of the corresponding +locations in the output object file, and displays them as a listing file. +The format of this listing can be controlled by directives inside the assembler +source (i.e., +.Li .list +(see Section +.Dq List ) , +.Li .title +(see Section +.Dq Title ) , +.Li .sbttl +(see Section +.Dq Sbttl ) , +.Li .psize +(see Section +.Dq Psize ) , +and +.Li .eject +(see Section +.Dq Eject ) +and also by the following switches: +.Pp +.Bl -tag -width Ds +.It --listing-lhs-width= Li number +Sets the maximum width, in words, of the first line of the hex byte dump. +This dump appears on the left hand side of the listing output. +.Pp +.It --listing-lhs-width2= Li number +Sets the maximum width, in words, of any further lines of the hex byte dump +for a given input source line. If this value is not specified, it defaults +to being the same as the value specified for +.Li --listing-lhs-width . +If neither switch is used the default is to one. +.Pp +.It --listing-rhs-width= Li number +Sets the maximum width, in characters, of the source line that is displayed +alongside the hex dump. The default value for this parameter is 100. The source +line is displayed on the right hand side of the listing output. +.Pp +.It --listing-cont-lines= Li number +Sets the maximum number of continuation lines of hex dump that will be displayed +for a given single line of source input. The default value is 4. +.El +.Pp +.Ss Assemble in MRI Compatibility Mode: Op -M +The +.Op -M +or +.Op --mri +option selects MRI compatibility mode. This changes the syntax and pseudo-op +handling of +.Xr as +to make it compatible with the +.Li ASM68K +or the +.Li ASM960 +(depending upon the configured target) assembler from Microtec Research. The +exact nature of the MRI syntax will not be documented here; see the MRI manuals +for more information. Note in particular that the handling of macros and macro +arguments is somewhat different. The purpose of this option is to permit assembling +existing MRI assembler code using +.Xr as . +.Pp +The MRI compatibility is not complete. Certain operations of the MRI assembler +depend upon its object file format, and can not be supported using other object +file formats. Supporting these would require enhancing each object file format +individually. These are: +.Pp +.Bl -bullet +.It +global symbols in common section +.Pp +The m68k MRI assembler supports common sections which are merged by the linker. +Other object file formats do not support this. +.Xr as +handles common sections by treating them as a single common symbol. It permits +local symbols to be defined within a common section, but it can not support +global symbols, since it has no way to describe them. +.Pp +.It +complex relocations +.Pp +The MRI assemblers support relocations against a negated section address, +and relocations which combine the start addresses of two or more sections. +These are not support by other object file formats. +.Pp +.It +.Li END +pseudo-op specifying start address +.Pp +The MRI +.Li END +pseudo-op permits the specification of a start address. This is not supported +by other object file formats. The start address may instead be specified using +the +.Op -e +option to the linker, or in a linker script. +.Pp +.It +.Li IDNT , +.Li .ident +and +.Li NAME +pseudo-ops +.Pp +The MRI +.Li IDNT , +.Li .ident +and +.Li NAME +pseudo-ops assign a module name to the output file. This is not supported +by other object file formats. +.Pp +.It +.Li ORG +pseudo-op +.Pp +The m68k MRI +.Li ORG +pseudo-op begins an absolute section at a given address. This differs from +the usual +.Xr as +.Li .org +pseudo-op, which changes the location within the current section. Absolute +sections are not supported by other object file formats. The address of a +section may be assigned within a linker script. +.El +.Pp +There are some other features of the MRI assembler which are not supported +by +.Xr as , +typically either because they are difficult or because they seem of little +consequence. Some of these may be supported in future releases. +.Pp +.Bl -bullet +.It +EBCDIC strings +.Pp +EBCDIC strings are not supported. +.Pp +.It +packed binary coded decimal +.Pp +Packed binary coded decimal is not supported. This means that the +.Li DC.P +and +.Li DCB.P +pseudo-ops are not supported. +.Pp +.It +.Li FEQU +pseudo-op +.Pp +The m68k +.Li FEQU +pseudo-op is not supported. +.Pp +.It +.Li NOOBJ +pseudo-op +.Pp +The m68k +.Li NOOBJ +pseudo-op is not supported. +.Pp +.It +.Li OPT +branch control options +.Pp +The m68k +.Li OPT +branch control options--- +.Li B , +.Li BRS , +.Li BRB , +.Li BRL , +and +.Li BRW +---are ignored. +.Xr as +automatically relaxes all branches, whether forward or backward, to an appropriate +size, so these options serve no purpose. +.Pp +.It +.Li OPT +list control options +.Pp +The following m68k +.Li OPT +list control options are ignored: +.Li C , +.Li CEX , +.Li CL , +.Li CRE , +.Li E , +.Li G , +.Li I , +.Li M , +.Li MEX , +.Li MC , +.Li MD , +.Li X . +.Pp +.It +other +.Li OPT +options +.Pp +The following m68k +.Li OPT +options are ignored: +.Li NEST , +.Li O , +.Li OLD , +.Li OP , +.Li P , +.Li PCO , +.Li PCR , +.Li PCS , +.Li R . +.Pp +.It +.Li OPT +.Li D +option is default +.Pp +The m68k +.Li OPT +.Li D +option is the default, unlike the MRI assembler. +.Li OPT NOD +may be used to turn it off. +.Pp +.It +.Li XREF +pseudo-op. +.Pp +The m68k +.Li XREF +pseudo-op is ignored. +.Pp +.It +.Li .debug +pseudo-op +.Pp +The i960 +.Li .debug +pseudo-op is not supported. +.Pp +.It +.Li .extended +pseudo-op +.Pp +The i960 +.Li .extended +pseudo-op is not supported. +.Pp +.It +.Li .list +pseudo-op. +.Pp +The various options of the i960 +.Li .list +pseudo-op are not supported. +.Pp +.It +.Li .optimize +pseudo-op +.Pp +The i960 +.Li .optimize +pseudo-op is not supported. +.Pp +.It +.Li .output +pseudo-op +.Pp +The i960 +.Li .output +pseudo-op is not supported. +.Pp +.It +.Li .setreal +pseudo-op +.Pp +The i960 +.Li .setreal +pseudo-op is not supported. +.Pp +.El +.Ss Dependency Tracking: Op --MD +.Xr as +can generate a dependency file for the file it creates. This file consists +of a single rule suitable for +.Li make +describing the dependencies of the main source file. +.Pp +The rule is written to the file named in its argument. +.Pp +This feature is used in the automatic updating of makefiles. +.Pp +.Ss Name the Object File: Op -o +There is always one object file output when you run +.Xr as . +By default it has the name +.Pa a.out . +You use this option (which takes exactly one filename) to give the object +file a different name. +.Pp +Whatever the object file is called, +.Xr as +overwrites any existing file of the same name. +.Pp +.Ss Join Data and Text Sections: Op -R +.Op -R +tells +.Xr 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. (See Section +.Dq Sections . ) +.Pp +When you specify +.Op -R +it would be possible to generate shorter address displacements (because we +do not have to cross between text and data section). We refrain from doing +this simply for compatibility with older versions of +.Xr as . +In future, +.Op -R +may work this way. +.Pp +When +.Xr as +is configured for COFF or ELF output, this option is only useful if you use +sections named +.Li .text +and +.Li .data . +.Pp +.Ss Display Assembly Statistics: Op --statistics +Use +.Li --statistics +to display two statistics about the resources used by +.Xr as : +the maximum amount of space allocated during the assembly (in bytes), and +the total execution time taken for the assembly (in cpu seconds). +.Pp +.Ss Compatible Output: Op --traditional-format +For some targets, the output of +.Xr as +is different in some ways from the output of some existing assembler. This +switch requests +.Xr as +to use the traditional format instead. +.Pp +For example, it disables the exception frame optimizations which +.Xr as +normally does by default on +.Li gcc +output. +.Pp +.Ss Announce Version: Op -v +You can find out what version of as is running by including the option +.Li -v +(which you can also spell as +.Li -version ) +on the command line. +.Pp +.Ss Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings +.Xr as +should never give a warning or error message when assembling compiler output. +But programs written by people often cause +.Xr as +to give a warning that a particular assumption was made. All such warnings +are directed to the standard error file. +.Pp +If you use the +.Op -W +and +.Op --no-warn +options, no warnings are issued. This only affects the warning messages: it +does not change any particular of how +.Xr as +assembles your file. Errors, which stop the assembly, are still reported. +.Pp +If you use the +.Op --fatal-warnings +option, +.Xr as +considers files that generate warnings to be in error. +.Pp +You can switch these options off again by specifying +.Op --warn , +which causes warnings to be output as usual. +.Pp +.Ss Generate Object File in Spite of Errors: Op -Z +After an error message, +.Xr as +normally produces no output. If for some reason you are interested in object +file output even after +.Xr as +gives an error message on your program, use the +.Li -Z +option. If there are any errors, +.Xr as +continues anyways, and writes an object file after a final warning message +of the form +.Li Va n errors, Va m warnings, generating bad object file. +.Pp +.Sh Syntax +This chapter describes the machine-independent syntax allowed in a source +file. +.Xr as +syntax is similar to what many other assemblers use; it is inspired by the +BSD 4.2 assembler. +.Pp +.Ss Preprocessing +The +.Xr as +internal preprocessor: +.Bl -bullet +.It +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. +.Pp +.It +removes all comments, replacing them with a single space, or an appropriate +number of newlines. +.Pp +.It +converts character constants into the appropriate numeric values. +.El +.Pp +It does not do macro processing, include file handling, or anything else you +may get from your C compiler's preprocessor. You can do include file processing +with the +.Li .include +directive (see Section +.Dq Include ) . +You can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing +by giving the input file a +.Li .S +suffix.See Section +.Dq Overall Options . +.Pp +Excess whitespace, comments, and character constants cannot be used in the +portions of the input text that are not preprocessed. +.Pp +If the first line of an input file is +.Li #NO_APP +or if you use the +.Li -f +option, whitespace and comments are not removed from the input file. Within +an input file, you can ask for whitespace and comment removal in specific +portions of the by putting a line that says +.Li #APP +before the text that may contain whitespace or comments, and putting a line +that says +.Li #NO_APP +after this text. This feature is mainly intend to support +.Li asm +statements in compilers whose output is otherwise free of comments and whitespace. +.Pp +.Ss Whitespace +.Em 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 (see Section +.Dq Characters ) , +any whitespace means the same as exactly one space. +.Pp +.Ss Comments +There are two ways of rendering comments to +.Xr as . +In both cases the comment is equivalent to one space. +.Pp +Anything from +.Li /* +through the next +.Li */ +is a comment. This means you may not nest these comments. +.Pp +.Bd -literal -offset indent +/* + The only way to include a newline ('\en') in a comment + is to use this sort of comment. +*/ + +/* This sort of comment does not nest. */ +.Ed +.Pp +Anything from the +.Em line comment +character to the next newline is considered a comment and is ignored. The +line comment character is +.Li @ +on the ARM; +.Li # +on the i386 and x86-64; +.Li # +for Motorola PowerPC; +.Li ! +on the SPARC; see Machine Dependencies. +.Pp +To be compatible with past assemblers, lines that begin with +.Li # +have a special interpretation. Following the +.Li # +should be an absolute expression (see Section +.Dq Expressions ) : +the logical line number of the +.Em next +line. Then a string (see Section +.Dq Strings ) +is allowed: if present it is a new logical file name. The rest of the line, +if any, should be whitespace. +.Pp +If the first non-whitespace characters on the line are not numeric, the line +is ignored. (Just like a comment.) +.Pp +.Bd -literal -offset indent + # This is an ordinary comment. +# 42-6 "new_file_name" # New logical file name + # This is logical line # 36. +.Ed +This feature is deprecated, and may disappear from future versions of +.Xr as . +.Pp +.Ss Symbols +A +.Em symbol +is one or more characters chosen from the set of all letters (both upper and +lower case), digits and the three characters +.Li _.$ . +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).See Section +.Dq Symbols . +.Pp +.Ss Statements +A +.Em statement +ends at a newline character ( +.Li \en ) +or at a semicolon ( +.Li ; ) . +The newline or semicolon is considered part of the preceding statement. Newlines +and semicolons within character constants are an exception: they do not end +statements. +.Pp +It is an error to end any statement with end-of-file: the last character of +any input file should be a newline. +.Pp +An empty statement is allowed, and may include whitespace. It is ignored. +.Pp +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 +.Li . +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 +.Em instruction : +it assembles into a machine language instruction. +.Pp +A label is a symbol immediately followed by a colon ( +.Li : ) . +Whitespace before a label or after a colon is permitted, but you may not have +whitespace between a label's symbol and its colon.See Section +.Dq Labels . +.Pp +.Bd -literal -offset indent +label: .directive followed by something +another_label: # This is an empty statement. + instruction operand_1, operand_2, ... +.Ed +.Pp +.Ss Constants +A constant is a number, written so that its value is known by inspection, +without knowing any context. Like this: +.Bd -literal -offset indent + +\&.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value. +\&.ascii "Ring the bell\e7" # A string constant. +\&.octa 0x123456789abcdef0123456789ABCDEF0 # A biGNUm. +\&.float 0f-314159265358979323846264338327\e +95028841971.693993751E-40 # - pi, a flonum. + +.Ed +.Pp +.Em Character Constants +.Pp +There are two kinds of character constants. A +.Em character +stands for one character in one byte and its value may be used in numeric +expressions. String constants (properly called string +.Em literals ) +are potentially many bytes and their values may not be used in arithmetic +expressions. +.Pp +.No Strings +.Pp +A +.Em 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 +.Em escape +these characters: precede them with a backslash +.Li \e +character. For example +.Li \e\e +represents one backslash: the first +.Li \e +is an escape which tells +.Xr as +to interpret the second character literally as a backslash (which prevents +.Xr as +from recognizing the second +.Li \e +as an escape character). The complete list of escapes follows. +.Pp +.Bl -tag -width Ds +.It \eb +Mnemonic for backspace; for ASCII this is octal code 010. +.Pp +.It \ef +Mnemonic for FormFeed; for ASCII this is octal code 014. +.Pp +.It \en +Mnemonic for newline; for ASCII this is octal code 012. +.Pp +.It \er +Mnemonic for carriage-Return; for ASCII this is octal code 015. +.Pp +.It \et +Mnemonic for horizontal Tab; for ASCII this is octal code 011. +.Pp +.It \e Va digit Va digit Va 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, +.Li \e008 +has the value 010, and +.Li \e009 +the value 011. +.Pp +.It \e Li x Va hex-digits... +A hex character code. All trailing hex digits are combined. Either upper or +lower case +.Li x +works. +.Pp +.It \e\e +Represents one +.Li \e +character. +.Pp +.It \e" +Represents one +.Li " +character. Needed in strings to represent this character, because an unescaped +.Li " +would end the string. +.Pp +.It \e Va anything-else +Any other character when escaped by +.Li \e +gives a warning, but assembles as if the +.Li \e +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 +.Xr as +has no other interpretation, so +.Xr as +knows it is giving you the wrong code and warns you of the fact. +.El +.Pp +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, do +not use an escape sequence. +.Pp +.No Characters +.Pp +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 +.Li '\e\e +where the first +.Li \e +escapes the second +.Li \e . +As you can see, the quote is an acute accent, not a grave accent. A newline +(or semicolon +.Li ; ) +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. +.Xr as +assumes your character code is ASCII: +.Li 'A +means 65, +.Li 'B +means 66, and so on. +.Pp +.Em Number Constants +.Pp +.Xr as +distinguishes three kinds of numbers according to how they are stored in the +target machine. +.Em Integers +are numbers that would fit into an +.Li int +in the C language. +.Em BiGNUms +are integers, but they are stored in more than 32 bits. +.Em Flonums +are floating point numbers, described below. +.Pp +.No Integers +.Pp +A binary integer is +.Li 0b +or +.Li 0B +followed by zero or more of the binary digits +.Li 01 . +.Pp +An octal integer is +.Li 0 +followed by zero or more of the octal digits ( +.Li 01234567 ) . +.Pp +A decimal integer starts with a non-zero digit followed by zero or more digits +( +.Li 0123456789 ) . +.Pp +A hexadecimal integer is +.Li 0x +or +.Li 0X +followed by one or more hexadecimal digits chosen from +.Li 0123456789abcdefABCDEF . +.Pp +Integers have the usual values. To denote a negative integer, use the prefix +operator +.Li - +discussed under expressions (see Section +.Dq Prefix Ops ) . +.Pp +.No BiGNUms +.Pp +A +.Em 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. +.Pp +.No Flonums +.Pp +A +.Em flonum +represents a floating point number. The translation is indirect: a decimal +floating point number from the text is converted by +.Xr 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 +.Xr as +specialized to that computer. +.Pp +A flonum is written by writing (in order) +.Bl -bullet +.It +The digit +.Li 0 . +.Pp +.It +A letter, to tell +.Xr as +the rest of the number is a flonum. +.Pp +.It +An optional sign: either +.Li + +or +.Li - . +.Pp +.It +An optional +.Em integer part : +zero or more decimal digits. +.Pp +.It +An optional +.Em fractional part : +.Li . +followed by zero or more decimal digits. +.Pp +.It +An optional exponent, consisting of: +.Pp +.Bl -bullet +.It +An +.Li E +or +.Li e . +.It +Optional sign: either +.Li + +or +.Li - . +.It +One or more decimal digits. +.El +.Pp +.El +At least one of the integer part or the fractional part must be present. The +floating point number has the usual base-10 value. +.Pp +.Xr as +does all processing using integers. Flonums are computed independently of +any floating point hardware in the computer running +.Xr as . +.Pp +.Sh Sections and Relocation +.Ss Background +Roughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those +addresses is treated the same for some particular purpose. For example there +may be a \(lqread only\(rq section. +.Pp +The linker +.Li ld +reads many object files (partial programs) and combines their contents to +form a runnable program. When +.Xr as +emits an object file, the partial program is assumed to start at address 0. +.Li ld +assigns the final addresses for the partial program, so that different partial +programs do not overlap. This is actually an oversimplification, but it suffices +to explain how +.Xr as +uses sections. +.Pp +.Li 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 +.Em section . +Assigning run-time addresses to sections is called +.Em relocation . +It includes the task of adjusting mentions of object-file addresses so they +refer to the proper run-time addresses. +.Pp +An object file written by +.Xr as +has at least three sections, any of which may be empty. These are named +.Em text , +.Em data +and +.Em bss +sections. +.Pp +.Xr as +can also generate whatever other named sections you specify using the +.Li .section +directive (see Section +.Dq Section ) . +If you do not use any directives that place output in the +.Li .text +or +.Li .data +sections, these sections still exist, but are empty. +.Pp +Within the object file, the text section starts at address +.Li 0 , +the data section follows, and the bss section follows the data section. +.Pp +To let +.Li ld +know which data changes when the sections are relocated, and how to change +that data, +.Xr as +also writes to the object file details of the relocation needed. To perform +relocation +.Li ld +must know, each time an address in the object file is mentioned: +.Bl -bullet +.It +Where in the object file is the beginning of this reference to an address? +.It +How long (in bytes) is this reference? +.It +Which section does the address refer to? What is the numeric value of +.Bd -filled -offset indent +( +.Va address ) +\-( +.Va start-address of section ) ? +.Ed +.It +Is the reference to an address \(lqProgram-Counter relative\(rq? +.El +.Pp +In fact, every address +.Xr as +ever uses is expressed as +.Bd -filled -offset indent +( +.Va section ) ++ ( +.Va offset into section ) +.Ed +Further, most expressions +.Xr as +computes have this section-relative nature. +.Pp +In this manual we use the notation { +.Va secname +.Va N +}to mean \(lqoffset +.Va N +into section +.Va secname +\&.\(rq +.Pp +Apart from text, data and bss sections you need to know about the +.Em absolute +section. When +.Li ld +mixes partial programs, addresses in the absolute section remain unchanged. +For example, address +.Li {absolute 0} +is \(lqrelocated\(rq to run-time address 0 by +.Li ld . +Although the linker never arranges two partial programs' data sections with +overlapping addresses after linking, +.Em by definition +their absolute sections must overlap. Address +.Li {absolute 239} +in one part of a program is always the same address when the program is running +as address +.Li {absolute 239} +in any other part of the program. +.Pp +The idea of sections is extended to the +.Em undefined +section. Any address whose section is unknown at assembly time is by definition +rendered {undefined +.Va U +}---where +.Va U +is 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 +.Em undefined . +.Pp +By analogy the word +.Em section +is used to describe groups of sections in the linked program. +.Li ld +puts all partial programs' text sections in contiguous addresses in the linked +program. It is customary to refer to the +.Em text section +of a program, meaning all the addresses of all partial programs' text sections. +Likewise for data and bss sections. +.Pp +Some sections are manipulated by +.Li ld ; +others are invented for use of +.Xr as +and have no meaning except during assembly. +.Pp +.Ss Linker Sections +.Li ld +deals with just four kinds of sections, summarized below. +.Pp +.Bl -tag -width Ds +.It named sections +These sections hold your program. +.Xr as +and +.Li ld +treat them as separate but equal sections. Anything you can say of one section +is true of 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 contains 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. +.Pp +.It bss section +This section contains zeroed bytes when your program begins running. It is +used to hold uninitialized 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. +.Pp +.It absolute section +Address 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is +useful if you want to refer to an address that +.Li ld +must not change when relocating. In this sense we speak of absolute addresses +being \(lqunrelocatable\(rq: they do not change during relocation. +.Pp +.It undefined section +This \(lqsection\(rq is a catch-all for address references to objects not in the preceding +sections. +.El +.Pp +An idealized example of three relocatable sections follows. The example uses +the traditional section names +.Li .text +and +.Li .data . +Memory addresses are on the horizontal axis. +.Pp +.Bd -literal -offset indent + +-----+----+--+ +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 ... +.Ed +.Pp +.Ss Assembler Internal Sections +These sections are meant only for the internal use of +.Xr as . +They have no meaning at run-time. You do not really need to know about these +sections for most purposes; but they can be mentioned in +.Xr as +warning messages, so it might be helpful to have an idea of their meanings +to +.Xr as . +These sections are used to permit the value of every expression in your assembly +language program to be a section-relative address. +.Pp +.Bl -tag -width Ds +.It ASSEMBLER-INTERNAL-LOGIC-ERROR! +An internal assembler logic error has been found. This means there is a bug +in the assembler. +.Pp +.It 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. +.El +.Pp +.Ss Sub-Sections +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. +.Xr as +allows you to use +.Em subsections +for this purpose. Within each section, there can be numbered subsections with +values from 0 to 8192. Objects assembled into the same subsection go into +the object file together with other objects in the same subsection. 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 +.Li .text 0 +before each section of code being output, and a +.Li .text 1 +before each group of constants being output. +.Pp +Subsections are optional. If you do not use subsections, everything goes in +subsection number zero. +.Pp +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; +.Li ld +and other programs that manipulate object files 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. +.Pp +To specify which subsection you want subsequent statements assembled into, +use a numeric argument to specify it, in a +.Li .text Va expression +or a +.Li .data Va expression +statement. You can also use the +.Li .subsection +directive (see Section +.Dq SubSection ) +to specify a subsection: +.Li .subsection Va expression . +.Va Expression +should be an absolute expression (see Section +.Dq Expressions ) . +If you just say +.Li .text +then +.Li .text 0 +is assumed. Likewise +.Li .data +means +.Li .data 0 . +Assembly begins in +.Li text 0 . +For instance: +.Bd -literal -offset indent +\&.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 (*)." +.Ed +.Pp +Each section has a +.Em location counter +incremented by one for every byte assembled into that section. Because subsections +are merely a convenience restricted to +.Xr as +there is no concept of a subsection location counter. There is no way to directly +manipulate a location counter---but the +.Li .align +directive changes it, and any label definition captures its current value. +The location counter of the section where statements are being assembled is +said to be the +.Em active +location counter. +.Pp +.Ss 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. +.Pp +The +.Li .lcomm +pseudo-op defines a symbol in the bss section; see Lcomm,, +.Li .lcomm +\&. +.Pp +The +.Li .comm +pseudo-op may be used to declare a common symbol, which is another form of +uninitialized symbol; see Comm,, +.Li .comm +\&. +.Pp +.Sh 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. +.Pp +.Qo +.Em Warning: +.Xr as +does not place symbols in the object file in the same order they were declared. +This may break some debuggers. +.Qc +.Pp +.Ss Labels +A +.Em label +is written as a symbol immediately followed by a colon +.Li : . +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. +.Pp +.Ss Giving Symbols Other Values +A symbol can be given an arbitrary value by writing a symbol, followed by +an equals sign +.Li = , +followed by an expression (see Section +.Dq Expressions ) . +This is equivalent to using the +.Li .set +directive.See Section +.Dq Set . +In the same way, using a double equals sign +.Li = +.Li = +here represents an equivalent of the +.Li .eqv +directive.See Section +.Dq Eqv . +.Pp +.Ss Symbol Names +Symbol names begin with a letter or with one of +.Li ._ . +On most machines, you can also use +.Li $ +in symbol names; exceptions are noted in Machine Dependencies. That character +may be followed by any string of digits, letters, dollar signs (unless otherwise +noted for a particular target machine), and underscores. +.Pp +Case of letters is significant: +.Li foo +is a different symbol name than +.Li Foo . +.Pp +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. +.Pp +.Em Local Symbol Names +.Pp +A local symbol is any symbol beginning with certain local label prefixes. +By default, the local label prefix is +.Li .L +for ELF systems or +.Li L +for traditional a.out systems, but each target may have its own set of local +label prefixes. +.Pp +Local symbols are defined and used within the assembler, but they are normally +not saved in object files. Thus, they are not visible when debugging. You +may use the +.Li -L +option (see Section +.Dq L ) +to retain the local symbols in the object files. +.Pp +.Em Local Labels +.Pp +Local labels help compilers and programmers use names temporarily. They create +symbols which are guaranteed to be unique over the entire scope of the input +source code and which can be referred to by a simple notation. To define a +local label, write a label of the form +.Li Sy N: +(where +.Sy N +represents any positive integer). To refer to the most recent previous definition +of that label write +.Li Sy Nb , +using the same number as when you defined the label. To refer to the next +definition of a local label, write +.Li Sy Nf +---the +.Li b +stands for \(lqbackwards\(rq and the +.Li f +stands for \(lqforwards\(rq. +.Pp +There is no restriction on how you can use these labels, and you can reuse +them too. So that it is possible to repeatedly define the same local label +(using the same number +.Li Sy N ) , +although you can only refer to the most recently defined local label of that +number (for a backwards reference) or the next definition of a specific local +label for a forward reference. It is also worth noting that the first 10 local +labels ( +.Li Sy 0: +\&....Li Sy 9: ) +are implemented in a slightly more efficient manner than the others. +.Pp +Here is an example: +.Pp +.Bd -literal -offset indent +1: branch 1f +2: branch 1b +1: branch 2f +2: branch 1b +.Ed +.Pp +Which is the equivalent of: +.Pp +.Bd -literal -offset indent +label_1: branch label_3 +label_2: branch label_1 +label_3: branch label_4 +label_4: branch label_3 +.Ed +.Pp +Local label names are only a notational device. They are immediately transformed +into more conventional symbol names before the assembler uses them. The symbol +names are stored in the symbol table, appear in error messages, and are optionally +emitted to the object file. The names are constructed using these parts: +.Pp +.Bl -tag -width Ds +.It Em local label prefix +All local symbols begin with the system-specific local label prefix. Normally +both +.Xr as +and +.Li ld +forget symbols that start with the local label prefix. These labels are used +for symbols you are never intended to see. If you use the +.Li -L +option then +.Xr as +retains these symbols in the object file. If you also instruct +.Li ld +to retain these symbols, you may use them in debugging. +.Pp +.It Va number +This is the number that was used in the local label definition. So if the +label is written +.Li 55: +then the number is +.Li 55 . +.Pp +.It Li C-B +This unusual character is included so you do not accidentally invent a symbol +of the same name. The character has ASCII value of +.Li \e002 +(control-B). +.Pp +.It Em ordinal number +This is a serial number to keep the labels distinct. The first definition +of +.Li 0: +gets the number +.Li 1 . +The 15th definition of +.Li 0: +gets the number +.Li 15 , +and so on. Likewise the first definition of +.Li 1: +gets the number +.Li 1 +and its 15th definition gets +.Li 15 +as well. +.El +.Pp +So for example, the first +.Li 1: +may be named +.Li .L1 Li C-B1 , +and the 44th +.Li 3: +may be named +.Li .L3 Li C-B44 . +.Pp +.Em Dollar Local Labels +.Pp +.Li as +also supports an even more local form of local labels called dollar labels. +These labels go out of scope (i.e., they become undefined) as soon as a non-local +label is defined. Thus they remain valid for only a small region of the input +source code. Normal local labels, by contrast, remain in scope for the entire +file, or until they are redefined by another occurrence of the same local +label. +.Pp +Dollar labels are defined in exactly the same way as ordinary local labels, +except that instead of being terminated by a colon, they are terminated by +a dollar sign, e.g., +.Li Sy 55$ . +.Pp +They can also be distinguished from ordinary local labels by their transformed +names which use ASCII character +.Li \e001 +(control-A) as the magic character to distinguish them from ordinary labels. +For example, the fifth definition of +.Li 6$ +may be named +.Li .L6 Li C-A5 . +.Pp +.Ss The Special Dot Symbol +The special symbol +.Li . +refers to the current address that +.Xr as +is assembling into. Thus, the expression +.Li melvin: .long . +defines +.Li melvin +to contain its own address. Assigning a value to +.Li . +is treated the same as a +.Li .org +directive. Thus, the expression +.Li .=.+4 +is the same as saying +.Li .space 4 . +.Pp +.Ss Symbol Attributes +Every symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending +on output format, symbols can also have auxiliary attributes. The detailed +definitions are in +.Pa a.out.h . +.Pp +If you use a symbol without defining it, +.Xr 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. +.Pp +.Em Value +.Pp +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 +.Li ld +changes section base addresses during linking. Absolute symbols' values do +not change during linking: that is why they are called absolute. +.Pp +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 file, and +.Li ld +tries to determine its value from other files linked into the same program. +You make this kind of symbol simply by mentioning a symbol name without defining +it. A non-zero value represents a +.Li .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. +.Pp +.Em Type +.Pp +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. +.Pp +.Sh Expressions +An +.Em expression +specifies an address or numeric value. Whitespace may precede and/or follow +an expression. +.Pp +The result of an expression must be an absolute number, or else an offset +into a particular section. If an expression is not absolute, and there is +not enough information when +.Xr as +sees the expression to know its section, a second pass over the source program +might be necessary to interpret the expression---but the second pass is currently +not implemented. +.Xr as +aborts with an error message in this situation. +.Pp +.Ss 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 +.Xr as +assumes a value of (absolute) 0. This is compatible with other assemblers. +.Pp +.Ss Integer Expressions +An +.Em integer expression +is one or more +.Em arguments +delimited by +.Em operators . +.Pp +.Em Arguments +.Pp +.Em Arguments +are symbols, numbers or subexpressions. In other contexts arguments are sometimes +called \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the +\(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to +refer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only +to machine instruction operands. +.Pp +Symbols are evaluated to yield { +.Va section +.Va NNN +}where +.Va section +is one of text, data, bss, absolute, or undefined. +.Va NNN +is a signed, 2's complement 32 bit integer. +.Pp +Numbers are usually integers. +.Pp +A number can be a flonum or biGNUm. In this case, you are warned that only +the low order 32 bits are used, and +.Xr as +pretends these 32 bits are an integer. You may write integer-manipulating +instructions that act on exotic constants, compatible with other assemblers. +.Pp +Subexpressions are a left parenthesis +.Li ( +followed by an integer expression, followed by a right parenthesis +.Li ) ; +or a prefix operator followed by an argument. +.Pp +.Em Operators +.Pp +.Em Operators +are arithmetic functions, like +.Li + +or +.Li % . +Prefix operators are followed by an argument. Infix operators appear between +their arguments. Operators may be preceded and/or followed by whitespace. +.Pp +.Em Prefix Operator +.Pp +.Xr as +has the following +.Em prefix operators . +They each take one argument, which must be absolute. +.Pp +.Bl -tag -width Ds +.It - +.Em Negation . +Two's complement negation. +.It ~ +.Em Complementation . +Bitwise not. +.El +.Pp +.Em Infix Operators +.Pp +.Em Infix operators +take two arguments, one on either side. Operators have precedence, but operations +with equal precedence are performed left to right. Apart from +.Li + +or +.Op - , +both arguments must be absolute, and the result is absolute. +.Pp +.Bl -enum +.It +Highest Precedence +.Pp +.Bl -tag -width Ds +.It * +.Em Multiplication . +.Pp +.It / +.Em Division . +Truncation is the same as the C operator +.Li / +.Pp +.It % +.Em Remainder . +.Pp +.It << +.Em Shift Left . +Same as the C operator +.Li << . +.Pp +.It >> +.Em Shift Right . +Same as the C operator +.Li >> . +.El +.Pp +.It +Intermediate precedence +.Pp +.Bl -tag -width Ds +.It | +.Pp +.Em Bitwise Inclusive Or . +.Pp +.It & +.Em Bitwise And . +.Pp +.It ^ +.Em Bitwise Exclusive Or . +.Pp +.It ! +.Em Bitwise Or Not . +.El +.Pp +.It +Low Precedence +.Pp +.Bl -tag -width Ds +.It + +.Em Addition . +If either argument is absolute, the result has the section of the other argument. +You may not add together arguments from different sections. +.Pp +.It - +.Em Subtraction . +If the right argument is absolute, the result has the section of the left +argument. If both arguments are in the same section, the result is absolute. +You may not subtract arguments from different sections. +.Pp +.It == +.Em Is Equal To +.It <> +.It != +.Em Is Not Equal To +.It < +.Em Is Less Than +.It > +.Em Is Greater Than +.It >= +.Em Is Greater Than Or Equal To +.It <= +.Em Is Less Than Or Equal To +.Pp +The comparison operators can be used as infix operators. A true results has +a value of -1 whereas a false result has a value of 0. Note, these operators +perform signed comparisons. +.El +.Pp +.It +Lowest Precedence +.Pp +.Bl -tag -width Ds +.It && +.Em Logical And . +.Pp +.It || +.Em Logical Or . +.Pp +These two logical operations can be used to combine the results of sub expressions. +Note, unlike the comparison operators a true result returns a value of 1 but +a false results does still return 0. Also note that the logical or operator +has a slightly lower precedence than logical and. +.Pp +.El +.El +In short, it's only meaningful to add or subtract the +.Em offsets +in an address; you can only have a defined section in one of the two arguments. +.Pp +.Sh Assembler Directives +All assembler directives have names that begin with a period ( +.Li . ) . +The rest of the name is letters, usually in lower case. +.Pp +This chapter discusses directives that are available regardless of the target +machine configuration for the GNU assembler. +.Pp +.Ss Li .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 +.Xr as +to quit also. One day +.Li .abort +will not be supported. +.Pp +.Ss Li .align Va abs-expr, Va abs-expr, Va abs-expr +Pad the location counter (in the current subsection) to a particular storage +boundary. The first expression (which must be absolute) is the alignment required, +as described below. +.Pp +The second expression (also absolute) gives the fill value to be stored in +the padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section +is marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. +.Pp +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after +the required alignment; this can be useful if you want the alignment to be +filled with no-op instructions when appropriate. +.Pp +The way the required alignment is specified varies from system to system. +For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc, +tic4x, tic80 and xtensa, the first expression is the alignment request in +bytes. For example +.Li .align 8 +advances the location counter until it is a multiple of 8. If the location +counter is already a multiple of 8, no change is needed. For the tic54x, the +first expression is the alignment request in words. +.Pp +For other systems, including the i386 using a.out format, and the arm and +strongarm, it is the number of low-order zero bits the location counter must +have after advancement. For example +.Li .align 3 +advances the location counter until it a multiple of 8. If the location counter +is already a multiple of 8, no change is needed. +.Pp +This inconsistency is due to the different behaviors of the various native +assemblers for these systems which GAS must emulate. GAS also provides +.Li .balign +and +.Li .p2align +directives, described later, which have a consistent behavior across all architectures +(but are specific to GAS). +.Pp +.Ss Li .ascii " Va string"... +.Li .ascii +expects zero or more string literals (see Section +.Dq Strings ) +separated by commas. It assembles each string (with no automatic trailing +zero byte) into consecutive addresses. +.Pp +.Ss Li .asciz " Va string"... +.Li .asciz +is just like +.Li .ascii , +but each string is followed by a zero byte. The \(lqz\(rq in +.Li .asciz +stands for \(lqzero\(rq. +.Pp +.Ss Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr +Pad the location counter (in the current subsection) to a particular storage +boundary. The first expression (which must be absolute) is the alignment request +in bytes. For example +.Li .balign 8 +advances the location counter until it is a multiple of 8. If the location +counter is already a multiple of 8, no change is needed. +.Pp +The second expression (also absolute) gives the fill value to be stored in +the padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section +is marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. +.Pp +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after +the required alignment; this can be useful if you want the alignment to be +filled with no-op instructions when appropriate. +.Pp +The +.Li .balignw +and +.Li .balignl +directives are variants of the +.Li .balign +directive. The +.Li .balignw +directive treats the fill pattern as a two byte word value. The +.Li .balignl +directives treats the fill pattern as a four byte longword value. For example, +.Li .balignw 4,0x368d +will align to a multiple of 4. If it skips two bytes, they will be filled +in with the value 0x368d (the exact placement of the bytes depends upon the +endianness of the processor). If it skips 1 or 3 bytes, the fill value is +undefined. +.Pp +.Ss Li .byte Va expressions +.Li .byte +expects zero or more expressions, separated by commas. Each expression is +assembled into the next byte. +.Pp +.Ss Li .comm Va symbol , Va length +.Li .comm +declares a common symbol named +.Va symbol . +When linking, a common symbol in one object file may be merged with a defined +or common symbol of the same name in another object file. If +.Li ld +does not see a definition for the symbol--just one or more common symbols--then +it will allocate +.Va length +bytes of uninitialized memory. +.Va length +must be an absolute expression. If +.Li ld +sees multiple common symbols with the same name, and they do not all have +the same size, it will allocate space using the largest size. +.Pp +When using ELF, the +.Li .comm +directive takes an optional third argument. This is the desired alignment +of the symbol, specified as a byte boundary (for example, an alignment of +16 means that the least significant 4 bits of the address should be zero). +The alignment must be an absolute expression, and it must be a power of two. +If +.Li ld +allocates uninitialized memory for the common symbol, it will use the alignment +when placing the symbol. If no alignment is specified, +.Xr as +will set the alignment to the largest power of two less than or equal to the +size of the symbol, up to a maximum of 16. +.Pp +.Ss Li .cfi_startproc [simple] +.Li .cfi_startproc +is used at the beginning of each function that should have an entry in +.Li .eh_frame . +It initializes some internal data structures. Don't forget to close the function +by +.Li .cfi_endproc . +.Pp +Unless +.Li .cfi_startproc +is used along with parameter +.Li simple +it also emits some architecture dependent initial CFI instructions. +.Ss Li .cfi_endproc +.Li .cfi_endproc +is used at the end of a function where it closes its unwind entry previously +opened by +.Li .cfi_startproc , +and emits it to +.Li .eh_frame . +.Pp +.Ss Li .cfi_personality Va encoding [, Va exp] +.Li .cfi_personality +defines personality routine and its encoding. +.Va encoding +must be a constant determining how the personality should be encoded. If it +is 255 ( +.Li DW_EH_PE_omit ) , +second argument is not present, otherwise second argument should be a constant +or a symbol name. When using indirect encodings, the symbol provided should +be the location where personality can be loaded from, not the personality +routine itself. The default after +.Li .cfi_startproc +is +.Li .cfi_personality 0xff , +no personality routine. +.Pp +.Ss Li .cfi_lsda Va encoding [, Va exp] +.Li .cfi_lsda +defines LSDA and its encoding. +.Va encoding +must be a constant determining how the LSDA should be encoded. If it is 255 +( +.Li DW_EH_PE_omit ) , +second argument is not present, otherwise second argument should be a constant +or a symbol name. The default after +.Li .cfi_startproc +is +.Li .cfi_lsda 0xff , +no LSDA. +.Pp +.Ss Li .cfi_def_cfa Va register, Va offset +.Li .cfi_def_cfa +defines a rule for computing CFA as: +.Em take address from Va register and add Va offset to it . +.Pp +.Ss Li .cfi_def_cfa_register Va register +.Li .cfi_def_cfa_register +modifies a rule for computing CFA. From now on +.Va register +will be used instead of the old one. Offset remains the same. +.Pp +.Ss Li .cfi_def_cfa_offset Va offset +.Li .cfi_def_cfa_offset +modifies a rule for computing CFA. Register remains the same, but +.Va offset +is new. Note that it is the absolute offset that will be added to a defined +register to compute CFA address. +.Pp +.Ss Li .cfi_adjust_cfa_offset Va offset +Same as +.Li .cfi_def_cfa_offset +but +.Va offset +is a relative value that is added/substracted from the previous offset. +.Pp +.Ss Li .cfi_offset Va register, Va offset +Previous value of +.Va register +is saved at offset +.Va offset +from CFA. +.Pp +.Ss Li .cfi_rel_offset Va register, Va offset +Previous value of +.Va register +is saved at offset +.Va offset +from the current CFA register. This is transformed to +.Li .cfi_offset +using the known displacement of the CFA register from the CFA. This is often +easier to use, because the number will match the code it's annotating. +.Pp +.Ss Li .cfi_register Va register1, Va register2 +Previous value of +.Va register1 +is saved in register +.Va register2 . +.Pp +.Ss Li .cfi_restore Va register +.Li .cfi_restore +says that the rule for +.Va register +is now the same as it was at the beginning of the function, after all initial +instruction added by +.Li .cfi_startproc +were executed. +.Pp +.Ss Li .cfi_undefined Va register +From now on the previous value of +.Va register +can't be restored anymore. +.Pp +.Ss Li .cfi_same_value Va register +Current value of +.Va register +is the same like in the previous frame, i.e. no restoration needed. +.Pp +.Ss Li .cfi_remember_state, +First save all current rules for all registers by +.Li .cfi_remember_state , +then totally screw them up by subsequent +.Li .cfi_* +directives and when everything is hopelessly bad, use +.Li .cfi_restore_state +to restore the previous saved state. +.Pp +.Ss Li .cfi_return_column Va register +Change return column +.Va register , +i.e. the return address is either directly in +.Va register +or can be accessed by rules for +.Va register . +.Pp +.Ss Li .cfi_signal_frame +Mark current function as signal trampoline. +.Pp +.Ss Li .cfi_window_save +SPARC register window has been saved. +.Pp +.Ss Li .cfi_escape Va expression[, ...] +Allows the user to add arbitrary bytes to the unwind info. One might use this +to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet +support. +.Pp +.Ss Li .file Va fileno Va filename +When emitting dwarf2 line number information +.Li .file +assigns filenames to the +.Li .debug_line +file name table. The +.Va fileno +operand should be a unique positive integer to use as the index of the entry +in the table. The +.Va filename +operand is a C string literal. +.Pp +The detail of filename indices is exposed to the user because the filename +table is shared with the +.Li .debug_info +section of the dwarf2 debugging information, and thus the user must know the +exact indices that table entries will have. +.Pp +.Ss Li .loc Va fileno Va lineno [ Va column] [ Va options] +The +.Li .loc +directive will add row to the +.Li .debug_line +line number matrix corresponding to the immediately following assembly instruction. +The +.Va fileno , +.Va lineno , +and optional +.Va column +arguments will be applied to the +.Li .debug_line +state machine before the row is added. +.Pp +The +.Va options +are a sequence of the following tokens in any order: +.Pp +.Bl -tag -width Ds +.It basic_block +This option will set the +.Li basic_block +register in the +.Li .debug_line +state machine to +.Li true . +.Pp +.It prologue_end +This option will set the +.Li prologue_end +register in the +.Li .debug_line +state machine to +.Li true . +.Pp +.It epilogue_begin +This option will set the +.Li epilogue_begin +register in the +.Li .debug_line +state machine to +.Li true . +.Pp +.It is_stmt Va value +This option will set the +.Li is_stmt +register in the +.Li .debug_line +state machine to +.Li value , +which must be either 0 or 1. +.Pp +.It isa Va value +This directive will set the +.Li isa +register in the +.Li .debug_line +state machine to +.Va value , +which must be an unsigned integer. +.Pp +.El +.Ss Li .loc_mark_blocks Va enable +The +.Li .loc_mark_blocks +directive makes the assembler emit an entry to the +.Li .debug_line +line number matrix with the +.Li basic_block +register in the state machine set whenever a code label is seen. The +.Va enable +argument should be either 1 or 0, to enable or disable this function respectively. +.Pp +.Ss Li .data Va subsection +.Li .data +tells +.Xr as +to assemble the following statements onto the end of the data subsection numbered +.Va subsection +(which is an absolute expression). If +.Va subsection +is omitted, it defaults to zero. +.Pp +.Ss Li .double Va flonums +.Li .double +expects zero or more flonums, separated by commas. It assembles floating point +numbers. +.Pp +.Ss Li .eject +Force a page break at this point, when generating assembly listings. +.Pp +.Ss Li .else +.Li .else +is part of the +.Xr as +support for conditional assembly; see If,, +.Li .if +\&. It marks the beginning of a section of code to be assembled if the condition +for the preceding +.Li .if +was false. +.Pp +.Ss Li .elseif +.Li .elseif +is part of the +.Xr as +support for conditional assembly; see If,, +.Li .if +\&. It is shorthand for beginning a new +.Li .if +block that would otherwise fill the entire +.Li .else +section. +.Pp +.Ss Li .end +.Li .end +marks the end of the assembly file. +.Xr as +does not process anything in the file past the +.Li .end +directive. +.Pp +.Ss Li .endfunc +.Li .endfunc +marks the end of a function specified with +.Li .func . +.Pp +.Ss Li .endif +.Li .endif +is part of the +.Xr as +support for conditional assembly; it marks the end of a block of code that +is only assembled conditionally.See Section +.Dq If . +.Pp +.Ss Li .equ Va symbol, Va expression +This directive sets the value of +.Va symbol +to +.Va expression . +It is synonymous with +.Li .set ; +see Set,, +.Li .set +\&. +.Pp +.Ss Li .equiv Va symbol, Va expression +The +.Li .equiv +directive is like +.Li .equ +and +.Li .set , +except that the assembler will signal an error if +.Va symbol +is already defined. Note a symbol which has been referenced but not actually +defined is considered to be undefined. +.Pp +Except for the contents of the error message, this is roughly equivalent to +.Bd -literal -offset indent +\&.ifdef SYM +\&.err +\&.endif +\&.equ SYM,VAL +.Ed +plus it protects the symbol from later redefinition. +.Pp +.Ss Li .eqv Va symbol, Va expression +The +.Li .eqv +directive is like +.Li .equiv , +but no attempt is made to evaluate the expression or any part of it immediately. +Instead each time the resulting symbol is used in an expression, a snapshot +of its current value is taken. +.Pp +.Ss Li .err +If +.Xr as +assembles a +.Li .err +directive, it will print an error message and, unless the +.Op -Z +option was used, it will not generate an object file. This can be used to +signal an error in conditionally compiled code. +.Pp +.Ss Li .error " Va string" +Similarly to +.Li .err , +this directive emits an error, but you can specify a string that will be emitted +as the error message. If you don't specify the message, it defaults to +.Li ".error directive invoked in source file" . +See Section.Dq Errors . +.Pp +.Bd -literal -offset indent + .error "This code has not been assembled and tested." +.Ed +.Pp +.Ss Li .exitm +Exit early from the current macro definition.See Section +.Dq Macro . +.Pp +.Ss Li .extern +.Li .extern +is accepted in the source program---for compatibility with other assemblers---but +it is ignored. +.Xr as +treats all undefined symbols as external. +.Pp +.Ss Li .fail Va expression +Generates an error or a warning. If the value of the +.Va expression +is 500 or more, +.Xr as +will print a warning message. If the value is less than 500, +.Xr as +will print an error message. The message will include the value of +.Va expression . +This can occasionally be useful inside complex nested macros or conditional +assembly. +.Pp +.Ss Li .file Va string +.Li .file +tells +.Xr as +that we are about to start a new logical file. +.Va string +is the new file name. In general, the filename is recognized whether or not +it is surrounded by quotes +.Li " ; +but if you wish to specify an empty file name, you must give the quotes-- +.Li "" . +This statement may go away in future: it is only recognized to be compatible +with old +.Xr as +programs. +.Pp +.Ss Li .fill Va repeat , Va size , Va value +.Va repeat , +.Va size +and +.Va value +are absolute expressions. This emits +.Va repeat +copies of +.Va size +bytes. +.Va Repeat +may be zero or more. +.Va 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 +.Va repeat +bytes is taken from an 8-byte number. The highest order 4 bytes are zero. +The lowest order 4 bytes are +.Va value +rendered in the byte-order of an integer on the computer +.Xr as +is assembling for. Each +.Va size +bytes in a repetition is taken from the lowest order +.Va size +bytes of this number. Again, this bizarre behavior is compatible with other +people's assemblers. +.Pp +.Va size +and +.Va value +are optional. If the second comma and +.Va value +are absent, +.Va value +is assumed zero. If the first comma and following tokens are absent, +.Va size +is assumed to be 1. +.Pp +.Ss Li .float Va flonums +This directive assembles zero or more flonums, separated by commas. It has +the same effect as +.Li .single . +.Pp +.Ss Li .func Va name[, Va label] +.Li .func +emits debugging information to denote function +.Va name , +and is ignored unless the file is assembled with debugging enabled. Only +.Li --gstabs[+] +is currently supported. +.Va label +is the entry point of the function and if omitted +.Va name +prepended with the +.Li leading char +is used. +.Li leading char +is usually +.Li _ +or nothing, depending on the target. All functions are currently defined to +have +.Li void +return type. The function must be terminated with +.Li .endfunc . +.Pp +.Ss Li .global Va symbol, Li .globl Va symbol +.Li .global +makes the symbol visible to +.Li ld . +If you define +.Va symbol +in your partial program, its value is made available to other partial programs +that are linked with it. Otherwise, +.Va symbol +takes its attributes from a symbol of the same name from another file linked +into the same program. +.Pp +Both spellings ( +.Li .globl +and +.Li .global ) +are accepted, for compatibility with other assemblers. +.Pp +.Ss Li .hidden Va names +This is one of the ELF visibility directives. The other two are +.Li .internal +(see Section +.Dq Internal ) +and +.Li .protected +(see Section +.Dq Protected ) . +.Pp +This directive overrides the named symbols default visibility (which is set +by their binding: local, global or weak). The directive sets the visibility +to +.Li hidden +which means that the symbols are not visible to other components. Such symbols +are always considered to be +.Li protected +as well. +.Pp +.Ss Li .hword Va expressions +This expects zero or more +.Va expressions , +and emits a 16 bit number for each. +.Pp +This directive is a synonym for +.Li .short . +.Pp +.Ss Li .ident +This directive is used by some assemblers to place tags in object files. The +behavior of this directive varies depending on the target. When using the +a.out object file format, +.Xr as +simply accepts the directive for source-file compatibility with existing assemblers, +but does not emit anything for it. When using COFF, comments are emitted to +the +.Li .comment +or +.Li .rdata +section, depending on the target. When using ELF, comments are emitted to +the +.Li .comment +section. +.Pp +.Ss Li .if Va absolute expression +.Li .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 +.Va absolute expression ) +is non-zero. The end of the conditional section of code must be marked by +.Li .endif +(see Section +.Dq Endif ) ; +optionally, you may include code for the alternative condition, flagged by +.Li .else +(see Section +.Dq Else ) . +If you have several conditions to check, +.Li .elseif +may be used to avoid nesting blocks if/else within each subsequent +.Li .else +block. +.Pp +The following variants of +.Li .if +are also supported: +.Bl -tag -width Ds +.It .ifdef Va symbol +Assembles the following section of code if the specified +.Va symbol +has been defined. Note a symbol which has been referenced but not yet defined +is considered to be undefined. +.Pp +.It .ifb Va text +Assembles the following section of code if the operand is blank (empty). +.Pp +.It .ifc Va string1, Va string2 +Assembles the following section of code if the two strings are the same. The +strings may be optionally quoted with single quotes. If they are not quoted, +the first string stops at the first comma, and the second string stops at +the end of the line. Strings which contain whitespace should be quoted. The +string comparison is case sensitive. +.Pp +.It .ifeq Va absolute expression +Assembles the following section of code if the argument is zero. +.Pp +.It .ifeqs Va string1, Va string2 +Another form of +.Li .ifc . +The strings must be quoted using double quotes. +.Pp +.It .ifge Va absolute expression +Assembles the following section of code if the argument is greater than or +equal to zero. +.Pp +.It .ifgt Va absolute expression +Assembles the following section of code if the argument is greater than zero. +.Pp +.It .ifle Va absolute expression +Assembles the following section of code if the argument is less than or equal +to zero. +.Pp +.It .iflt Va absolute expression +Assembles the following section of code if the argument is less than zero. +.Pp +.It .ifnb Va text +Like +.Li .ifb , +but the sense of the test is reversed: this assembles the following section +of code if the operand is non-blank (non-empty). +.Pp +.It .ifnc Va string1, Va string2. +Like +.Li .ifc , +but the sense of the test is reversed: this assembles the following section +of code if the two strings are not the same. +.Pp +.It .ifndef Va symbol +.It .ifnotdef Va symbol +Assembles the following section of code if the specified +.Va symbol +has not been defined. Both spelling variants are equivalent. Note a symbol +which has been referenced but not yet defined is considered to be undefined. +.Pp +.It .ifne Va absolute expression +Assembles the following section of code if the argument is not equal to zero +(in other words, this is equivalent to +.Li .if ) . +.Pp +.It .ifnes Va string1, Va string2 +Like +.Li .ifeqs , +but the sense of the test is reversed: this assembles the following section +of code if the two strings are not the same. +.El +.Pp +.Ss Li .incbin " Va file"[, Va skip[, Va count]] +The +.Li incbin +directive includes +.Va file +verbatim at the current location. You can control the search paths used with +the +.Li -I +command-line option (see Section +.Dq Invoking ) . +Quotation marks are required around +.Va file . +.Pp +The +.Va skip +argument skips a number of bytes from the start of the +.Va file . +The +.Va count +argument indicates the maximum number of bytes to read. Note that the data +is not aligned in any way, so it is the user's responsibility to make sure +that proper alignment is provided both before and after the +.Li incbin +directive. +.Pp +.Ss Li .include " Va file" +This directive provides a way to include supporting files at specified points +in your source program. The code from +.Va file +is assembled as if it followed the point of the +.Li .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 +.Li -I +command-line option (see Section +.Dq Invoking ) . +Quotation marks are required around +.Va file . +.Pp +.Ss Li .int Va expressions +Expect zero or more +.Va expressions , +of any section, separated by commas. For each expression, emit a number that, +at run time, is the value of that expression. The byte order and bit size +of the number depends on what kind of target the assembly is for. +.Pp +.Ss Li .internal Va names +This is one of the ELF visibility directives. The other two are +.Li .hidden +(see Section +.Dq Hidden ) +and +.Li .protected +(see Section +.Dq Protected ) . +.Pp +This directive overrides the named symbols default visibility (which is set +by their binding: local, global or weak). The directive sets the visibility +to +.Li internal +which means that the symbols are considered to be +.Li hidden +(i.e., not visible to other components), and that some extra, processor specific +processing must also be performed upon the symbols as well. +.Pp +.Ss Li .irp Va symbol, Va values... +Evaluate a sequence of statements assigning different values to +.Va symbol . +The sequence of statements starts at the +.Li .irp +directive, and is terminated by an +.Li .endr +directive. For each +.Va value , +.Va symbol +is set to +.Va value , +and the sequence of statements is assembled. If no +.Va value +is listed, the sequence of statements is assembled once, with +.Va symbol +set to the null string. To refer to +.Va symbol +within the sequence of statements, use +.Va \esymbol . +.Pp +For example, assembling +.Pp +.Bd -literal -offset indent + .irp param,1,2,3 + move d\eparam,sp@- + .endr +.Ed +.Pp +is equivalent to assembling +.Pp +.Bd -literal -offset indent + move d1,sp@- + move d2,sp@- + move d3,sp@- +.Ed +.Pp +For some caveats with the spelling of +.Va symbol , +see also Macro. +.Pp +.Ss Li .irpc Va symbol, Va values... +Evaluate a sequence of statements assigning different values to +.Va symbol . +The sequence of statements starts at the +.Li .irpc +directive, and is terminated by an +.Li .endr +directive. For each character in +.Va value , +.Va symbol +is set to the character, and the sequence of statements is assembled. If no +.Va value +is listed, the sequence of statements is assembled once, with +.Va symbol +set to the null string. To refer to +.Va symbol +within the sequence of statements, use +.Va \esymbol . +.Pp +For example, assembling +.Pp +.Bd -literal -offset indent + .irpc param,123 + move d\eparam,sp@- + .endr +.Ed +.Pp +is equivalent to assembling +.Pp +.Bd -literal -offset indent + move d1,sp@- + move d2,sp@- + move d3,sp@- +.Ed +.Pp +For some caveats with the spelling of +.Va symbol , +see also the discussion atSee Section +.Dq Macro . +.Pp +.Ss Li .lcomm Va symbol , Va length +Reserve +.Va length +(an absolute expression) bytes for a local common denoted by +.Va symbol . +The section and value of +.Va symbol +are those of the new local common. The addresses are allocated in the bss +section, so that at run-time the bytes start off zeroed. +.Va Symbol +is not declared global (see Section +.Dq Global ) , +so is normally not visible to +.Li ld . +.Pp +.Ss Li .lflags +.Xr as +accepts this directive, for compatibility with other assemblers, but ignores +it. +.Pp +.Ss Li .line Va line-number +Even though this is a directive associated with the +.Li a.out +or +.Li b.out +object-code formats, +.Xr as +still recognizes it when producing COFF output, and treats +.Li .line +as though it were the COFF +.Li .ln +.Em if +it is found outside a +.Li .def +/ +.Li .endef +pair. +.Pp +Inside a +.Li .def , +.Li .line +is, instead, one of the directives used by compilers to generate auxiliary +symbol information for debugging. +.Pp +.Ss Li .linkonce [ Va type] +Mark the current section so that the linker only includes a single copy of +it. This may be used to include the same section in several different object +files, but ensure that the linker will only include it once in the final output +file. The +.Li .linkonce +pseudo-op must be used for each instance of the section. Duplicate sections +are detected based on the section name, so it should be unique. +.Pp +This directive is only supported by a few object file formats; as of this +writing, the only object file format which supports it is the Portable Executable +format used on Windows NT. +.Pp +The +.Va type +argument is optional. If specified, it must be one of the following strings. +For example: +.Bd -literal -offset indent +\&.linkonce same_size +.Ed +Not all types may be supported on all object file formats. +.Pp +.Bl -tag -width Ds +.It discard +Silently discard duplicate sections. This is the default. +.Pp +.It one_only +Warn if there are duplicate sections, but still keep only one copy. +.Pp +.It same_size +Warn if any of the duplicates have different sizes. +.Pp +.It same_contents +Warn if any of the duplicates do not have exactly the same contents. +.El +.Pp +.Ss Li .ln Va line-number +.Li .ln +is a synonym for +.Li .line . +.Pp +.Ss Li .mri Va val +If +.Va val +is non-zero, this tells +.Xr as +to enter MRI mode. If +.Va val +is zero, this tells +.Xr as +to exit MRI mode. This change affects code assembled until the next +.Li .mri +directive, or until the end of the file.See Section +.Dq M . +.Pp +.Ss Li .list +Control (in conjunction with the +.Li .nolist +directive) whether or not assembly listings are generated. These two directives +maintain an internal counter (which is zero initially). +.Li .list +increments the counter, and +.Li .nolist +decrements it. Assembly listings are generated whenever the counter is greater +than zero. +.Pp +By default, listings are disabled. When you enable them (with the +.Li -a +command line option;see Section +.Dq Invoking ) , +the initial value of the listing counter is one. +.Pp +.Ss Li .long Va expressions +.Li .long +is the same as +.Li .int . +See Section.Dq Int . +.Pp +.Ss Li .macro +The commands +.Li .macro +and +.Li .endm +allow you to define macros that generate assembly output. For example, this +definition specifies a macro +.Li sum +that puts a sequence of numbers into memory: +.Pp +.Bd -literal -offset indent + .macro sum from=0, to=5 + .long \efrom + .if \eto-\efrom + sum "(\efrom+1)",\eto + .endif + .endm +.Ed +.Pp +With that definition, +.Li SUM 0,5 +is equivalent to this assembly input: +.Pp +.Bd -literal -offset indent + .long 0 + .long 1 + .long 2 + .long 3 + .long 4 + .long 5 +.Ed +.Pp +.Bl -tag -width Ds +.It .macro Va macname +.It .macro Va macname Va macargs ... +Begin the definition of a macro called +.Va macname . +If your macro definition requires arguments, specify their names after the +macro name, separated by commas or spaces. You can qualify the macro argument +to indicate whether all invocations must specify a non-blank value (through +.Li : Li req ) , +or whether it takes all of the remaining arguments (through +.Li : Li vararg ) . +You can supply a default value for any macro argument by following the name +with +.Li = Va deflt . +You cannot define two macros with the same +.Va macname +unless it has been subject to the +.Li .purgem +directive (see Section +.Dq Purgem ) +between the two definitions. For example, these are all valid +.Li .macro +statements: +.Pp +.Bl -tag -width Ds +.It .macro comm +Begin the definition of a macro called +.Li comm , +which takes no arguments. +.Pp +.It .macro plus1 p, p1 +.It .macro plus1 p p1 +Either statement begins the definition of a macro called +.Li plus1 , +which takes two arguments; within the macro definition, write +.Li \ep +or +.Li \ep1 +to evaluate the arguments. +.Pp +.It .macro reserve_str p1=0 p2 +Begin the definition of a macro called +.Li reserve_str , +with two arguments. The first argument has a default value, but not the second. +After the definition is complete, you can call the macro either as +.Li reserve_str Va a, Va b +(with +.Li \ep1 +evaluating to +.Va a +and +.Li \ep2 +evaluating to +.Va b ) , +or as +.Li reserve_str , Va b +(with +.Li \ep1 +evaluating as the default, in this case +.Li 0 , +and +.Li \ep2 +evaluating to +.Va b ) . +.Pp +.It .macro m p1:req, p2=0, p3:vararg +Begin the definition of a macro called +.Li m , +with at least three arguments. The first argument must always have a value +specified, but not the second, which instead has a default value. The third +formal will get assigned all remaining arguments specified at invocation time. +.Pp +When you call a macro, you can specify the argument values either by position, +or by keyword. For example, +.Li sum 9,17 +is equivalent to +.Li sum to=17, from=9 . +.Pp +.El +Note that since each of the +.Va macargs +can be an identifier exactly as any other one permitted by the target architecture, +there may be occasional problems if the target hand-crafts special meanings +to certain characters when they occur in a special position. For example, +if the colon ( +.Li : ) +is generally permitted to be part of a symbol name, but the architecture specific +code special-cases it when occurring as the final character of a symbol (to +denote a label), then the macro parameter replacement code will have no way +of knowing that and consider the whole construct (including the colon) an +identifier, and check only this identifier for being the subject to parameter +substitution. So for example this macro definition: +.Pp +.Bd -literal -offset indent + .macro label l +\el: + .endm +.Ed +.Pp +might not work as expected. Invoking +.Li label foo +might not create a label called +.Li foo +but instead just insert the text +.Li \el: +into the assembler source, probably generating an error about an unrecognised +identifier. +.Pp +Similarly problems might occur with the period character ( +.Li . ) +which is often allowed inside opcode names (and hence identifier names). So +for example constructing a macro to build an opcode from a base name and a +length specifier like this: +.Pp +.Bd -literal -offset indent + .macro opcode base length + \ebase.\elength + .endm +.Ed +.Pp +and invoking it as +.Li opcode store l +will not create a +.Li store.l +instruction but instead generate some kind of error as the assembler tries +to interpret the text +.Li \ebase.\elength . +.Pp +There are several possible ways around this problem: +.Pp +.Bl -tag -width Ds +.It Insert white space +If it is possible to use white space characters then this is the simplest +solution. eg: +.Pp +.Bd -literal -offset indent + .macro label l +\el : + .endm +.Ed +.Pp +.It Use Li \e() +The string +.Li \e() +can be used to separate the end of a macro argument from the following text. +eg: +.Pp +.Bd -literal -offset indent + .macro opcode base length + \ebase\e().\elength + .endm +.Ed +.Pp +.It Use the alternate macro syntax mode +In the alternative macro syntax mode the ampersand character ( +.Li & ) +can be used as a separator. eg: +.Pp +.Bd -literal -offset indent + .altmacro + .macro label l +l&: + .endm +.Ed +.El +.Pp +Note: this problem of correctly identifying string parameters to pseudo ops +also applies to the identifiers used in +.Li .irp +(see Section +.Dq Irp ) +and +.Li .irpc +(see Section +.Dq Irpc ) +as well. +.Pp +.It .endm +Mark the end of a macro definition. +.Pp +.It .exitm +Exit early from the current macro definition. +.Pp +.It \e@ +.Xr as +maintains a counter of how many macros it has executed in this pseudo-variable; +you can copy that number to your output with +.Li \e@ , +but +.Em only within a macro definition . +.Pp +.It LOCAL Va name [ , ... ] +.Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro. +See Section.Dq Altmacro . +.El +.Pp +.Ss Li .altmacro +Enable alternate macro mode, enabling: +.Pp +.Bl -tag -width Ds +.It LOCAL Va name [ , ... ] +One additional directive, +.Li LOCAL , +is available. It is used to generate a string replacement for each of the +.Va name +arguments, and replace any instances of +.Va name +in each macro expansion. The replacement string is unique in the assembly, +and different for each separate macro expansion. +.Li LOCAL +allows you to write macros that define symbols, without fear of conflict between +separate macro expansions. +.Pp +.It String delimiters +You can write strings delimited in these other ways besides +.Li " Va string" : +.Pp +.Bl -tag -width Ds +.It ' Va string' +You can delimit strings with single-quote characters. +.Pp +.It < Va string> +You can delimit strings with matching angle brackets. +.El +.Pp +.It single-character string escape +To include any single character literally in a string (even if the character +would otherwise have some special meaning), you can prefix the character with +.Li ! +(an exclamation mark). For example, you can write +.Li <4.3 !> 5.4!!> +to get the literal text +.Li 4.3 > 5.4! . +.Pp +.It Expression results as strings +You can write +.Li % Va expr +to evaluate the expression +.Va expr +and use the result as a string. +.El +.Pp +.Ss Li .noaltmacro +Disable alternate macro mode.See Section +.Dq Altmacro . +.Pp +.Ss Li .nolist +Control (in conjunction with the +.Li .list +directive) whether or not assembly listings are generated. These two directives +maintain an internal counter (which is zero initially). +.Li .list +increments the counter, and +.Li .nolist +decrements it. Assembly listings are generated whenever the counter is greater +than zero. +.Pp +.Ss Li .octa Va biGNUms +This directive expects zero or more biGNUms, separated by commas. For each +biGNUm, it emits a 16-byte integer. +.Pp +The term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence +.Em octa +-word for 16 bytes. +.Pp +.Ss Li .org Va new-lc , Va fill +Advance the location counter of the current section to +.Va new-lc . +.Va new-lc +is either an absolute expression or an expression with the same section as +the current subsection. That is, you can't use +.Li .org +to cross sections: if +.Va new-lc +has the wrong section, the +.Li .org +directive is ignored. To be compatible with former assemblers, if the section +of +.Va new-lc +is absolute, +.Xr as +issues a warning, then pretends the section of +.Va new-lc +is the same as the current subsection. +.Pp +.Li .org +may only increase the location counter, or leave it unchanged; you cannot +use +.Li .org +to move the location counter backwards. +.Pp +Because +.Xr as +tries to assemble programs in one pass, +.Va new-lc +may not be undefined. If you really detest this restriction we eagerly await +a chance to share your improved assembler. +.Pp +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. +.Pp +When the location counter (of the current subsection) is advanced, the intervening +bytes are filled with +.Va fill +which should be an absolute expression. If the comma and +.Va fill +are omitted, +.Va fill +defaults to zero. +.Pp +.Ss Li .p2align[wl] Va abs-expr, Va abs-expr, Va 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 must have after advancement. For example +.Li .p2align 3 +advances the location counter until it a multiple of 8. If the location counter +is already a multiple of 8, no change is needed. +.Pp +The second expression (also absolute) gives the fill value to be stored in +the padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section +is marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. +.Pp +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after +the required alignment; this can be useful if you want the alignment to be +filled with no-op instructions when appropriate. +.Pp +The +.Li .p2alignw +and +.Li .p2alignl +directives are variants of the +.Li .p2align +directive. The +.Li .p2alignw +directive treats the fill pattern as a two byte word value. The +.Li .p2alignl +directives treats the fill pattern as a four byte longword value. For example, +.Li .p2alignw 2,0x368d +will align to a multiple of 4. If it skips two bytes, they will be filled +in with the value 0x368d (the exact placement of the bytes depends upon the +endianness of the processor). If it skips 1 or 3 bytes, the fill value is +undefined. +.Pp +.Ss Li .previous +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +and +.Li .popsection +(see Section +.Dq PopSection ) . +.Pp +This directive swaps the current section (and subsection) with most recently +referenced section (and subsection) prior to this one. Multiple +.Li .previous +directives in a row will flip between two sections (and their subsections). +.Pp +In terms of the section stack, this directive swaps the current section with +the top section on the section stack. +.Pp +.Ss Li .popsection +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +This directive replaces the current section (and subsection) with the top +section (and subsection) on the section stack. This section is popped off +the stack. +.Pp +.Ss Li .print Va string +.Xr as +will print +.Va string +on the standard output during assembly. You must put +.Va string +in double quotes. +.Pp +.Ss Li .protected Va names +This is one of the ELF visibility directives. The other two are +.Li .hidden +(see Section +.Dq Hidden ) +and +.Li .internal +(see Section +.Dq Internal ) . +.Pp +This directive overrides the named symbols default visibility (which is set +by their binding: local, global or weak). The directive sets the visibility +to +.Li protected +which means that any references to the symbols from within the components +that defines them must be resolved to the definition in that component, even +if a definition in another component would normally preempt this. +.Pp +.Ss Li .psize Va lines , Va columns +Use this directive to declare the number of lines---and, optionally, the number +of columns---to use for each page, when generating listings. +.Pp +If you do not use +.Li .psize , +listings use a default line-count of 60. You may omit the comma and +.Va columns +specification; the default width is 200 columns. +.Pp +.Xr as +generates formfeeds whenever the specified number of lines is exceeded (or +whenever you explicitly request one, using +.Li .eject ) . +.Pp +If you specify +.Va lines +as +.Li 0 , +no formfeeds are generated save those explicitly specified with +.Li .eject . +.Pp +.Ss Li .purgem Va name +Undefine the macro +.Va name , +so that later uses of the string will not be expanded.See Section +.Dq Macro . +.Pp +.Ss Li .pushsection Va name , Va subsection +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .popsection +(see Section +.Dq PopSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +This directive pushes the current section (and subsection) onto the top of +the section stack, and then replaces the current section and subsection with +.Li name +and +.Li subsection . +.Pp +.Ss Li .quad Va biGNUms +.Li .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. +.Pp +The term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence +.Em quad +-word for 8 bytes. +.Pp +.Ss Li .reloc Va offset, Va reloc_name[, Va expression] +Generate a relocation at +.Va offset +of type +.Va reloc_name +with value +.Va expression . +If +.Va offset +is a number, the relocation is generated in the current section. If +.Va offset +is an expression that resolves to a symbol plus offset, the relocation is +generated in the given symbol's section. +.Va expression , +if present, must resolve to a symbol plus addend or to an absolute value, +but note that not all targets support an addend. e.g. ELF REL targets such +as i386 store an addend in the section contents rather than in the relocation. +This low level interface does not support addends stored in the section. +.Pp +.Ss Li .rept Va count +Repeat the sequence of lines between the +.Li .rept +directive and the next +.Li .endr +directive +.Va count +times. +.Pp +For example, assembling +.Pp +.Bd -literal -offset indent + .rept 3 + .long 0 + .endr +.Ed +.Pp +is equivalent to assembling +.Pp +.Bd -literal -offset indent + .long 0 + .long 0 + .long 0 +.Ed +.Pp +.Ss Li .sbttl " Va subheading" +Use +.Va subheading +as the title (third line, immediately after the title line) when generating +assembly listings. +.Pp +This directive affects subsequent pages, as well as the current page if it +appears within ten lines of the top of a page. +.Pp +.Ss Li .section Va name +Use the +.Li .section +directive to assemble the following code into a section named +.Va name . +.Pp +This directive is only supported for targets that actually support arbitrarily +named sections; on +.Li a.out +targets, for example, it is not accepted, even with a standard +.Li a.out +section name. +.Pp +This is one of the ELF section stack manipulation directives. The others are +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +.Li .popsection +(see Section +.Dq PopSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +For ELF targets, the +.Li .section +directive is used like this: +.Pp +.Bd -literal -offset indent +\&.section name [, "flags"[, @type[,flag_specific_arguments]]] +.Ed +.Pp +The optional +.Va flags +argument is a quoted string which may contain any combination of the following +characters: +.Bl -tag -width Ds +.It a +section is allocatable +.It w +section is writable +.It x +section is executable +.It M +section is mergeable +.It S +section contains zero terminated strings +.It G +section is a member of a section group +.It T +section is used for thread-local-storage +.El +.Pp +The optional +.Va type +argument may contain one of the following constants: +.Bl -tag -width Ds +.It @progbits +section contains data +.It @nobits +section does not contain data (i.e., section only occupies space) +.It @note +section contains data which is used by things other than the program +.It @init_array +section contains an array of pointers to init functions +.It @fini_array +section contains an array of pointers to finish functions +.It @preinit_array +section contains an array of pointers to pre-init functions +.El +.Pp +Many targets only support the first three section types. +.Pp +Note on targets where the +.Li @ +character is the start of a comment (eg ARM) then another character is used +instead. For example the ARM port uses the +.Li % +character. +.Pp +If +.Va flags +contains the +.Li M +symbol then the +.Va type +argument must be specified as well as an extra argument--- +.Va entsize +---like this: +.Pp +.Bd -literal -offset indent +\&.section name , "flags"M, @type, entsize +.Ed +.Pp +Sections with the +.Li M +flag but not +.Li S +flag must contain fixed size constants, each +.Va entsize +octets long. Sections with both +.Li M +and +.Li S +must contain zero terminated strings where each character is +.Va entsize +bytes long. The linker may remove duplicates within sections with the same +name, same entity size and same flags. +.Va entsize +must be an absolute expression. +.Pp +If +.Va flags +contains the +.Li G +symbol then the +.Va type +argument must be present along with an additional field like this: +.Pp +.Bd -literal -offset indent +\&.section name , "flags"G, @type, GroupName[, linkage] +.Ed +.Pp +The +.Va GroupName +field specifies the name of the section group to which this particular section +belongs. The optional linkage field can contain: +.Bl -tag -width Ds +.It comdat +indicates that only one copy of this section should be retained +.It .GNU.linkonce +an alias for comdat +.El +.Pp +Note: if both the +.Va M +and +.Va G +flags are present then the fields for the Merge flag should come first, like +this: +.Pp +.Bd -literal -offset indent +\&.section name , "flags"MG, @type, entsize, GroupName[, linkage] +.Ed +.Pp +If no flags are specified, the default flags depend upon the section name. +If the section name is not recognized, the default will be for the section +to have none of the above flags: it will not be allocated in memory, nor writable, +nor executable. The section will contain data. +.Pp +For ELF targets, the assembler supports another type of +.Li .section +directive for compatibility with the Solaris assembler: +.Pp +.Bd -literal -offset indent +\&.section "name"[, flags...] +.Ed +.Pp +Note that the section name is quoted. There may be a sequence of comma separated +flags: +.Bl -tag -width Ds +.It #alloc +section is allocatable +.It #write +section is writable +.It #execinstr +section is executable +.It #tls +section is used for thread local storage +.El +.Pp +This directive replaces the current section and subsection. See the contents +of the gas testsuite directory +.Li gas/testsuite/gas/elf +for some examples of how this directive and the other section stack directives +work. +.Pp +.Ss Li .set Va symbol, Va expression +Set the value of +.Va symbol +to +.Va expression . +This changes +.Va symbol +\&'s value and type to conform to +.Va expression . +If +.Va symbol +was flagged as external, it remains flagged (see Section +.Dq Symbol Attributes ) . +.Pp +You may +.Li .set +a symbol many times in the same assembly. +.Pp +If you +.Li .set +a global symbol, the value stored in the object file is the last value stored +into it. +.Pp +.Ss Li .short Va expressions +This expects zero or more +.Va expressions , +and emits a 16 bit number for each. +.Pp +.Ss Li .single Va flonums +This directive assembles zero or more flonums, separated by commas. It has +the same effect as +.Li .float . +.Pp +.Ss Li .size +This directive is used to set the size associated with a symbol. +.Pp +For ELF targets, the +.Li .size +directive is used like this: +.Pp +.Bd -literal -offset indent +\&.size name , expression +.Ed +.Pp +This directive sets the size associated with a symbol +.Va name . +The size in bytes is computed from +.Va expression +which can make use of label arithmetic. This directive is typically used to +set the size of function symbols. +.Pp +.Ss Li .sleb128 Va expressions +.Va sleb128 +stands for \(lqsigned little endian base 128.\(rq This is a compact, variable length +representation of numbers used by the DWARF symbolic debugging format.See Section +.Dq Uleb128 . +.Pp +.Ss Li .skip Va size , Va fill +This directive emits +.Va size +bytes, each of value +.Va fill . +Both +.Va size +and +.Va fill +are absolute expressions. If the comma and +.Va fill +are omitted, +.Va fill +is assumed to be zero. This is the same as +.Li .space . +.Pp +.Ss Li .space Va size , Va fill +This directive emits +.Va size +bytes, each of value +.Va fill . +Both +.Va size +and +.Va fill +are absolute expressions. If the comma and +.Va fill +are omitted, +.Va fill +is assumed to be zero. This is the same as +.Li .skip . +.Pp +.Ss Li .stabd, .stabn, .stabs +There are three directives that begin +.Li .stab . +All emit symbols (see Section +.Dq Symbols ) , +for use by symbolic debuggers. The symbols are not entered in the +.Xr as +hash table: they cannot be referenced elsewhere in the source file. Up to +five fields are required: +.Pp +.Bl -tag -width Ds +.It string +This is the symbol's name. It may contain any character except +.Li \e000 , +so is more general than ordinary symbol names. Some debuggers used to code +arbitrarily complex structures into symbol names using this field. +.Pp +.It type +An absolute expression. The symbol's type is set to the low 8 bits of this +expression. Any bit pattern is permitted, but +.Li ld +and debuggers choke on silly bit patterns. +.Pp +.It other +An absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits +of this expression. +.Pp +.It desc +An absolute expression. The symbol's descriptor is set to the low 16 bits +of this expression. +.Pp +.It value +An absolute expression which becomes the symbol's value. +.El +.Pp +If a warning is detected while reading a +.Li .stabd , +.Li .stabn , +or +.Li .stabs +statement, the symbol has probably already been created; you get a half-formed +symbol in your object file. This is compatible with earlier assemblers! +.Pp +.Bl -tag -width Ds +.It .stabd Va type , Va other , Va desc +.Pp +The \(lqname\(rq 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. +.Pp +The symbol's value is set to the location counter, relocatably. When your +program is linked, the value of this symbol is the address of the location +counter when the +.Li .stabd +was assembled. +.Pp +.It .stabn Va type , Va other , Va desc , Va value +The name of the symbol is set to the empty string +.Li "" . +.Pp +.It .stabs Va string , Va type , Va other , Va desc , Va value +All five fields are specified. +.El +.Pp +.Ss Li .string " Va str" +Copy the characters in +.Va str +to the object file. You may specify more than one string to copy, separated +by commas. Unless otherwise specified for a particular machine, the assembler +marks the end of each string with a 0 byte. You can use any of the escape +sequences described in Strings,,Strings. +.Pp +.Ss Li .struct Va expression +Switch to the absolute section, and set the section offset to +.Va expression , +which must be an absolute expression. You might use this as follows: +.Bd -literal -offset indent + .struct 0 +field1: + .struct field1 + 4 +field2: + .struct field2 + 4 +field3: +.Ed +This would define the symbol +.Li field1 +to have the value 0, the symbol +.Li field2 +to have the value 4, and the symbol +.Li field3 +to have the value 8. Assembly would be left in the absolute section, and you +would need to use a +.Li .section +directive of some sort to change to some other section before further assembly. +.Pp +.Ss Li .subsection Va name +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +.Li .popsection +(see Section +.Dq PopSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +This directive replaces the current subsection with +.Li name . +The current section is not changed. The replaced subsection is put onto the +section stack in place of the then current top of stack subsection. +.Pp +.Ss Li .symver +Use the +.Li .symver +directive to bind symbols to specific version nodes within a source file. +This is only supported on ELF platforms, and is typically used when assembling +files to be linked into a shared library. There are cases where it may make +sense to use this in objects to be bound into an application itself so as +to override a versioned symbol from a shared library. +.Pp +For ELF targets, the +.Li .symver +directive can be used like this: +.Bd -literal -offset indent +\&.symver name, name2@nodename +.Ed +If the symbol +.Va name +is defined within the file being assembled, the +.Li .symver +directive effectively creates a symbol alias with the name +.Va name2@nodename , +and in fact the main reason that we just don't try and create a regular alias +is that the +.Va @ +character isn't permitted in symbol names. The +.Va name2 +part of the name is the actual name of the symbol by which it will be externally +referenced. The name +.Va name +itself is merely a name of convenience that is used so that it is possible +to have definitions for multiple versions of a function within a single source +file, and so that the compiler can unambiguously know which version of a function +is being mentioned. The +.Va nodename +portion of the alias should be the name of a node specified in the version +script supplied to the linker when building a shared library. If you are attempting +to override a versioned symbol from a shared library, then +.Va nodename +should correspond to the nodename of the symbol you are trying to override. +.Pp +If the symbol +.Va name +is not defined within the file being assembled, all references to +.Va name +will be changed to +.Va name2@nodename . +If no reference to +.Va name +is made, +.Va name2@nodename +will be removed from the symbol table. +.Pp +Another usage of the +.Li .symver +directive is: +.Bd -literal -offset indent +\&.symver name, name2@@nodename +.Ed +In this case, the symbol +.Va name +must exist and be defined within the file being assembled. It is similar to +.Va name2@nodename . +The difference is +.Va name2@@nodename +will also be used to resolve references to +.Va name2 +by the linker. +.Pp +The third usage of the +.Li .symver +directive is: +.Bd -literal -offset indent +\&.symver name, name2@@@nodename +.Ed +When +.Va name +is not defined within the file being assembled, it is treated as +.Va name2@nodename . +When +.Va name +is defined within the file being assembled, the symbol name, +.Va name , +will be changed to +.Va name2@@nodename . +.Pp +.Ss Li .text Va subsection +Tells +.Xr as +to assemble the following statements onto the end of the text subsection numbered +.Va subsection , +which is an absolute expression. If +.Va subsection +is omitted, subsection number zero is used. +.Pp +.Ss Li .title " Va heading" +Use +.Va heading +as the title (second line, immediately after the source file name and pagenumber) +when generating assembly listings. +.Pp +This directive affects subsequent pages, as well as the current page if it +appears within ten lines of the top of a page. +.Pp +.Ss Li .type +This directive is used to set the type of a symbol. +.Pp +For ELF targets, the +.Li .type +directive is used like this: +.Pp +.Bd -literal -offset indent +\&.type name , type description +.Ed +.Pp +This sets the type of symbol +.Va name +to be either a function symbol or an object symbol. There are five different +syntaxes supported for the +.Va type description +field, in order to provide compatibility with various other assemblers. +.Pp +Because some of the characters used in these syntaxes (such as +.Li @ +and +.Li # ) +are comment characters for some architectures, some of the syntaxes below +do not work on all architectures. The first variant will be accepted by the +GNU assembler on all architectures so that variant should be used for maximum +portability, if you do not need to assemble your code with other assemblers. +.Pp +The syntaxes supported are: +.Pp +.Bd -literal -offset indent + .type <name> STT_FUNCTION + .type <name> STT_OBJECT + + .type <name>,#function + .type <name>,#object + + .type <name>,@function + .type <name>,@object + + .type <name>,%function + .type <name>,%object + + .type <name>,"function" + .type <name>,"object" +.Ed +.Pp +.Ss Li .uleb128 Va expressions +.Va uleb128 +stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length +representation of numbers used by the DWARF symbolic debugging format.See Section +.Dq Sleb128 . +.Pp +.Ss Li .version " Va string" +This directive creates a +.Li .note +section and places into it an ELF formatted note of type NT_VERSION. The note's +name is set to +.Li string . +.Pp +.Ss Li .vtable_entry Va table, Va offset +This directive finds or creates a symbol +.Li table +and creates a +.Li VTABLE_ENTRY +relocation for it with an addend of +.Li offset . +.Pp +.Ss Li .vtable_inherit Va child, Va parent +This directive finds the symbol +.Li child +and finds or creates the symbol +.Li parent +and then creates a +.Li VTABLE_INHERIT +relocation for the parent whose addend is the value of the child symbol. As +a special case the parent name of +.Li 0 +is treated as referring to the +.Li *ABS* +section. +.Pp +.Ss Li .warning " Va string" +Similar to the directive +.Li .error +(see Section +.Dq Error ) , +but just emits a warning. +.Pp +.Ss Li .weak Va names +This directive sets the weak attribute on the comma separated list of symbol +.Li names . +If the symbols do not already exist, they will be created. +.Pp +On COFF targets other than PE, weak symbols are a GNU extension. This directive +sets the weak attribute on the comma separated list of symbol +.Li names . +If the symbols do not already exist, they will be created. +.Pp +On the PE target, weak symbols are supported natively as weak aliases. When +a weak symbol is created that is not an alias, GAS creates an alternate symbol +to hold the default value. +.Pp +.Ss Li .weakref Va alias, Va target +This directive creates an alias to the target symbol that enables the symbol +to be referenced with weak-symbol semantics, but without actually making it +weak. If direct references or definitions of the symbol are present, then +the symbol will not be weak, but if all references to it are through weak +references, the symbol will be marked as weak in the symbol table. +.Pp +The effect is equivalent to moving all references to the alias to a separate +assembly source file, renaming the alias to the symbol in it, declaring the +symbol as weak there, and running a reloadable link to merge the object files +resulting from the assembly of the new source file and the old source file +that had the references to the alias removed. +.Pp +The alias itself never makes to the symbol table, and is entirely handled +within the assembler. +.Pp +.Ss Li .word Va expressions +This directive expects zero or more +.Va expressions , +of any section, separated by commas. For each expression, +.Xr as +emits a 32-bit number. +.Pp +.Ss Deprecated Directives +One day these directives won't work. They are included for compatibility with +older assemblers. +.Bl -tag -width Ds +.It .abort +.It .line +.El +.Pp +.Sh ARM Dependent Features +.Ss Options +.Bl -tag -width Ds +.It -mcpu= Va processor[+ Va extension...] +This option specifies the target processor. The assembler will issue an error +message if an attempt is made to assemble an instruction which will not execute +on the target processor. The following processor names are recognized: +.Li arm1 , +.Li arm2 , +.Li arm250 , +.Li arm3 , +.Li arm6 , +.Li arm60 , +.Li arm600 , +.Li arm610 , +.Li arm620 , +.Li arm7 , +.Li arm7m , +.Li arm7d , +.Li arm7dm , +.Li arm7di , +.Li arm7dmi , +.Li arm70 , +.Li arm700 , +.Li arm700i , +.Li arm710 , +.Li arm710t , +.Li arm720 , +.Li arm720t , +.Li arm740t , +.Li arm710c , +.Li arm7100 , +.Li arm7500 , +.Li arm7500fe , +.Li arm7t , +.Li arm7tdmi , +.Li arm7tdmi-s , +.Li arm8 , +.Li arm810 , +.Li strongarm , +.Li strongarm1 , +.Li strongarm110 , +.Li strongarm1100 , +.Li strongarm1110 , +.Li arm9 , +.Li arm920 , +.Li arm920t , +.Li arm922t , +.Li arm940t , +.Li arm9tdmi , +.Li arm9e , +.Li arm926e , +.Li arm926ej-s , +.Li arm946e-r0 , +.Li arm946e , +.Li arm946e-s , +.Li arm966e-r0 , +.Li arm966e , +.Li arm966e-s , +.Li arm968e-s , +.Li arm10t , +.Li arm10tdmi , +.Li arm10e , +.Li arm1020 , +.Li arm1020t , +.Li arm1020e , +.Li arm1022e , +.Li arm1026ej-s , +.Li arm1136j-s , +.Li arm1136jf-s , +.Li arm1156t2-s , +.Li arm1156t2f-s , +.Li arm1176jz-s , +.Li arm1176jzf-s , +.Li mpcore , +.Li mpcorenovfp , +.Li cortex-a8 , +.Li cortex-r4 , +.Li cortex-m3 , +.Li ep9312 +(ARM920 with Cirrus Maverick coprocessor), +.Li i80200 +(Intel XScale processor) +.Li iwmmxt +(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and +.Li xscale . +The special name +.Li all +may be used to allow the assembler to accept instructions valid for any ARM +processor. +.Pp +In addition to the basic instruction set, the assembler can be told to accept +various extension mnemonics that extend the processor using the co-processor +instruction space. For example, +.Li -mcpu=arm920+maverick +is equivalent to specifying +.Li -mcpu=ep9312 . +The following extensions are currently supported: +.Li +maverick +.Li +iwmmxt +and +.Li +xscale . +.Pp +.It -march= Va architecture[+ Va extension...] +This option specifies the target architecture. The assembler will issue an +error message if an attempt is made to assemble an instruction which will +not execute on the target architecture. The following architecture names are +recognized: +.Li armv1 , +.Li armv2 , +.Li armv2a , +.Li armv2s , +.Li armv3 , +.Li armv3m , +.Li armv4 , +.Li armv4xm , +.Li armv4t , +.Li armv4txm , +.Li armv5 , +.Li armv5t , +.Li armv5txm , +.Li armv5te , +.Li armv5texp , +.Li armv6 , +.Li armv6j , +.Li armv6k , +.Li armv6z , +.Li armv6zk , +.Li armv7 , +.Li armv7-a , +.Li armv7-r , +.Li armv7-m , +.Li iwmmxt +and +.Li xscale . +If both +.Li -mcpu +and +.Li -march +are specified, the assembler will use the setting for +.Li -mcpu . +.Pp +The architecture option can be extended with the same instruction set extension +options as the +.Li -mcpu +option. +.Pp +.It -mfpu= Va floating-point-format +.Pp +This option specifies the floating point format to assemble for. The assembler +will issue an error message if an attempt is made to assemble an instruction +which will not execute on the target floating point unit. The following format +options are recognized: +.Li softfpa , +.Li fpe , +.Li fpe2 , +.Li fpe3 , +.Li fpa , +.Li fpa10 , +.Li fpa11 , +.Li arm7500fe , +.Li softvfp , +.Li softvfp+vfp , +.Li vfp , +.Li vfp10 , +.Li vfp10-r0 , +.Li vfp9 , +.Li vfpxd , +.Li arm1020t , +.Li arm1020e , +.Li arm1136jf-s +and +.Li maverick . +.Pp +In addition to determining which instructions are assembled, this option also +affects the way in which the +.Li .double +assembler directive behaves when assembling little-endian code. +.Pp +The default is dependent on the processor selected. For Architecture 5 or +later, the default is to assembler for VFP instructions; for earlier architectures +the default is to assemble for FPA instructions. +.Pp +.It -mthumb +This option specifies that the assembler should start assembling Thumb instructions; +that is, it should behave as though the file starts with a +.Li .code 16 +directive. +.Pp +.It -mthumb-interwork +This option specifies that the output generated by the assembler should be +marked as supporting interworking. +.Pp +.It -mapcs Li [26|32] +This option specifies that the output generated by the assembler should be +marked as supporting the indicated version of the Arm Procedure. Calling Standard. +.Pp +.It -matpcs +This option specifies that the output generated by the assembler should be +marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled +this option will cause the assembler to create an empty debugging section +in the object file called .arm.atpcs. Debuggers can use this to determine +the ABI being used by. +.Pp +.It -mapcs-float +This indicates the floating point variant of the APCS should be used. In this +variant floating point arguments are passed in FP registers rather than integer +registers. +.Pp +.It -mapcs-reentrant +This indicates that the reentrant variant of the APCS should be used. This +variant supports position independent code. +.Pp +.It -mfloat-abi= Va abi +This option specifies that the output generated by the assembler should be +marked as using specified floating point ABI. The following values are recognized: +.Li soft , +.Li softfp +and +.Li hard . +.Pp +.It -meabi= Va ver +This option specifies which EABI version the produced object files should +conform to. The following values are recognized: +.Li GNU , +.Li 4 +and +.Li 5 . +.Pp +.It -EB +This option specifies that the output generated by the assembler should be +marked as being encoded for a big-endian processor. +.Pp +.It -EL +This option specifies that the output generated by the assembler should be +marked as being encoded for a little-endian processor. +.Pp +.It -k +This option specifies that the output of the assembler should be marked as +position-independent code (PIC). +.Pp +.El +.Ss Syntax +.Em Special Characters +.Pp +The presence of a +.Li @ +on a line indicates the start of a comment that extends to the end of the +current line. If a +.Li # +appears as the first character of a line, the whole line is treated as a comment. +.Pp +The +.Li ; +character can be used instead of a newline to separate statements. +.Pp +Either +.Li # +or +.Li $ +can be used to indicate immediate operands. +.Pp +*TODO* Explain about /data modifier on symbols. +.Pp +.Em Register Names +.Pp +*TODO* Explain about ARM register naming, and the predefined names. +.Pp +.Em ARM relocation generation +.Pp +Specific data relocations can be generated by putting the relocation name +in parentheses after the symbol name. For example: +.Pp +.Bd -literal -offset indent + .word foo(TARGET1) +.Ed +.Pp +This will generate an +.Li R_ARM_TARGET1 +relocation against the symbol +.Va foo . +The following relocations are supported: +.Li GOT , +.Li GOTOFF , +.Li TARGET1 , +.Li TARGET2 , +.Li SBREL , +.Li TLSGD , +.Li TLSLDM , +.Li TLSLDO , +.Li GOTTPOFF +and +.Li TPOFF . +.Pp +For compatibility with older toolchains the assembler also accepts +.Li (PLT) +after branch targets. This will generate the deprecated +.Li R_ARM_PLT32 +relocation. +.Pp +Relocations for +.Li MOVW +and +.Li MOVT +instructions can be generated by prefixing the value with +.Li #:lower16: +and +.Li #:upper16 +respectively. For example to load the 32-bit address of foo into r0: +.Pp +.Bd -literal -offset indent + MOVW r0, #:lower16:foo + MOVT r0, #:upper16:foo +.Ed +.Pp +.Ss Floating Point +The ARM family uses ieee floating-point numbers. +.Pp +.Ss ARM Machine Directives +.Bl -tag -width Ds +.It .align Va expression [, Va expression] +This is the generic +.Va .align +directive. For the ARM however if the first argument is zero (ie no alignment +is needed) the assembler will behave as if the argument had been 2 (ie pad +to the next four byte boundary). This is for compatibility with ARM's own +assembler. +.Pp +.It Va name .req Va register name +This creates an alias for +.Va register name +called +.Va name . +For example: +.Pp +.Bd -literal -offset indent + foo .req r0 +.Ed +.Pp +.It .unreq Va alias-name +This undefines a register alias which was previously defined using the +.Li req , +.Li dn +or +.Li qn +directives. For example: +.Pp +.Bd -literal -offset indent + foo .req r0 + .unreq foo +.Ed +.Pp +An error occurs if the name is undefined. Note - this pseudo op can be used +to delete builtin in register name aliases (eg 'r0'). This should only be +done if it is really necessary. +.Pp +.It Va name .dn Va register name [ Va .type] [ Va [index]] +.It Va name .qn Va register name [ Va .type] [ Va [index]] +.Pp +The +.Li dn +and +.Li qn +directives are used to create typed and/or indexed register aliases for use +in Advanced SIMD Extension (Neon) instructions. The former should be used +to create aliases of double-precision registers, and the latter to create +aliases of quad-precision registers. +.Pp +If these directives are used to create typed aliases, those aliases can be +used in Neon instructions instead of writing types after the mnemonic or after +each operand. For example: +.Pp +.Bd -literal -offset indent + x .dn d2.f32 + y .dn d3.f32 + z .dn d4.f32[1] + vmul x,y,z +.Ed +.Pp +This is equivalent to writing the following: +.Pp +.Bd -literal -offset indent + vmul.f32 d2,d3,d4[1] +.Ed +.Pp +Aliases created using +.Li dn +or +.Li qn +can be destroyed using +.Li unreq . +.Pp +.It .code Li [16|32] +This directive selects the instruction set being generated. The value 16 selects +Thumb, with the value 32 selecting ARM. +.Pp +.It .thumb +This performs the same action as +.Va .code 16 . +.Pp +.It .arm +This performs the same action as +.Va .code 32 . +.Pp +.It .force_thumb +This directive forces the selection of Thumb instructions, even if the target +processor does not support those instructions +.Pp +.It .thumb_func +This directive specifies that the following symbol is the name of a Thumb +encoded function. This information is necessary in order to allow the assembler +and linker to generate correct code for interworking between Arm and Thumb +instructions and should be used even if interworking is not going to be performed. +The presence of this directive also implies +.Li .thumb +.Pp +This directive is not neccessary when generating EABI objects. On these targets +the encoding is implicit when generating Thumb code. +.Pp +.It .thumb_set +This performs the equivalent of a +.Li .set +directive in that it creates a symbol which is an alias for another symbol +(possibly not yet defined). This directive also has the added property in +that it marks the aliased symbol as being a thumb function entry point, in +the same way that the +.Li .thumb_func +directive does. +.Pp +.It .ltorg +This directive causes the current contents of the literal pool to be dumped +into the current section (which is assumed to be the .text section) at the +current location (aligned to a word boundary). +.Li GAS +maintains a separate literal pool for each section and each sub-section. The +.Li .ltorg +directive will only affect the literal pool of the current section and sub-section. +At the end of assembly all remaining, un-empty literal pools will automatically +be dumped. +.Pp +Note - older versions of +.Li GAS +would dump the current literal pool any time a section change occurred. This +is no longer done, since it prevents accurate control of the placement of +literal pools. +.Pp +.It .pool +This is a synonym for .ltorg. +.Pp +.It .unwind_fnstart +Marks the start of a function with an unwind table entry. +.Pp +.It .unwind_fnend +Marks the end of a function with an unwind table entry. The unwind index table +entry is created when this directive is processed. +.Pp +If no personality routine has been specified then standard personality routine +0 or 1 will be used, depending on the number of unwind opcodes required. +.Pp +.It .cantunwind +Prevents unwinding through the current function. No personality routine or +exception table data is required or permitted. +.Pp +.It .personality Va name +Sets the personality routine for the current function to +.Va name . +.Pp +.It .personalityindex Va index +Sets the personality routine for the current function to the EABI standard +routine number +.Va index +.Pp +.It .handlerdata +Marks the end of the current function, and the start of the exception table +entry for that function. Anything between this directive and the +.Li .fnend +directive will be added to the exception table entry. +.Pp +Must be preceded by a +.Li .personality +or +.Li .personalityindex +directive. +.Pp +.It .save Va reglist +Generate unwinder annotations to restore the registers in +.Va reglist . +The format of +.Va reglist +is the same as the corresponding store-multiple instruction. +.Pp +.Bd -literal -offset indent + .save {r4, r5, r6, lr} + stmfd sp!, {r4, r5, r6, lr} + .save f4, 2 + sfmfd f4, 2, [sp]! + .save {d8, d9, d10} + fstmdx sp!, {d8, d9, d10} + .save {wr10, wr11} + wstrd wr11, [sp, #-8]! + wstrd wr10, [sp, #-8]! +or + .save wr11 + wstrd wr11, [sp, #-8]! + .save wr10 + wstrd wr10, [sp, #-8]! +.Ed +.Pp +.It .vsave Va vfp-reglist +Generate unwinder annotations to restore the VFP registers in +.Va vfp-reglist +using FLDMD. Also works for VFPv3 registers that are to be restored using +VLDM. The format of +.Va vfp-reglist +is the same as the corresponding store-multiple instruction. +.Pp +.Bd -literal -offset indent + .vsave {d8, d9, d10} + fstmdd sp!, {d8, d9, d10} + .vsave {d15, d16, d17} + vstm sp!, {d15, d16, d17} +.Ed +.Pp +Since FLDMX and FSTMX are now deprecated, this directive should be used in +favour of +.Li .save +for saving VFP registers for ARMv6 and above. +.Pp +.It .pad # Va count +Generate unwinder annotations for a stack adjustment of +.Va count +bytes. A positive value indicates the function prologue allocated stack space +by decrementing the stack pointer. +.Pp +.It .movsp Va reg [, # Va offset] +Tell the unwinder that +.Va reg +contains an offset from the current stack pointer. If +.Va offset +is not specified then it is assumed to be zero. +.Pp +.It .setfp Va fpreg, Va spreg [, # Va offset] +Make all unwinder annotations relaive to a frame pointer. Without this the +unwinder will use offsets from the stack pointer. +.Pp +The syntax of this directive is the same as the +.Li sub +or +.Li mov +instruction used to set the frame pointer. +.Va spreg +must be either +.Li sp +or mentioned in a previous +.Li .movsp +directive. +.Pp +.Bd -literal -offset indent +\&.movsp ip +mov ip, sp +\&... +\&.setfp fp, ip, #4 +sub fp, ip, #4 +.Ed +.Pp +.It .raw Va offset, Va byte1, ... +Insert one of more arbitary unwind opcode bytes, which are known to adjust +the stack pointer by +.Va offset +bytes. +.Pp +For example +.Li .unwind_raw 4, 0xb1, 0x01 +is equivalent to +.Li .save {r0} +.Pp +.It .cpu Va name +Select the target processor. Valid values for +.Va name +are the same as for the +.Op -mcpu +commandline option. +.Pp +.It .arch Va name +Select the target architecture. Valid values for +.Va name +are the same as for the +.Op -march +commandline option. +.Pp +.It .object_arch Va name +Override the architecture recorded in the EABI object attribute section. Valid +values for +.Va name +are the same as for the +.Li .arch +directive. Typically this is useful when code uses runtime detection of CPU +features. +.Pp +.It .fpu Va name +Select the floating point unit to assemble for. Valid values for +.Va name +are the same as for the +.Op -mfpu +commandline option. +.Pp +.It .eabi_attribute Va tag, Va value +Set the EABI object attribute number +.Va tag +to +.Va value . +The value is either a +.Li number , +.Li "string" , +or +.Li number, "string" +depending on the tag. +.Pp +.El +.Ss Opcodes +.Li as +implements all the standard ARM opcodes. It also implements several pseudo +opcodes, including several synthetic load instructions. +.Pp +.Bl -tag -width Ds +.It NOP +.Bd -literal -offset indent + nop +.Ed +.Pp +This pseudo op will always evaluate to a legal ARM instruction that does nothing. +Currently it will evaluate to MOV r0, r0. +.Pp +.It LDR +.Bd -literal -offset indent + ldr <register> , = <expression> +.Ed +.Pp +If expression evaluates to a numeric constant then a MOV or MVN instruction +will be used in place of the LDR instruction, if the constant can be generated +by either of these instructions. Otherwise the constant will be placed into +the nearest literal pool (if it not already there) and a PC relative LDR instruction +will be generated. +.Pp +.It ADR +.Bd -literal -offset indent + adr <register> <label> +.Ed +.Pp +This instruction will load the address of +.Va label +into the indicated register. The instruction will evaluate to a PC relative +ADD or SUB instruction depending upon where the label is located. If the label +is out of range, or if it is not defined in the same file (and section) as +the ADR instruction, then an error will be generated. This instruction will +not make use of the literal pool. +.Pp +.It ADRL +.Bd -literal -offset indent + adrl <register> <label> +.Ed +.Pp +This instruction will load the address of +.Va label +into the indicated register. The instruction will evaluate to one or two PC +relative ADD or SUB instructions depending upon where the label is located. +If a second instruction is not needed a NOP instruction will be generated +in its place, so that this instruction is always 8 bytes long. +.Pp +If the label is out of range, or if it is not defined in the same file (and +section) as the ADRL instruction, then an error will be generated. This instruction +will not make use of the literal pool. +.Pp +.El +For information on the ARM or Thumb instruction sets, see +.Em ARM Software Development Toolkit Reference Manual , +Advanced RISC Machines Ltd. +.Pp +.Ss Mapping Symbols +The ARM ELF specification requires that special symbols be inserted into object +files to mark certain features: +.Pp +.Bl -tag -width Ds +.It $a +At the start of a region of code containing ARM instructions. +.Pp +.It $t +At the start of a region of code containing THUMB instructions. +.Pp +.It $d +At the start of a region of data. +.Pp +.El +The assembler will automatically insert these symbols for you - there is no +need to code them yourself. Support for tagging symbols ($b, $f, $p and $m) +which is also mentioned in the current ARM ELF specification is not implemented. +This is because they have been dropped from the new EABI and so tools cannot +rely upon their presence. +.Pp +.Sh 80386 Dependent Features +The i386 version +.Li as +supports both the original Intel 386 architecture in both 16 and 32-bit mode +as well as AMD x86-64 architecture extending the Intel architecture to 64-bits. +.Pp +.Ss Options +The i386 version of +.Li as +has a few machine dependent options: +.Pp +.Bl -tag -width Ds +.It --32 | --64 +Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies +Intel i386 architecture, while 64-bit implies AMD x86-64 architecture. +.Pp +These options are only available with the ELF object file format, and require +that the necessary BFD support has been included (on a 32-bit platform you +have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64 +as target platform). +.Pp +.It -n +By default, x86 GAS replaces multiple nop instructions used for alignment +within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi. +This switch disables the optimization. +.Pp +.It --divide +On SVR4-derived platforms, the character +.Li / +is treated as a comment character, which means that it cannot be used in expressions. +The +.Li --divide +option turns +.Li / +into a normal character. This does not disable +.Li / +at the beginning of a line starting a comment, or affect using +.Li # +for starting a comment. +.Pp +.It -march= Va CPU +This option specifies an instruction set architecture for generating instructions. +The following architectures are recognized: +.Li i8086 , +.Li i186 , +.Li i286 , +.Li i386 , +.Li i486 , +.Li i586 , +.Li i686 , +.Li pentium , +.Li pentiumpro , +.Li pentiumii , +.Li pentiumiii , +.Li pentium4 , +.Li prescott , +.Li nocona , +.Li core , +.Li core2 , +.Li k6 , +.Li k6_2 , +.Li athlon , +.Li sledgehammer , +.Li opteron , +.Li k8 , +.Li generic32 +and +.Li generic64 . +.Pp +This option only affects instructions generated by the assembler. The +.Li .arch +directive will take precedent. +.Pp +.It -mtune= Va CPU +This option specifies a processor to optimize for. When used in conjunction +with the +.Op -march +option, only instructions of the processor specified by the +.Op -march +option will be generated. +.Pp +Valid +.Va CPU +values are identical to +.Op -march= Va CPU . +.Pp +.El +.Ss AT&T Syntax versus Intel Syntax +.Li as +now supports assembly using Intel assembler syntax. +.Li .intel_syntax +selects Intel mode, and +.Li .att_syntax +switches back to the usual AT&T mode for compatibility with the output of +.Li gcc . +Either of these directives may have an optional argument, +.Li prefix , +or +.Li noprefix +specifying whether registers require a +.Li % +prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax. +We mention these differences because almost all 80386 documents use Intel +syntax. Notable differences between the two syntaxes are: +.Pp +.Bl -bullet +.It +AT&T immediate operands are preceded by +.Li $ ; +Intel immediate operands are undelimited (Intel +.Li push 4 +is AT&T +.Li pushl $4 ) . +AT&T register operands are preceded by +.Li % ; +Intel register operands are undelimited. AT&T absolute (as opposed to PC relative) +jump/call operands are prefixed by +.Li * ; +they are undelimited in Intel syntax. +.Pp +.It +AT&T and Intel syntax use the opposite order for source and destination operands. +Intel +.Li add eax, 4 +is +.Li addl $4, %eax . +The +.Li source, dest +convention is maintained for compatibility with previous Unix assemblers. +Note that instructions with more than one source operand, such as the +.Li enter +instruction, do +.Em not +have reversed order. i386-Bugs. +.Pp +.It +In AT&T syntax the size of memory operands is determined from the last character +of the instruction mnemonic. Mnemonic suffixes of +.Li b , +.Li w , +.Li l +and +.Li q +specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit) +memory references. Intel syntax accomplishes this by prefixing memory operands +( +.Em not +the instruction mnemonics) with +.Li byte ptr , +.Li word ptr , +.Li dword ptr +and +.Li qword ptr . +Thus, Intel +.Li mov al, byte ptr Va foo +is +.Li movb Va foo, %al +in AT&T syntax. +.Pp +.It +Immediate form long jumps and calls are +.Li lcall/ljmp $ Va section, $ Va offset +in AT&T syntax; the Intel syntax is +.Li call/jmp far Va section: Va offset . +Also, the far return instruction is +.Li lret $ Va stack-adjust +in AT&T syntax; Intel syntax is +.Li ret far Va stack-adjust . +.Pp +.It +The AT&T assembler does not provide support for multiple section programs. +Unix style systems expect all programs to be single sections. +.El +.Pp +.Ss Instruction Naming +Instruction mnemonics are suffixed with one character modifiers which specify +the size of operands. The letters +.Li b , +.Li w , +.Li l +and +.Li q +specify byte, word, long and quadruple word operands. If no suffix is specified +by an instruction then +.Li as +tries to fill in the missing suffix based on the destination register operand +(the last one by convention). Thus, +.Li mov %ax, %bx +is equivalent to +.Li movw %ax, %bx ; +also, +.Li mov $1, %bx +is equivalent to +.Li movw $1, bx . +Note that this is incompatible with the AT&T Unix assembler which assumes +that a missing mnemonic suffix implies long operand size. (This incompatibility +does not affect compiler output since compilers always explicitly specify +the mnemonic suffix.) +.Pp +Almost all instructions 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 +.Em from +and a size to zero extend +.Em to . +This is accomplished by using two instruction mnemonic suffixes in AT&T syntax. +Base names for sign extend and zero extend are +.Li movs... +and +.Li movz... +in AT&T syntax ( +.Li movsx +and +.Li movzx +in Intel syntax). The instruction mnemonic suffixes are tacked on to this +base name, the +.Em from +suffix before the +.Em to +suffix. Thus, +.Li movsbl %al, %edx +is AT&T syntax for \(lqmove sign extend +.Em from +%al +.Em to +%edx.\(rq Possible suffixes, thus, are +.Li bl +(from byte to long), +.Li bw +(from byte to word), +.Li wl +(from word to long), +.Li bq +(from byte to quadruple word), +.Li wq +(from word to quadruple word), and +.Li lq +(from long to quadruple word). +.Pp +The Intel-syntax conversion instructions +.Pp +.Bl -bullet +.It +.Li cbw +--- sign-extend byte in +.Li %al +to word in +.Li %ax , +.Pp +.It +.Li cwde +--- sign-extend word in +.Li %ax +to long in +.Li %eax , +.Pp +.It +.Li cwd +--- sign-extend word in +.Li %ax +to long in +.Li %dx:%ax , +.Pp +.It +.Li cdq +--- sign-extend dword in +.Li %eax +to quad in +.Li %edx:%eax , +.Pp +.It +.Li cdqe +--- sign-extend dword in +.Li %eax +to quad in +.Li %rax +(x86-64 only), +.Pp +.It +.Li cqo +--- sign-extend quad in +.Li %rax +to octuple in +.Li %rdx:%rax +(x86-64 only), +.El +.Pp +are called +.Li cbtw , +.Li cwtl , +.Li cwtd , +.Li cltd , +.Li cltq , +and +.Li cqto +in AT&T naming. +.Li as +accepts either naming for these instructions. +.Pp +Far call/jump instructions are +.Li lcall +and +.Li ljmp +in AT&T syntax, but are +.Li call far +and +.Li jump far +in Intel convention. +.Pp +.Ss Register Naming +Register operands are always prefixed with +.Li % . +The 80386 registers consist of +.Pp +.Bl -bullet +.It +the 8 32-bit registers +.Li %eax +(the accumulator), +.Li %ebx , +.Li %ecx , +.Li %edx , +.Li %edi , +.Li %esi , +.Li %ebp +(the frame pointer), and +.Li %esp +(the stack pointer). +.Pp +.It +the 8 16-bit low-ends of these: +.Li %ax , +.Li %bx , +.Li %cx , +.Li %dx , +.Li %di , +.Li %si , +.Li %bp , +and +.Li %sp . +.Pp +.It +the 8 8-bit registers: +.Li %ah , +.Li %al , +.Li %bh , +.Li %bl , +.Li %ch , +.Li %cl , +.Li %dh , +and +.Li %dl +(These are the high-bytes and low-bytes of +.Li %ax , +.Li %bx , +.Li %cx , +and +.Li %dx ) +.Pp +.It +the 6 section registers +.Li %cs +(code section), +.Li %ds +(data section), +.Li %ss +(stack section), +.Li %es , +.Li %fs , +and +.Li %gs . +.Pp +.It +the 3 processor control registers +.Li %cr0 , +.Li %cr2 , +and +.Li %cr3 . +.Pp +.It +the 6 debug registers +.Li %db0 , +.Li %db1 , +.Li %db2 , +.Li %db3 , +.Li %db6 , +and +.Li %db7 . +.Pp +.It +the 2 test registers +.Li %tr6 +and +.Li %tr7 . +.Pp +.It +the 8 floating point register stack +.Li %st +or equivalently +.Li %st(0) , +.Li %st(1) , +.Li %st(2) , +.Li %st(3) , +.Li %st(4) , +.Li %st(5) , +.Li %st(6) , +and +.Li %st(7) . +These registers are overloaded by 8 MMX registers +.Li %mm0 , +.Li %mm1 , +.Li %mm2 , +.Li %mm3 , +.Li %mm4 , +.Li %mm5 , +.Li %mm6 +and +.Li %mm7 . +.Pp +.It +the 8 SSE registers registers +.Li %xmm0 , +.Li %xmm1 , +.Li %xmm2 , +.Li %xmm3 , +.Li %xmm4 , +.Li %xmm5 , +.Li %xmm6 +and +.Li %xmm7 . +.El +.Pp +The AMD x86-64 architecture extends the register set by: +.Pp +.Bl -bullet +.It +enhancing the 8 32-bit registers to 64-bit: +.Li %rax +(the accumulator), +.Li %rbx , +.Li %rcx , +.Li %rdx , +.Li %rdi , +.Li %rsi , +.Li %rbp +(the frame pointer), +.Li %rsp +(the stack pointer) +.Pp +.It +the 8 extended registers +.Li %r8 +-- +.Li %r15 . +.Pp +.It +the 8 32-bit low ends of the extended registers: +.Li %r8d +-- +.Li %r15d +.Pp +.It +the 8 16-bit low ends of the extended registers: +.Li %r8w +-- +.Li %r15w +.Pp +.It +the 8 8-bit low ends of the extended registers: +.Li %r8b +-- +.Li %r15b +.Pp +.It +the 4 8-bit registers: +.Li %sil , +.Li %dil , +.Li %bpl , +.Li %spl . +.Pp +.It +the 8 debug registers: +.Li %db8 +-- +.Li %db15 . +.Pp +.It +the 8 SSE registers: +.Li %xmm8 +-- +.Li %xmm15 . +.El +.Pp +.Ss Instruction Prefixes +Instruction prefixes are used to modify the following instruction. They are +used to repeat string instructions, to provide section overrides, to perform +bus lock operations, and to change operand and address sizes. (Most instructions +that normally operate on 32-bit operands will use 16-bit operands if the instruction +has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the +same line as the instruction they act upon. For example, the +.Li scas +(scan string) instruction is repeated with: +.Pp +.Bd -literal -offset indent + repne scas %es:(%edi),%al +.Ed +.Pp +You may also place prefixes on the lines immediately preceding the instruction, +but this circumvents checks that +.Li as +does with prefixes, and will not work with all prefixes. +.Pp +Here is a list of instruction prefixes: +.Pp +.Bl -bullet +.It +Section override prefixes +.Li cs , +.Li ds , +.Li ss , +.Li es , +.Li fs , +.Li gs . +These are automatically added by specifying using the +.Va section +: +.Va memory-operand +form for memory references. +.Pp +.It +Operand/Address size prefixes +.Li data16 +and +.Li addr16 +change 32-bit operands/addresses into 16-bit operands/addresses, while +.Li data32 +and +.Li addr32 +change 16-bit ones (in a +.Li .code16 +section) into 32-bit operands/addresses. These prefixes +.Em must +appear on the same line of code as the instruction they modify. For example, +in a 16-bit +.Li .code16 +section, you might write: +.Pp +.Bd -literal -offset indent + addr32 jmpl *(%ebx) +.Ed +.Pp +.It +The bus lock prefix +.Li lock +inhibits interrupts during execution of the instruction it precedes. (This +is only valid with certain instructions; see a 80386 manual for details). +.Pp +.It +The wait for coprocessor prefix +.Li wait +waits for the coprocessor to complete the current instruction. This should +never be needed for the 80386/80387 combination. +.Pp +.It +The +.Li rep , +.Li repe , +and +.Li repne +prefixes are added to string instructions to make them repeat +.Li %ecx +times ( +.Li %cx +times if the current address size is 16-bits). +.It +The +.Li rex +family of prefixes is used by x86-64 to encode extensions to i386 instruction +set. The +.Li rex +prefix has four bits --- an operand size overwrite ( +.Li 64 ) +used to change operand size from 32-bit to 64-bit and X, Y and Z extensions +bits used to extend the register set. +.Pp +You may write the +.Li rex +prefixes directly. The +.Li rex64xyz +instruction emits +.Li rex +prefix with all the bits set. By omitting the +.Li 64 , +.Li x , +.Li y +or +.Li z +you may write other prefixes as well. Normally, there is no need to write +the prefixes explicitly, since gas will automatically generate them based +on the instruction operands. +.El +.Pp +.Ss Memory References +An Intel syntax indirect memory reference of the form +.Pp +.Bd -literal -offset indent +section:[base + index*scale + disp] +.Ed +.Pp +is translated into the AT&T syntax +.Pp +.Bd -literal -offset indent +section:disp(base, index, scale) +.Ed +.Pp +where +.Va base +and +.Va index +are the optional 32-bit base and index registers, +.Va disp +is the optional displacement, and +.Va scale , +taking the values 1, 2, 4, and 8, multiplies +.Va index +to calculate the address of the operand. If no +.Va scale +is specified, +.Va scale +is taken to be 1. +.Va 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 +.Em must +be preceded by a +.Li % . +If you specify a section override which coincides with the default section +register, +.Li as +does +.Em 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. +.Pp +Here are some examples of Intel and AT&T style memory references: +.Pp +.Bl -tag -width Ds +.It AT&T: Li -4(%ebp), Intel: Li [ebp - 4] +.Va base +is +.Li %ebp ; +.Va disp +is +.Li -4 . +.Va section +is missing, and the default section is used ( +.Li %ss +for addressing with +.Li %ebp +as the base register). +.Va index , +.Va scale +are both missing. +.Pp +.It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4] +.Va index +is +.Li %eax +(scaled by a +.Va scale +4); +.Va disp +is +.Li foo . +All other fields are missing. The section register here defaults to +.Li %ds . +.Pp +.It AT&T: Li foo(,1); Intel Li [foo] +This uses the value pointed to by +.Li foo +as a memory operand. Note that +.Va base +and +.Va index +are both missing, but there is only +.Em one +.Li , . +This is a syntactic exception. +.Pp +.It AT&T: Li %gs:foo; Intel Li gs:foo +This selects the contents of the variable +.Li foo +with section register +.Va section +being +.Li %gs . +.El +.Pp +Absolute (as opposed to PC relative) call and jump operands must be prefixed +with +.Li * . +If no +.Li * +is specified, +.Li as +always chooses PC relative addressing for jump/call labels. +.Pp +Any instruction that has a memory operand, but no register operand, +.Em must +specify its size (byte, word, long, or quadruple) with an instruction mnemonic +suffix ( +.Li b , +.Li w , +.Li l +or +.Li q , +respectively). +.Pp +The x86-64 architecture adds an RIP (instruction pointer relative) addressing. +This addressing mode is specified by using +.Li rip +as a base register. Only constant offsets are valid. For example: +.Pp +.Bl -tag -width Ds +.It AT&T: Li 1234(%rip), Intel: Li [rip + 1234] +Points to the address 1234 bytes past the end of the current instruction. +.Pp +.It AT&T: Li symbol(%rip), Intel: Li [rip + symbol] +Points to the +.Li symbol +in RIP relative way, this is shorter than the default absolute addressing. +.El +.Pp +Other addressing modes remain unchanged in x86-64 architecture, except registers +used are 64-bit instead of 32-bit. +.Pp +.Ss 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 +displacement is used. We do not support word (16-bit) displacement jumps in +32-bit mode (i.e. prefixing the jump instruction with the +.Li data16 +instruction prefix), since the 80386 insists upon masking +.Li %eip +to 16 bits after the word displacement is added. (See alsosee Section +.Dq i386-Arch ) +.Pp +Note that the +.Li jcxz , +.Li jecxz , +.Li loop , +.Li loopz , +.Li loope , +.Li loopnz +and +.Li loopne +instructions only come in byte displacements, so that if you use these instructions +( +.Li gcc +does not use them) you may get an error message (and incorrect code). The +AT&T 80386 assembler tries to get around this problem by expanding +.Li jcxz foo +to +.Pp +.Bd -literal -offset indent + jcxz cx_zero + jmp cx_nonzero +cx_zero: jmp foo +cx_nonzero: +.Ed +.Pp +.Ss 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 instruction mnemonic +suffix and a constructor associated with it. Instruction mnemonic suffixes +specify the operand's data type. Constructors build these data types into +memory. +.Pp +.Bl -bullet +.It +Floating point constructors are +.Li .float +or +.Li .single , +.Li .double , +and +.Li .tfloat +for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic +suffixes +.Li s , +.Li l , +and +.Li t . +.Li t +stands for 80-bit (ten byte) real. The 80387 only supports this format via +the +.Li fldt +(load 80-bit real to stack top) and +.Li fstpt +(store 80-bit real and pop stack) instructions. +.Pp +.It +Integer constructors are +.Li .word , +.Li .long +or +.Li .int , +and +.Li .quad +for the 16-, 32-, and 64-bit integer formats. The corresponding instruction +mnemonic suffixes are +.Li s +(single), +.Li l +(long), and +.Li q +(quad). As with the 80-bit real format, the 64-bit +.Li q +format is only present in the +.Li fildq +(load quad integer to stack top) and +.Li fistpq +(store quad integer and pop stack) instructions. +.El +.Pp +Register to register operations should not use instruction mnemonic suffixes. +.Li fstl %st, %st(1) +will give a warning, and be assembled as if you wrote +.Li fst %st, %st(1) , +since all register to register operations use 80-bit floating point operands. +(Contrast this with +.Li fstl %st, mem , +which converts +.Li %st +from 80-bit to 64-bit floating point format, then stores the result in the +4 byte location +.Li mem ) +.Pp +.Ss Intel's MMX and AMD's 3DNow! SIMD Operations +.Li as +supports Intel's MMX instruction set (SIMD instructions for integer data), +available on Intel's Pentium MMX processors and Pentium II processors, AMD's +K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also +supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating +point data) available on AMD's K6-2 processor and possibly others in the future. +.Pp +Currently, +.Li as +does not support Intel's floating point SIMD, Katmai (KNI). +.Pp +The eight 64-bit MMX operands, also used by 3DNow!, are called +.Li %mm0 , +.Li %mm1 , +\&... +.Li %mm7 . +They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers, +one 64-bit integer, or two 32-bit floating point values. The MMX registers +cannot be used at the same time as the floating point stack. +.Pp +See Intel and AMD documentation, keeping in mind that the operand order in +instructions is reversed from the Intel syntax. +.Pp +.Ss Writing 16-bit Code +While +.Li as +normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending +on the default configuration, it also supports writing code to run in real +mode or in 16-bit protected mode code segments. To do this, put a +.Li .code16 +or +.Li .code16gcc +directive before the assembly language instructions to be run in 16-bit mode. +You can switch +.Li as +back to writing normal 32-bit code with the +.Li .code32 +directive. +.Pp +.Li .code16gcc +provides experimental support for generating 16-bit code from gcc, and differs +from +.Li .code16 +in that +.Li call , +.Li ret , +.Li enter , +.Li leave , +.Li push , +.Li pop , +.Li pusha , +.Li popa , +.Li pushf , +and +.Li popf +instructions default to 32-bit size. This is so that the stack pointer is +manipulated in the same way over function calls, allowing access to function +parameters at the same stack offsets as in 32-bit mode. +.Li .code16gcc +also automatically adds address size prefixes where necessary to use the 32-bit +addressing modes that gcc generates. +.Pp +The code which +.Li as +generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor. +To write code that runs on such a processor, you must refrain from using +.Em any +32-bit constructs which require +.Li as +to output address or operand size prefixes. +.Pp +Note that writing 16-bit code instructions by explicitly specifying a prefix +or an instruction mnemonic suffix within a 32-bit code section generates different +machine instructions than those generated for a 16-bit code segment. In a +32-bit code section, the following code generates the machine opcode bytes +.Li 66 6a 04 , +which pushes the value +.Li 4 +onto the stack, decrementing +.Li %esp +by 2. +.Pp +.Bd -literal -offset indent + pushw $4 +.Ed +.Pp +The same code in a 16-bit code section would generate the machine opcode bytes +.Li 6a 04 +(i.e., without the operand size prefix), which is correct since the processor +default operand size is assumed to be 16 bits in a 16-bit code section. +.Pp +.Ss AT&T Syntax bugs +The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers, +generate floating point instructions with reversed source and destination +registers in certain cases. Unfortunately, gcc and possibly many other programs +use this reversed syntax, so we're stuck with it. +.Pp +For example +.Pp +.Bd -literal -offset indent + fsub %st,%st(3) +.Ed +results in +.Li %st(3) +being updated to +.Li %st - %st(3) +rather than the expected +.Li %st(3) - %st . +This happens with all the non-commutative arithmetic floating point operations +with two register operands where the source register is +.Li %st +and the destination register is +.Li %st(i) . +.Pp +.Ss Specifying CPU Architecture +.Li as +may be told to assemble for a particular CPU (sub-)architecture with the +.Li .arch Va cpu_type +directive. This directive enables a warning when gas detects an instruction +that is not supported on the CPU specified. The choices for +.Va cpu_type +are: +.Pp +.TS +l l l l. + +i8086 i186 i286 i386 +i486 i586 i686 pentium +pentiumpro pentiumii pentiumiii pentium4 +prescott nocona core core2 +amdfam10 +k6 athlon sledgehammer k8 +\&.mmx .sse .sse2 .sse3 +\&.ssse3 .sse4.1 .sse4.2 .sse4 +\&.sse4a .3dnow .3dnowa .padlock +\&.pacifica .svme .abm +.TE +.Pp +Apart from the warning, there are only two other effects on +.Li as +operation; Firstly, if you specify a CPU other than +.Li i486 , +then shift by one instructions such as +.Li sarl $1, %eax +will automatically use a two byte opcode sequence. The larger three byte opcode +sequence is used on the 486 (and when no architecture is specified) because +it executes faster on the 486. Note that you can explicitly request the two +byte opcode by writing +.Li sarl %eax . +Secondly, if you specify +.Li i8086 , +.Li i186 , +or +.Li i286 , +.Em and +.Li .code16 +or +.Li .code16gcc +then byte offset conditional jumps will be promoted when necessary to a two +instruction sequence consisting of a conditional jump of the opposite sense +around an unconditional jump to the target. +.Pp +Following the CPU architecture (but not a sub-architecture, which are those +starting with a dot), you may specify +.Li jumps +or +.Li nojumps +to control automatic promotion of conditional jumps. +.Li jumps +is the default, and enables jump promotion; All external jumps will be of +the long variety, and file-local jumps will be promoted as necessary. (see Section +.Dq i386-Jumps ) +.Li nojumps +leaves external conditional jumps as byte offset jumps, and warns about file-local +conditional jumps that +.Li as +promotes. Unconditional jumps are treated as for +.Li jumps . +.Pp +For example +.Pp +.Bd -literal -offset indent + .arch i8086,nojumps +.Ed +.Pp +.Ss Notes +There is some trickery concerning the +.Li mul +and +.Li imul +instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding +multiplies (base opcode +.Li 0xf6 ; +extension 4 for +.Li mul +and 5 for +.Li imul ) +can be output only in the one operand form. Thus, +.Li imul %ebx, %eax +does +.Em not +select the expanding multiply; the expanding multiply would clobber the +.Li %edx +register, and this would confuse +.Li gcc +output. Use +.Li imul %ebx +to get the 64-bit product in +.Li %edx:%eax . +.Pp +We have added a two operand form of +.Li 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 +.Li %eax +by 69, for example, can be done with +.Li imul $69, %eax +rather than +.Li imul $69, %eax, %eax . +.Pp +.Sh IA-64 Dependent Features +.Ss Options +.Bl -tag -width Ds +.It -mconstant-gp +This option instructs the assembler to mark the resulting object file as using +the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program +uses a single global pointer (GP) value. Note that this option does not in +any fashion affect the machine code emitted by the assembler. All it does +is turn on the EF_IA_64_CONS_GP flag in the ELF file header. +.Pp +.It -mauto-pic +This option instructs the assembler to mark the resulting object file as using +the \(lqconstant GP without function descriptor\(rq data model. This model is like +the \(lqconstant GP\(rq model, except that it additionally does away with function +descriptors. What this means is that the address of a function refers directly +to the function's code entry-point. Normally, such an address would refer +to a function descriptor, which contains both the code entry-point and the +GP-value needed by the function. Note that this option does not in any fashion +affect the machine code emitted by the assembler. All it does is turn on the +EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header. +.Pp +.It -milp32 +.It -milp64 +.It -mlp64 +.It -mp64 +These options select the data model. The assembler defaults to +.Li -mlp64 +(LP64 data model). +.Pp +.It -mle +.It -mbe +These options select the byte order. The +.Li -mle +option selects little-endian byte order (default) and +.Li -mbe +selects big-endian byte order. Note that IA-64 machine code always uses little-endian +byte order. +.Pp +.It -mtune=itanium1 +.It -mtune=itanium2 +Tune for a particular IA-64 CPU, +.Va itanium1 +or +.Va itanium2 . +The default is +.Va itanium2 . +.Pp +.It -munwind-check=warning +.It -munwind-check=error +These options control what the assembler will do when performing consistency +checks on unwind directives. +.Li -munwind-check=warning +will make the assembler issue a warning when an unwind directive check fails. +This is the default. +.Li -munwind-check=error +will make the assembler issue an error when an unwind directive check fails. +.Pp +.It -mhint.b=ok +.It -mhint.b=warning +.It -mhint.b=error +These options control what the assembler will do when the +.Li hint.b +instruction is used. +.Li -mhint.b=ok +will make the assembler accept +.Li hint.b . +.Li -mint.b=warning +will make the assembler issue a warning when +.Li hint.b +is used. +.Li -mhint.b=error +will make the assembler treat +.Li hint.b +as an error, which is the default. +.Pp +.It -x +.It -xexplicit +These options turn on dependency violation checking. +.Pp +.It -xauto +This option instructs the assembler to automatically insert stop bits where +necessary to remove dependency violations. This is the default mode. +.Pp +.It -xnone +This option turns off dependency violation checking. +.Pp +.It -xdebug +This turns on debug output intended to help tracking down bugs in the dependency +violation checker. +.Pp +.It -xdebugn +This is a shortcut for -xnone -xdebug. +.Pp +.It -xdebugx +This is a shortcut for -xexplicit -xdebug. +.Pp +.El +.Ss Syntax +The assembler syntax closely follows the IA-64 Assembly Language Reference +Guide. +.Pp +.Em Special Characters +.Pp +.Li // +is the line comment token. +.Pp +.Li ; +can be used instead of a newline to separate statements. +.Pp +.Em Register Names +.Pp +The 128 integer registers are referred to as +.Li r Va n . +The 128 floating-point registers are referred to as +.Li f Va n . +The 128 application registers are referred to as +.Li ar Va n . +The 128 control registers are referred to as +.Li cr Va n . +The 64 one-bit predicate registers are referred to as +.Li p Va n . +The 8 branch registers are referred to as +.Li b Va n . +In addition, the assembler defines a number of aliases: +.Li gp +( +.Li r1 ) , +.Li sp +( +.Li r12 ) , +.Li rp +( +.Li b0 ) , +.Li ret0 +( +.Li r8 ) , +.Li ret1 +( +.Li r9 ) , +.Li ret2 +( +.Li r10 ) , +.Li ret3 +( +.Li r9 ) , +.Li farg Va n +( +.Li f8+ Va n ) , +and +.Li fret Va n +( +.Li f8+ Va n ) . +.Pp +For convenience, the assembler also defines aliases for all named application +and control registers. For example, +.Li ar.bsp +refers to the register backing store pointer ( +.Li ar17 ) . +Similarly, +.Li cr.eoi +refers to the end-of-interrupt register ( +.Li cr67 ) . +.Pp +.Em IA-64 Processor-Status-Register (PSR) Bit Names +.Pp +The assembler defines bit masks for each of the bits in the IA-64 processor +status register. For example, +.Li psr.ic +corresponds to a value of 0x2000. These masks are primarily intended for use +with the +.Li ssm +/ +.Li sum +and +.Li rsm +/ +.Li rum +instructions, but they can be used anywhere else where an integer constant +is expected. +.Pp +.Ss Opcodes +For detailed information on the IA-64 machine instruction set, see the +.Lk http://developer.intel.com/design/itanium/arch_spec.htm . +.Pp +.Sh MIPS Dependent Features +GNU +.Li as +for mips architectures supports several different mips processors, and MIPS +ISA levels I through V, MIPS32, and MIPS64. For information about the mips +instruction set, see +.Em MIPS RISC Architecture , +by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions, +see \(lqAppendix D: Assembly Language Programming\(rq in the same work. +.Pp +.Ss Assembler options +The mips configurations of GNU +.Li as +support these special options: +.Pp +.Bl -tag -width Ds +.It -G Va num +This option sets the largest size of an object that can be referenced implicitly +with the +.Li gp +register. It is only accepted for targets that use ecoff format. The default +value is 8. +.Pp +.It -EB +.It -EL +Any mips configuration of +.Li as +can select big-endian or little-endian output at run time (unlike the other +GNU development tools, which must be configured for one or the other). Use +.Li -EB +to select big-endian output, and +.Li -EL +for little-endian. +.Pp +.It -KPIC +Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style +position-independent macro expansions. It also tells the assembler to mark +the output file as PIC. +.Pp +.It -mvxworks-pic +Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style +position-independent macro expansions. +.Pp +.It -mips1 +.It -mips2 +.It -mips3 +.It -mips4 +.It -mips5 +.It -mips32 +.It -mips32r2 +.It -mips64 +.It -mips64r2 +Generate code for a particular MIPS Instruction Set Architecture level. +.Li -mips1 +corresponds to the r2000 and r3000 processors, +.Li -mips2 +to the r6000 processor, +.Li -mips3 +to the r4000 processor, and +.Li -mips4 +to the r8000 and r10000 processors. +.Li -mips5 , +.Li -mips32 , +.Li -mips32r2 , +.Li -mips64 , +and +.Li -mips64r2 +correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64 +Release 2 ISA processors, respectively. You can also switch instruction sets +during the assembly; see MIPS ISA, Directives to override the ISA level. +.Pp +.It -mgp32 +.It -mfp32 +Some macros have different expansions for 32-bit and 64-bit registers. The +register sizes are normally inferred from the ISA and ABI, but these flags +force a certain group of registers to be treated as 32 bits wide at all times. +.Li -mgp32 +controls the size of general-purpose registers and +.Li -mfp32 +controls the size of floating-point registers. +.Pp +The +.Li .set gp=32 +and +.Li .set fp=32 +directives allow the size of registers to be changed for parts of an object. +The default value is restored by +.Li .set gp=default +and +.Li .set fp=default . +.Pp +On some MIPS variants there is a 32-bit mode flag; when this flag is set, +64-bit instructions generate a trap. Also, some 32-bit OSes only save the +32-bit registers on a context switch, so it is essential never to use the +64-bit registers. +.Pp +.It -mgp64 +.It -mfp64 +Assume that 64-bit registers are available. This is provided in the interests +of symmetry with +.Li -mgp32 +and +.Li -mfp32 . +.Pp +The +.Li .set gp=64 +and +.Li .set fp=64 +directives allow the size of registers to be changed for parts of an object. +The default value is restored by +.Li .set gp=default +and +.Li .set fp=default . +.Pp +.It -mips16 +.It -no-mips16 +Generate code for the MIPS 16 processor. This is equivalent to putting +.Li .set mips16 +at the start of the assembly file. +.Li -no-mips16 +turns off this option. +.Pp +.It -msmartmips +.It -mno-smartmips +Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides +a number of new instructions which target smartcard and cryptographic applications. +This is equivalent to putting +.Li .set smartmips +at the start of the assembly file. +.Li -mno-smartmips +turns off this option. +.Pp +.It -mips3d +.It -no-mips3d +Generate code for the MIPS-3D Application Specific Extension. This tells the +assembler to accept MIPS-3D instructions. +.Li -no-mips3d +turns off this option. +.Pp +.It -mdmx +.It -no-mdmx +Generate code for the MDMX Application Specific Extension. This tells the +assembler to accept MDMX instructions. +.Li -no-mdmx +turns off this option. +.Pp +.It -mdsp +.It -mno-dsp +Generate code for the DSP Release 1 Application Specific Extension. This tells +the assembler to accept DSP Release 1 instructions. +.Li -mno-dsp +turns off this option. +.Pp +.It -mdspr2 +.It -mno-dspr2 +Generate code for the DSP Release 2 Application Specific Extension. This option +implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. +.Li -mno-dspr2 +turns off this option. +.Pp +.It -mmt +.It -mno-mt +Generate code for the MT Application Specific Extension. This tells the assembler +to accept MT instructions. +.Li -mno-mt +turns off this option. +.Pp +.It -mfix7000 +.It -mno-fix7000 +Cause nops to be inserted if the read of the destination register of an mfhi +or mflo instruction occurs in the following two instructions. +.Pp +.It -mfix-vr4120 +.It -no-mfix-vr4120 +Insert nops to work around certain VR4120 errata. This option is intended +to be used on GCC-generated code: it is not designed to catch all problems +in hand-written assembler code. +.Pp +.It -mfix-vr4130 +.It -no-mfix-vr4130 +Insert nops to work around the VR4130 +.Li mflo +/ +.Li mfhi +errata. +.Pp +.It -m4010 +.It -no-m4010 +Generate code for the LSI r4010 chip. This tells the assembler to accept the +r4010 specific instructions ( +.Li addciu , +.Li ffc , +etc.), and to not schedule +.Li nop +instructions around accesses to the +.Li HI +and +.Li LO +registers. +.Li -no-m4010 +turns off this option. +.Pp +.It -m4650 +.It -no-m4650 +Generate code for the MIPS r4650 chip. This tells the assembler to accept +the +.Li mad +and +.Li madu +instruction, and to not schedule +.Li nop +instructions around accesses to the +.Li HI +and +.Li LO +registers. +.Li -no-m4650 +turns off this option. +.Pp +.It -m3900 +.It -no-m3900 +.It -m4100 +.It -no-m4100 +For each option +.Li -m Va nnnn , +generate code for the MIPS r +.Va nnnn +chip. This tells the assembler to accept instructions specific to that chip, +and to schedule for that chip's hazards. +.Pp +.It -march= Va cpu +Generate code for a particular MIPS cpu. It is exactly equivalent to +.Li -m Va cpu , +except that there are more value of +.Va cpu +understood. Valid +.Va cpu +value are: +.Pp +.Qo +2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400, +4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500, +6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, +4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, +34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a +.Qc +.Pp +.It -mtune= Va cpu +Schedule and tune for a particular MIPS cpu. Valid +.Va cpu +values are identical to +.Li -march= Va cpu . +.Pp +.It -mabi= Va abi +Record which ABI the source code uses. The recognized arguments are: +.Li 32 , +.Li n32 , +.Li o64 , +.Li 64 +and +.Li eabi . +.Pp +.It -msym32 +.It -mno-sym32 +Equivalent to adding +.Li .set sym32 +or +.Li .set nosym32 +to the beginning of the assembler input.See Section +.Dq MIPS symbol sizes . +.Pp +.It -nocpp +This option is ignored. It is accepted for command-line compatibility with +other assemblers, which use it to turn off C style preprocessing. With GNU +.Li as , +there is no need for +.Li -nocpp , +because the GNU assembler itself never runs the C preprocessor. +.Pp +.It --construct-floats +.It --no-construct-floats +The +.Li --no-construct-floats +option disables the construction of double width floating point constants +by loading the two halves of the value into the two single width floating +point registers that make up the double width register. This feature is useful +if the processor support the FR bit in its status register, and this bit is +known (by the programmer) to be set. This bit prevents the aliasing of the +double width register by the single width registers. +.Pp +By default +.Li --construct-floats +is selected, allowing construction of these floating point constants. +.Pp +.It --trap +.It --no-break +.Li as +automatically macro expands certain division and multiplication instructions +to check for overflow and division by zero. This option causes +.Li as +to generate code to take a trap exception rather than a break exception when +an error is detected. The trap instructions are only supported at Instruction +Set Architecture level 2 and higher. +.Pp +.It --break +.It --no-trap +Generate code to take a break exception rather than a trap exception when +an error is detected. This is the default. +.Pp +.It -mpdr +.It -mno-pdr +Control generation of +.Li .pdr +sections. Off by default on IRIX, on elsewhere. +.Pp +.It -mshared +.It -mno-shared +When generating code using the Unix calling conventions (selected by +.Li -KPIC +or +.Li -mcall_shared ) , +gas will normally generate code which can go into a shared library. The +.Li -mno-shared +option tells gas to generate code which uses the calling convention, but can +not go into a shared library. The resulting code is slightly more efficient. +This option only affects the handling of the +.Li .cpload +and +.Li .cpsetup +pseudo-ops. +.El +.Pp +.Ss MIPS ECOFF object code +Assembling for a mips ecoff target supports some additional sections besides +the usual +.Li .text , +.Li .data +and +.Li .bss . +The additional sections are +.Li .rdata , +used for read-only data, +.Li .sdata , +used for small data, and +.Li .sbss , +used for small common objects. +.Pp +When assembling for ecoff, the assembler uses the +.Li $gp +( +.Li $28 ) +register to form the address of a \(lqsmall object\(rq. Any object in the +.Li .sdata +or +.Li .sbss +sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects +in the +.Li .bss +section, you can use the +.Li gcc +.Li -G +option to control the size of objects addressed via +.Li $gp ; +the default value is 8, meaning that a reference to any object eight bytes +or smaller uses +.Li $gp . +Passing +.Li -G 0 +to +.Li as +prevents it from using the +.Li $gp +register on the basis of object size (but the assembler uses +.Li $gp +for objects in +.Li .sdata +or +.Li sbss +in any case). The size of an object in the +.Li .bss +section is set by the +.Li .comm +or +.Li .lcomm +directive that defines it. The size of an external object may be set with +the +.Li .extern +directive. For example, +.Li .extern sym,4 +declares that the object at +.Li sym +is 4 bytes in length, whie leaving +.Li sym +otherwise undefined. +.Pp +Using small ecoff objects requires linker support, and assumes that the +.Li $gp +register is correctly initialized (normally done automatically by the startup +code). mips ecoff assembly code must not modify the +.Li $gp +register. +.Pp +.Ss Directives for debugging information +mips ecoff +.Li as +supports several directives used for generating debugging information which +are not support by traditional mips assemblers. These are +.Li .def , +.Li .endef , +.Li .dim , +.Li .file , +.Li .scl , +.Li .size , +.Li .tag , +.Li .type , +.Li .val , +.Li .stabd , +.Li .stabn , +and +.Li .stabs . +The debugging information generated by the three +.Li .stab +directives can only be read by gdb, not by traditional mips debuggers (this +enhancement is required to fully support C++ debugging). These directives +are primarily used by compilers, not assembly language programmers! +.Pp +.Ss Directives to override the size of symbols +The n64 ABI allows symbols to have any 64-bit value. Although this provides +a great deal of flexibility, it means that some macros have much longer expansions +than their 32-bit counterparts. For example, the non-PIC expansion of +.Li dla $4,sym +is usually: +.Pp +.Bd -literal -offset indent +lui $4,%highest(sym) +lui $1,%hi(sym) +daddiu $4,$4,%higher(sym) +daddiu $1,$1,%lo(sym) +dsll32 $4,$4,0 +daddu $4,$4,$1 +.Ed +.Pp +whereas the 32-bit expansion is simply: +.Pp +.Bd -literal -offset indent +lui $4,%hi(sym) +daddiu $4,$4,%lo(sym) +.Ed +.Pp +n64 code is sometimes constructed in such a way that all symbolic constants +are known to have 32-bit values, and in such cases, it's preferable to use +the 32-bit expansion instead of the 64-bit expansion. +.Pp +You can use the +.Li .set sym32 +directive to tell the assembler that, from this point on, all expressions +of the form +.Li Va symbol +or +.Li Va symbol + Va offset +have 32-bit values. For example: +.Pp +.Bd -literal -offset indent +\&.set sym32 +dla $4,sym +lw $4,sym+16 +sw $4,sym+0x8000($4) +.Ed +.Pp +will cause the assembler to treat +.Li sym , +.Li sym+16 +and +.Li sym+0x8000 +as 32-bit values. The handling of non-symbolic addresses is not affected. +.Pp +The directive +.Li .set nosym32 +ends a +.Li .set sym32 +block and reverts to the normal behavior. It is also possible to change the +symbol size using the command-line options +.Op -msym32 +and +.Op -mno-sym32 . +.Pp +These options and directives are always accepted, but at present, they have +no effect for anything other than n64. +.Pp +.Ss Directives to override the ISA level +GNU +.Li as +supports an additional directive to change the mips Instruction Set Architecture +level on the fly: +.Li .set mips Va n . +.Va n +should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other +than 0 make the assembler accept instructions for the corresponding isa level, +from that point on in the assembly. +.Li .set mips Va n +affects not only which instructions are permitted, but also how certain macros +are expanded. +.Li .set mips0 +restores the isa level to its original level: either the level you selected +with command line options, or the default for your configuration. You can +use this feature to permit specific mips3 instructions while assembling in +32 bit mode. Use this directive with care! +.Pp +The +.Li .set arch= Va cpu +directive provides even finer control. It changes the effective CPU target +and allows the assembler to use instructions specific to a particular CPU. +All CPUs supported by the +.Li -march +command line option are also selectable by this directive. The original value +is restored by +.Li .set arch=default . +.Pp +The directive +.Li .set mips16 +puts the assembler into MIPS 16 mode, in which it will assemble instructions +for the MIPS 16 processor. Use +.Li .set nomips16 +to return to normal 32 bit mode. +.Pp +Traditional mips assemblers do not support this directive. +.Pp +.Ss Directives for extending MIPS 16 bit instructions +By default, MIPS 16 instructions are automatically extended to 32 bits when +necessary. The directive +.Li .set noautoextend +will turn this off. When +.Li .set noautoextend +is in effect, any 32 bit instruction must be explicitly extended with the +.Li .e +modifier (e.g., +.Li li.e $4,1000 ) . +The directive +.Li .set autoextend +may be used to once again automatically extend instructions when necessary. +.Pp +This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers +do not support this directive. +.Pp +.Ss Directive to mark data as an instruction +The +.Li .insn +directive tells +.Li as +that the following data is actually instructions. This makes a difference +in MIPS 16 mode: when loading the address of a label which precedes instructions, +.Li as +automatically adds 1 to the value, so that jumping to the loaded address will +do the right thing. +.Pp +.Ss Directives to save and restore options +The directives +.Li .set push +and +.Li .set pop +may be used to save and restore the current settings for all the options which +are controlled by +.Li .set . +The +.Li .set push +directive saves the current settings on a stack. The +.Li .set pop +directive pops the stack and restores the settings. +.Pp +These directives can be useful inside an macro which must change an option +such as the ISA level or instruction reordering but does not want to change +the state of the code which invoked the macro. +.Pp +Traditional mips assemblers do not support these directives. +.Pp +.Ss Directives to control generation of MIPS ASE instructions +The directive +.Li .set mips3d +makes the assembler accept instructions from the MIPS-3D Application Specific +Extension from that point on in the assembly. The +.Li .set nomips3d +directive prevents MIPS-3D instructions from being accepted. +.Pp +The directive +.Li .set smartmips +makes the assembler accept instructions from the SmartMIPS Application Specific +Extension to the MIPS32 isa from that point on in the assembly. The +.Li .set nosmartmips +directive prevents SmartMIPS instructions from being accepted. +.Pp +The directive +.Li .set mdmx +makes the assembler accept instructions from the MDMX Application Specific +Extension from that point on in the assembly. The +.Li .set nomdmx +directive prevents MDMX instructions from being accepted. +.Pp +The directive +.Li .set dsp +makes the assembler accept instructions from the DSP Release 1 Application +Specific Extension from that point on in the assembly. The +.Li .set nodsp +directive prevents DSP Release 1 instructions from being accepted. +.Pp +The directive +.Li .set dspr2 +makes the assembler accept instructions from the DSP Release 2 Application +Specific Extension from that point on in the assembly. This dirctive implies +.Li .set dsp . +The +.Li .set nodspr2 +directive prevents DSP Release 2 instructions from being accepted. +.Pp +The directive +.Li .set mt +makes the assembler accept instructions from the MT Application Specific Extension +from that point on in the assembly. The +.Li .set nomt +directive prevents MT instructions from being accepted. +.Pp +Traditional mips assemblers do not support these directives. +.Pp +.Sh PowerPC Dependent Features +.Ss Options +The PowerPC chip family includes several successive levels, using the same +core instruction set, but including a few additional instructions at each +level. There are exceptions to this however. For details on what instructions +each variant supports, please see the chip's architecture reference manual. +.Pp +The following table lists all available PowerPC options. +.Pp +.Bl -tag -width Ds +.It -mpwrx | -mpwr2 +Generate code for POWER/2 (RIOS2). +.Pp +.It -mpwr +Generate code for POWER (RIOS1) +.Pp +.It -m601 +Generate code for PowerPC 601. +.Pp +.It -mppc, -mppc32, -m603, -m604 +Generate code for PowerPC 603/604. +.Pp +.It -m403, -m405 +Generate code for PowerPC 403/405. +.Pp +.It -m440 +Generate code for PowerPC 440. BookE and some 405 instructions. +.Pp +.It -m7400, -m7410, -m7450, -m7455 +Generate code for PowerPC 7400/7410/7450/7455. +.Pp +.It -mppc64, -m620 +Generate code for PowerPC 620/625/630. +.Pp +.It -me500, -me500x2 +Generate code for Motorola e500 core complex. +.Pp +.It -mspe +Generate code for Motorola SPE instructions. +.Pp +.It -mppc64bridge +Generate code for PowerPC 64, including bridge insns. +.Pp +.It -mbooke64 +Generate code for 64-bit BookE. +.Pp +.It -mbooke, mbooke32 +Generate code for 32-bit BookE. +.Pp +.It -me300 +Generate code for PowerPC e300 family. +.Pp +.It -maltivec +Generate code for processors with AltiVec instructions. +.Pp +.It -mpower4 +Generate code for Power4 architecture. +.Pp +.It -mpower5 +Generate code for Power5 architecture. +.Pp +.It -mpower6 +Generate code for Power6 architecture. +.Pp +.It -mcell +Generate code for Cell Broadband Engine architecture. +.Pp +.It -mcom +Generate code Power/PowerPC common instructions. +.Pp +.It -many +Generate code for any architecture (PWR/PWRX/PPC). +.Pp +.It -mregnames +Allow symbolic names for registers. +.Pp +.It -mno-regnames +Do not allow symbolic names for registers. +.Pp +.It -mrelocatable +Support for GCC's -mrelocatable option. +.Pp +.It -mrelocatable-lib +Support for GCC's -mrelocatable-lib option. +.Pp +.It -memb +Set PPC_EMB bit in ELF flags. +.Pp +.It -mlittle, -mlittle-endian +Generate code for a little endian machine. +.Pp +.It -mbig, -mbig-endian +Generate code for a big endian machine. +.Pp +.It -msolaris +Generate code for Solaris. +.Pp +.It -mno-solaris +Do not generate code for Solaris. +.El +.Pp +.Ss PowerPC Assembler Directives +A number of assembler directives are available for PowerPC. The following +table is far from complete. +.Pp +.Bl -tag -width Ds +.It .machine "string" +This directive allows you to change the machine for which code is generated. +.Li "string" +may be any of the -m cpu selection options (without the -m) enclosed in double +quotes, +.Li "push" , +or +.Li "pop" . +.Li .machine "push" +saves the currently selected cpu, which may be restored with +.Li .machine "pop" . +.El +.Pp +.Sh SPARC Dependent Features +.Ss Options +The SPARC chip family includes several successive levels, using the same core +instruction set, but including a few additional instructions at each level. +There are exceptions to this however. For details on what instructions each +variant supports, please see the chip's architecture reference manual. +.Pp +By default, +.Li as +assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level +as needed: it switches to successively higher architectures as it encounters +instructions that only exist in the higher levels. +.Pp +If not configured for SPARC v9 ( +.Li sparc64-*-* ) +GAS will not bump passed sparclite by default, an option must be passed to +enable the v9 instructions. +.Pp +GAS treats sparclite as being compatible with v8, unless an architecture is +explicitly requested. SPARC v9 is always incompatible with sparclite. +.Pp +.Bl -tag -width Ds +.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite +.It -Av8plus | -Av8plusa | -Av9 | -Av9a +Use one of the +.Li -A +options to select one of the SPARC architectures explicitly. If you select +an architecture explicitly, +.Li as +reports a fatal error if it encounters an instruction or feature requiring +an incompatible or higher level. +.Pp +.Li -Av8plus +and +.Li -Av8plusa +select a 32 bit environment. +.Pp +.Li -Av9 +and +.Li -Av9a +select a 64 bit environment and are not available unless GAS is explicitly +configured with 64 bit environment support. +.Pp +.Li -Av8plusa +and +.Li -Av9a +enable the SPARC V9 instruction set with UltraSPARC extensions. +.Pp +.It -xarch=v8plus | -xarch=v8plusa +For compatibility with the Solaris v9 assembler. These options are equivalent +to -Av8plus and -Av8plusa, respectively. +.Pp +.It -bump +Warn whenever it is necessary to switch to another level. If an architecture +level is explicitly requested, GAS will not issue warnings until that level +is reached, and will then bump the level as required (except between incompatible +levels). +.Pp +.It -32 | -64 +Select the word size, either 32 bits or 64 bits. These options are only available +with the ELF object file format, and require that the necessary BFD support +has been included. +.El +.Pp +.Ss Enforcing aligned data +SPARC GAS normally permits data to be misaligned. For example, it permits +the +.Li .long +pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris +assemblers issue an error when they see misaligned data. +.Pp +You can use the +.Li --enforce-aligned-data +option to make SPARC GAS also issue an error about misaligned data, just as +the SunOS and Solaris assemblers do. +.Pp +The +.Li --enforce-aligned-data +option is not the default because gcc issues misaligned data pseudo-ops when +it initializes certain packed data structures (structures defined using the +.Li packed +attribute). You may have to assemble with GAS in order to initialize packed +data structures in your own code. +.Pp +.Ss Floating Point +The Sparc uses ieee floating-point numbers. +.Pp +.Ss Sparc Machine Directives +The Sparc version of +.Li as +supports the following additional machine directives: +.Pp +.Bl -tag -width Ds +.It .align +This must be followed by the desired alignment in bytes. +.Pp +.It .common +This must be followed by a symbol name, a positive number, and +.Li "bss" . +This behaves somewhat like +.Li .comm , +but the syntax is different. +.Pp +.It .half +This is functionally identical to +.Li .short . +.Pp +.It .nword +On the Sparc, the +.Li .nword +directive produces native word sized value, ie. if assembling with -32 it +is equivalent to +.Li .word , +if assembling with -64 it is equivalent to +.Li .xword . +.Pp +.It .proc +This directive is ignored. Any text following it on the same line is also +ignored. +.Pp +.It .register +This directive declares use of a global application or system register. It +must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol +name for that register. If symbol name is +.Li #scratch , +it is a scratch register, if it is +.Li #ignore , +it just suppresses any errors about using undeclared global register, but +does not emit any information about it into the object file. This can be useful +e.g. if you save the register before use and restore it after. +.Pp +.It .reserve +This must be followed by a symbol name, a positive number, and +.Li "bss" . +This behaves somewhat like +.Li .lcomm , +but the syntax is different. +.Pp +.It .seg +This must be followed by +.Li "text" , +.Li "data" , +or +.Li "data1" . +It behaves like +.Li .text , +.Li .data , +or +.Li .data 1 . +.Pp +.It .skip +This is functionally identical to the +.Li .space +directive. +.Pp +.It .word +On the Sparc, the +.Li .word +directive produces 32 bit values, instead of the 16 bit values it produces +on many other machines. +.Pp +.It .xword +On the Sparc V9 processor, the +.Li .xword +directive produces 64 bit values. +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making +.Xr as +reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of +.Xr as +work better. Bug reports are your contribution to the maintenance of +.Xr as . +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If the assembler gets a fatal signal, for any input whatever, that is a +.Xr as +bug. Reliable assemblers never crash. +.Pp +.It +If +.Xr as +produces an error message for valid input, that is a bug. +.Pp +.It +If +.Xr as +does not produce an error message for invalid input, that is a bug. However, +you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq +or \(lqsupport for traditional practice\(rq. +.Pp +.It +If you are an experienced user of assemblers, your suggestions for improvement +of +.Xr as +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained +.Xr as +from a support organization, we recommend you contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a symbol you use in an example does not matter. Well, probably it +does not, but one cannot be sure. Perhaps the bug is a stray memory reference +which happens to fetch from the location where that name is stored in memory; +perhaps, if the name were different, the contents of that location would fool +the assembler into doing the right thing despite the bug. Play it safe and +give a specific, complete example. That is the easiest thing for you to do, +and the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of +.Xr as . +.Xr as +announces it if you start it with the +.Li --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of +.Xr as . +.Pp +.It +Any patches you may have applied to the +.Xr as +source. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile +.Xr as +---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the assembler to assemble your example and +observe the bug. To guarantee you will not omit something important, list +them all. A copy of the Makefile (or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file that will reproduce the bug. If the bug is observed +when the assembler is invoked via a compiler, send the assembler source, not +the high level language source. Most compilers will produce the assembler +source when run with the +.Li -S +option. If you are using +.Li gcc , +use the options +.Li -v --save-temps ; +this will save the assembler source in a file with an extension of +.Pa .s , +and also show you exactly how +.Xr as +is being run. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that +.Xr as +gets a fatal signal, then we will certainly notice it. But if the bug is incorrect +output, we might not notice unless it is glaringly wrong. You might as well +not give us a chance to make a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as, your copy of +.Xr as +is out of sync, or you have encountered a bug in the C library on your system. +(This has happened!) Your copy might crash and ours would not. If you told +us to expect a crash, then when ours fails to crash, we would know that the +bug was not happening for us. If you had not told us to expect a crash, then +we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the +.Xr as +source, send us context diffs, as generated by +.Li diff +with the +.Li -u , +.Li -c , +or +.Li -p +option. Always send diffs from the old file to the new file. If you even discuss +something in the +.Xr as +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with a program as complicated as +.Xr as +it is very hard to construct an example that will make the program follow +a certain path through the code. If you do not send us the example, we will +not be able to construct one, so we will not be able to verify that the bug +is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh Acknowledgements +If you have contributed to GAS 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 the maintainer is Ken Raeburn (email +address +.Li raeburn@cyGNUs.com ) . +.Pp +Dean Elsner wrote the original GNU assembler for the VAX. +.Pp +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 +.Pa messages.c , +.Pa input-file.c , +.Pa write.c . +.Pp +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 back ends (including heavy rewrite, +testing, an integration of the coff and b.out back ends), 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 and cpu32, did 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 +\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and +lint. +.Pp +Ken Raeburn wrote the high-level BFD interface code to replace most of the +code in format-specific I/O modules. +.Pp +The original VMS support was contributed by David L. Kashtan. Eric Youngdale +has done much work with it since. +.Pp +The Intel 80386 machine description was written by Eliot Dresselhaus. +.Pp +Minh Tran-Le at IntelliCorp contributed some AIX 386 support. +.Pp +The Motorola 88k machine description was contributed by Devon Bowen of Buffalo +University and Torbjorn Granlund of the Swedish Institute of Computer Science. +.Pp +Keith Knowles at the Open Software Foundation wrote the original MIPS back +end ( +.Pa tc-mips.c , +.Pa 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. +.Pp +Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300), +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. +.Pp +John Gilmore built the AMD 29000 support, added +.Li .include +support, and simplified the configuration of which versions accept which directives. +He updated the 68k machine description so that Motorola's opcodes always produced +fixed-size instructions (e.g., +.Li jsr ) , +while synthetic instructions remained shrinkable ( +.Li jbsr ) . +John fixed many bugs, including true tested cross-compilation support, and +one bug in relaxation that took a week and required the proverbial one-bit +fix. +.Pp +Ian Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for +the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO +Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 +and PowerPC assembler, and made a few other minor patches. +.Pp +Steve Chamberlain made GAS able to generate listings. +.Pp +Hewlett-Packard contributed support for the HP9000/300. +.Pp +Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) +along with a fairly extensive HPPA testsuite (for both SOM and ELF object +formats). This work was supported by both the Center for Software Science +at the University of Utah and CyGNUs Support. +.Pp +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). +.Pp +Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture. +.Pp +Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and +BFD support for openVMS/Alpha. +.Pp +Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* +flavors. +.Pp +David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, +Inc. added support for Xtensa processors. +.Pp +Several engineers at CyGNUs Support have also provided many small bug fixes +and configuration enhancements. +.Pp +Many others have contributed large or small bugfixes and enhancements. If +you have 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 are not +intentionally leaving anyone out. +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document 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. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation 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. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh AS Index diff --git a/contrib/binutils/gas/doc/as.txt b/contrib/binutils/gas/doc/as.txt deleted file mode 100644 index 91334b842db9..000000000000 --- a/contrib/binutils/gas/doc/as.txt +++ /dev/null @@ -1,13924 +0,0 @@ -START-INFO-DIR-ENTRY -* As: (as). The GNU assembler. -* Gas: (as). The GNU assembler. -END-INFO-DIR-ENTRY - -Using as -1 Overview - 1.1 Structure of this Manual - 1.2 The GNU Assembler - 1.3 Object File Formats - 1.4 Command Line - 1.5 Input Files - 1.6 Output (Object) File - 1.7 Error and Warning Messages -2 Command-Line Options - 2.1 Enable Listings: '-a[cdhlns]' - 2.2 '--alternate' - 2.3 '-D' - 2.4 Work Faster: '-f' - 2.5 '.include' Search Path: '-I' PATH - 2.6 Difference Tables: '-K' - 2.7 Include Local Symbols: '-L' - 2.8 Configuring listing output: '--listing' - 2.9 Assemble in MRI Compatibility Mode: '-M' - 2.10 Dependency Tracking: '--MD' - 2.11 Name the Object File: '-o' - 2.12 Join Data and Text Sections: '-R' - 2.13 Display Assembly Statistics: '--statistics' - 2.14 Compatible Output: '--traditional-format' - 2.15 Announce Version: '-v' - 2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' - 2.17 Generate Object File in Spite of Errors: '-Z' -3 Syntax - 3.1 Preprocessing - 3.2 Whitespace - 3.3 Comments - 3.4 Symbols - 3.5 Statements - 3.6 Constants - 3.6.1 Character Constants - 3.6.1.1 Strings - 3.6.1.2 Characters - 3.6.2 Number Constants - 3.6.2.1 Integers - 3.6.2.2 Bignums - 3.6.2.3 Flonums -4 Sections and Relocation - 4.1 Background - 4.2 Linker Sections - 4.3 Assembler Internal Sections - 4.4 Sub-Sections - 4.5 bss Section -5 Symbols - 5.1 Labels - 5.2 Giving Symbols Other Values - 5.3 Symbol Names - 5.4 The Special Dot Symbol - 5.5 Symbol Attributes - 5.5.1 Value - 5.5.2 Type -6 Expressions - 6.1 Empty Expressions - 6.2 Integer Expressions - 6.2.1 Arguments - 6.2.2 Operators - 6.2.3 Prefix Operator - 6.2.4 Infix Operators -7 Assembler Directives - 7.1 '.abort' - 7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.3 '.ascii "STRING"'... - 7.4 '.asciz "STRING"'... - 7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.6 '.byte EXPRESSIONS' - 7.7 '.comm SYMBOL , LENGTH ' - 7.8 '.cfi_startproc [simple]' - 7.9 '.cfi_endproc' - 7.10 '.cfi_personality ENCODING [, EXP]' - 7.11 '.cfi_lsda ENCODING [, EXP]' - 7.12 '.cfi_def_cfa REGISTER, OFFSET' - 7.13 '.cfi_def_cfa_register REGISTER' - 7.14 '.cfi_def_cfa_offset OFFSET' - 7.15 '.cfi_adjust_cfa_offset OFFSET' - 7.16 '.cfi_offset REGISTER, OFFSET' - 7.17 '.cfi_rel_offset REGISTER, OFFSET' - 7.18 '.cfi_register REGISTER1, REGISTER2' - 7.19 '.cfi_restore REGISTER' - 7.20 '.cfi_undefined REGISTER' - 7.21 '.cfi_same_value REGISTER' - 7.22 '.cfi_remember_state', - 7.23 '.cfi_return_column REGISTER' - 7.24 '.cfi_signal_frame' - 7.25 '.cfi_window_save' - 7.26 '.cfi_escape' EXPRESSION[, ...] - 7.27 '.file FILENO FILENAME' - 7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' - 7.29 '.loc_mark_blocks ENABLE' - 7.30 '.data SUBSECTION' - 7.31 '.double FLONUMS' - 7.32 '.eject' - 7.33 '.else' - 7.34 '.elseif' - 7.35 '.end' - 7.36 '.endfunc' - 7.37 '.endif' - 7.38 '.equ SYMBOL, EXPRESSION' - 7.39 '.equiv SYMBOL, EXPRESSION' - 7.40 '.eqv SYMBOL, EXPRESSION' - 7.41 '.err' - 7.42 '.error "STRING"' - 7.43 '.exitm' - 7.44 '.extern' - 7.45 '.fail EXPRESSION' - 7.46 '.file STRING' - 7.47 '.fill REPEAT , SIZE , VALUE' - 7.48 '.float FLONUMS' - 7.49 '.func NAME[,LABEL]' - 7.50 '.global SYMBOL', '.globl SYMBOL' - 7.51 '.hidden NAMES' - 7.52 '.hword EXPRESSIONS' - 7.53 '.ident' - 7.54 '.if ABSOLUTE EXPRESSION' - 7.55 '.incbin "FILE"[,SKIP[,COUNT]]' - 7.56 '.include "FILE"' - 7.57 '.int EXPRESSIONS' - 7.58 '.internal NAMES' - 7.59 '.irp SYMBOL,VALUES'... - 7.60 '.irpc SYMBOL,VALUES'... - 7.61 '.lcomm SYMBOL , LENGTH' - 7.62 '.lflags' - 7.63 '.line LINE-NUMBER' - 7.64 '.linkonce [TYPE]' - 7.65 '.ln LINE-NUMBER' - 7.66 '.mri VAL' - 7.67 '.list' - 7.68 '.long EXPRESSIONS' - 7.69 '.macro' - 7.70 '.altmacro' - 7.71 '.noaltmacro' - 7.72 '.nolist' - 7.73 '.octa BIGNUMS' - 7.74 '.org NEW-LC , FILL' - 7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.76 '.previous' - 7.77 '.popsection' - 7.78 '.print STRING' - 7.79 '.protected NAMES' - 7.80 '.psize LINES , COLUMNS' - 7.81 '.purgem NAME' - 7.82 '.pushsection NAME , SUBSECTION' - 7.83 '.quad BIGNUMS' - 7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' - 7.85 '.rept COUNT' - 7.86 '.sbttl "SUBHEADING"' - 7.87 '.section NAME' - 7.88 '.set SYMBOL, EXPRESSION' - 7.89 '.short EXPRESSIONS' - 7.90 '.single FLONUMS' - 7.91 '.size' - 7.92 '.sleb128 EXPRESSIONS' - 7.93 '.skip SIZE , FILL' - 7.94 '.space SIZE , FILL' - 7.95 '.stabd, .stabn, .stabs' - 7.96 '.string' "STR" - 7.97 '.struct EXPRESSION' - 7.98 '.subsection NAME' - 7.99 '.symver' - 7.100 '.text SUBSECTION' - 7.101 '.title "HEADING"' - 7.102 '.type' - 7.103 '.uleb128 EXPRESSIONS' - 7.104 '.version "STRING"' - 7.105 '.vtable_entry TABLE, OFFSET' - 7.106 '.vtable_inherit CHILD, PARENT' - 7.107 '.warning "STRING"' - 7.108 '.weak NAMES' - 7.109 '.weakref ALIAS, TARGET' - 7.110 '.word EXPRESSIONS' - 7.111 Deprecated Directives -8 ARM Dependent Features - 8.1 Options - 8.2 Syntax - 8.2.1 Special Characters - 8.2.2 Register Names - 8.2.3 ARM relocation generation - 8.3 Floating Point - 8.4 ARM Machine Directives - 8.5 Opcodes - 8.6 Mapping Symbols -9 80386 Dependent Features - 9.1 Options - 9.2 AT&T Syntax versus Intel Syntax - 9.3 Instruction Naming - 9.4 Register Naming - 9.5 Instruction Prefixes - 9.6 Memory References - 9.7 Handling of Jump Instructions - 9.8 Floating Point - 9.9 Intel's MMX and AMD's 3DNow! SIMD Operations - 9.10 Writing 16-bit Code - 9.11 AT&T Syntax bugs - 9.12 Specifying CPU Architecture - 9.13 Notes -10 IA-64 Dependent Features - 10.1 Options - 10.2 Syntax - 10.2.1 Special Characters - 10.2.2 Register Names - 10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names - 10.3 Opcodes -11 MIPS Dependent Features - 11.1 Assembler options - 11.2 MIPS ECOFF object code - 11.3 Directives for debugging information - 11.4 Directives to override the size of symbols - 11.5 Directives to override the ISA level - 11.6 Directives for extending MIPS 16 bit instructions - 11.7 Directive to mark data as an instruction - 11.8 Directives to save and restore options - 11.9 Directives to control generation of MIPS ASE instructions -12 PowerPC Dependent Features - 12.1 Options - 12.2 PowerPC Assembler Directives -13 SPARC Dependent Features - 13.1 Options - 13.2 Enforcing aligned data - 13.3 Floating Point - 13.4 Sparc Machine Directives -14 Reporting Bugs - 14.1 Have You Found a Bug? - 14.2 How to Report Bugs -15 Acknowledgements -Appendix A GNU Free Documentation License - ADDENDUM: How to use this License for your documents -AS Index -Using as -******** - -This file is a user guide to the GNU assembler 'as' version "2.17.50 -[FreeBSD] 2007-07-03". This version of the file describes 'as' -configured to generate code for machine specific architectures. - - This document is distributed under the terms of the GNU Free -Documentation License. A copy of the license is included in the section -entitled "GNU Free Documentation License". - -1 Overview -********** - -Here is a brief summary of how to invoke 'as'. For details, see *note -Command-Line Options: Invoking. - - as [-a[cdhlns][=FILE]] [-alternate] [-D] - [-defsym SYM=VAL] [-f] [-g] [-gstabs] - [-gstabs+] [-gdwarf-2] [-help] [-I DIR] [-J] - [-K] [-L] [-listing-lhs-width=NUM] - [-listing-lhs-width2=NUM] [-listing-rhs-width=NUM] - [-listing-cont-lines=NUM] [-keep-locals] [-o - OBJFILE] [-R] [-reduce-memory-overheads] [-statistics] - [-v] [-version] [-version] [-W] [-warn] - [-fatal-warnings] [-w] [-x] [-Z] [@FILE] - [-target-help] [TARGET-OPTIONS] - [-|FILES ...] - - _Target ARM options:_ - [-mcpu=PROCESSOR[+EXTENSION...]] - [-march=ARCHITECTURE[+EXTENSION...]] - [-mfpu=FLOATING-POINT-FORMAT] - [-mfloat-abi=ABI] - [-meabi=VER] - [-mthumb] - [-EB|-EL] - [-mapcs-32|-mapcs-26|-mapcs-float| - -mapcs-reentrant] - [-mthumb-interwork] [-k] - - _Target i386 options:_ - [-32|-64] [-n] - [-march=CPU] [-mtune=CPU] - - _Target IA-64 options:_ - [-mconstant-gp|-mauto-pic] - [-milp32|-milp64|-mlp64|-mp64] - [-mle|mbe] - [-mtune=itanium1|-mtune=itanium2] - [-munwind-check=warning|-munwind-check=error] - [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] - [-x|-xexplicit] [-xauto] [-xdebug] - - _Target MIPS options:_ - [-nocpp] [-EL] [-EB] [-O[OPTIMIZATION LEVEL]] - [-g[DEBUG LEVEL]] [-G NUM] [-KPIC] [-call_shared] - [-non_shared] [-xgot [-mvxworks-pic] - [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] - [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] - [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] - [-mips64] [-mips64r2] - [-construct-floats] [-no-construct-floats] - [-trap] [-no-break] [-break] [-no-trap] - [-mfix7000] [-mno-fix7000] - [-mips16] [-no-mips16] - [-msmartmips] [-mno-smartmips] - [-mips3d] [-no-mips3d] - [-mdmx] [-no-mdmx] - [-mdsp] [-mno-dsp] - [-mdspr2] [-mno-dspr2] - [-mmt] [-mno-mt] - [-mdebug] [-no-mdebug] - [-mpdr] [-mno-pdr] - - _Target PowerPC options:_ - [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| - -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| - -mbooke32|-mbooke64] - [-mcom|-many|-maltivec] [-memb] - [-mregnames|-mno-regnames] - [-mrelocatable|-mrelocatable-lib] - [-mlittle|-mlittle-endian|-mbig|-mbig-endian] - [-msolaris|-mno-solaris] - - _Target SPARC options:_ - [-Av6|-Av7|-Av8|-Asparclet|-Asparclite - -Av8plus|-Av8plusa|-Av9|-Av9a] - [-xarch=v8plus|-xarch=v8plusa] [-bump] - [-32|-64] - - - -'@FILE' - Read command-line options from FILE. The options read are inserted - in place of the original @FILE option. If FILE does not exist, or - cannot be read, then the option will be treated literally, and not - removed. - - Options in FILE are separated by whitespace. A whitespace - character may be included in an option by surrounding the entire - option in either single or double quotes. Any character (including - a backslash) may be included by prefixing the character to be - included with a backslash. The FILE may itself contain additional - @FILE options; any such options will be processed recursively. - -'-a[cdhlmns]' - Turn on listings, in any of a variety of ways: - - '-ac' - omit false conditionals - - '-ad' - omit debugging directives - - '-ah' - include high-level source - - '-al' - include assembly - - '-am' - include macro expansions - - '-an' - omit forms processing - - '-as' - include symbols - - '=file' - set the name of the listing file - - You may combine these options; for example, use '-aln' for assembly - listing without forms processing. The '=file' option, if used, - must be the last one. By itself, '-a' defaults to '-ahls'. - -'--alternate' - Begin in alternate macro mode. *Note '.altmacro': Altmacro. - -'-D' - Ignored. This option is accepted for script compatibility with - calls to other assemblers. - -'--defsym SYM=VALUE' - Define the symbol SYM to be VALUE before assembling the input file. - VALUE must be an integer constant. As in C, a leading '0x' - indicates a hexadecimal value, and a leading '0' indicates an octal - value. The value of the symbol can be overridden inside a source - file via the use of a '.set' pseudo-op. - -'-f' - "fast"--skip whitespace and comment preprocessing (assume source is - compiler output). - -'-g' -'--gen-debug' - Generate debugging information for each assembler source line using - whichever debug format is preferred by the target. This currently - means either STABS, ECOFF or DWARF2. - -'--gstabs' - Generate stabs debugging information for each assembler line. This - may help debugging assembler code, if the debugger can handle it. - -'--gstabs+' - Generate stabs debugging information for each assembler line, with - GNU extensions that probably only gdb can handle, and that could - make other debuggers crash or refuse to read your program. This - may help debugging assembler code. Currently the only GNU - extension is the location of the current working directory at - assembling time. - -'--gdwarf-2' - Generate DWARF2 debugging information for each assembler line. - This may help debugging assembler code, if the debugger can handle - it. Note--this option is only supported by some targets, not all - of them. - -'--help' - Print a summary of the command line options and exit. - -'--target-help' - Print a summary of all target specific options and exit. - -'-I DIR' - Add directory DIR to the search list for '.include' directives. - -'-J' - Don't warn about signed overflow. - -'-K' - This option is accepted but has no effect on the machine specific - family. - -'-L' -'--keep-locals' - Keep (in the symbol table) local symbols. These symbols start with - system-specific local label prefixes, typically '.L' for ELF - systems or 'L' for traditional a.out systems. *Note Symbol - Names::. - -'--listing-lhs-width=NUMBER' - Set the maximum width, in words, of the output data column for an - assembler listing to NUMBER. - -'--listing-lhs-width2=NUMBER' - Set the maximum width, in words, of the output data column for - continuation lines in an assembler listing to NUMBER. - -'--listing-rhs-width=NUMBER' - Set the maximum width of an input source line, as displayed in a - listing, to NUMBER bytes. - -'--listing-cont-lines=NUMBER' - Set the maximum number of lines printed in a listing for a single - line of input to NUMBER + 1. - -'-o OBJFILE' - Name the object-file output from 'as' OBJFILE. - -'-R' - Fold the data section into the text section. - - Set the default size of GAS's hash tables to a prime number close - to NUMBER. Increasing this value can reduce the length of time it - takes the assembler to perform its tasks, at the expense of - increasing the assembler's memory requirements. Similarly reducing - this value can reduce the memory requirements at the expense of - speed. - -'--reduce-memory-overheads' - This option reduces GAS's memory requirements, at the expense of - making the assembly processes slower. Currently this switch is a - synonym for '--hash-size=4051', but in the future it may have other - effects as well. - -'--statistics' - Print the maximum space (in bytes) and total time (in seconds) used - by assembly. - -'--strip-local-absolute' - Remove local absolute symbols from the outgoing symbol table. - -'-v' -'-version' - Print the 'as' version. - -'--version' - Print the 'as' version and exit. - -'-W' -'--no-warn' - Suppress warning messages. - -'--fatal-warnings' - Treat warnings as errors. - -'--warn' - Don't suppress warning messages or treat them as errors. - -'-w' - Ignored. - -'-x' - Ignored. - -'-Z' - Generate an object file even after errors. - -'-- | FILES ...' - Standard input, or source files to assemble. - - The following options are available when as is configured for the ARM -processor family. - -'-mcpu=PROCESSOR[+EXTENSION...]' - Specify which ARM processor variant is the target. -'-march=ARCHITECTURE[+EXTENSION...]' - Specify which ARM architecture variant is used by the target. -'-mfpu=FLOATING-POINT-FORMAT' - Select which Floating Point architecture is the target. -'-mfloat-abi=ABI' - Select which floating point ABI is in use. -'-mthumb' - Enable Thumb only instruction decoding. -'-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant' - Select which procedure calling convention is in use. -'-EB | -EL' - Select either big-endian (-EB) or little-endian (-EL) output. -'-mthumb-interwork' - Specify that the code has been generated with interworking between - Thumb and ARM code in mind. -'-k' - Specify that PIC code has been generated. - - The following options are available when 'as' is configured for the -SPARC architecture: - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - Explicitly select a variant of the SPARC architecture. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. '-Av9' and - '-Av9a' select a 64 bit environment. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn when the assembler switches to another architecture. - - The following options are available when as is configured for a MIPS -processor. - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format, such as a DECstation running - Ultrix. The default value is 8. - -'-EB' - Generate "big endian" format output. - -'-EL' - Generate "little endian" format output. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' is an alias for '-march=r3000', '-mips2' is an - alias for '-march=r6000', '-mips3' is an alias for '-march=r4000' - and '-mips4' is an alias for '-march=r8000'. '-mips5', '-mips32', - '-mips32r2', '-mips64', and '-mips64r2' correspond to generic 'MIPS - V', 'MIPS32', 'MIPS32 Release 2', 'MIPS64', and 'MIPS64 Release 2' - ISA processors, respectively. - -'-march=CPU' - Generate code for a particular MIPS cpu. - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. - -'-mfix7000' -'-mno-fix7000' - Cause nops to be inserted if the read of the destination register - of an mfhi or mflo instruction occurs in the following two - instructions. - -'-mdebug' -'-no-mdebug' - Cause stabs-style debugging output to go into an ECOFF-style - .mdebug section instead of the standard ELF .stabs sections. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. - -'-mgp32' -'-mfp32' - The register sizes are normally inferred from the ISA and ABI, but - these flags force a certain group of registers to be treated as 32 - bits wide at all times. '-mgp32' controls the size of - general-purpose registers and '-mfp32' controls the size of - floating-point registers. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extension to the MIPS32 instruction set. - This is equivalent to putting '.set smartmips' at the start of the - assembly file. '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-mno-dspr2' - Generate code for the DSP Release 2 Application Specific Extension. - This option implies -mdsp. This tells the assembler to accept DSP - Release 2 instructions. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'--construct-floats' -'--no-construct-floats' - The '--no-construct-floats' option disables the construction of - double width floating point constants by loading the two halves of - the value into the two single width floating point registers that - make up the double width register. By default '--construct-floats' - is selected, allowing construction of these floating point - constants. - -'--emulation=NAME' - This option causes 'as' to emulate 'as' configured for some other - target, in all respects, including output format (choosing between - ELF and ECOFF only), handling of pseudo-opcodes which may generate - debugging information or store symbol table information, and - default endianness. The available configuration names are: - 'mipsecoff', 'mipself', 'mipslecoff', 'mipsbecoff', 'mipslelf', - 'mipsbelf'. The first two do not alter the default endianness from - that of the primary target for which the assembler was configured; - the others change the default to little- or big-endian as indicated - by the 'b' or 'l' in the name. Using '-EB' or '-EL' will override - the endianness selection in any case. - - This option is currently supported only when the primary target - 'as' is configured for is a MIPS ELF or ECOFF target. Furthermore, - the primary target or others specified with '--enable-targets=...' - at configuration time must include support for the other format, if - both are to be available. For example, the Irix 5 configuration - includes support for both. - - Eventually, this option will support more configurations, with more - fine-grained control over the assembler's behavior, and will be - supported for more processors. - -'-nocpp' - 'as' ignores this option. It is accepted for compatibility with - the native tools. - -'--trap' -'--no-trap' -'--break' -'--no-break' - Control how to deal with multiplication overflow and division by - zero. '--trap' or '--no-break' (which are synonyms) take a trap - exception (and only work for Instruction Set Architecture level 2 - and higher); '--break' or '--no-trap' (also synonyms, and the - default) take a break exception. - -'-n' - When this option is used, 'as' will issue a warning every time it - generates a nop instruction from a macro. - -1.1 Structure of this Manual -============================ - -This manual is intended to describe what you need to know to use GNU -'as'. We cover the syntax expected in source files, including notation -for symbols, constants, and expressions; the directives that 'as' -understands; and of course how to invoke 'as'. - - We also cover special features in the machine specific configuration -of 'as', including assembler directives. - - On the other hand, this manual is _not_ intended as an introduction -to programming in assembly language--let alone programming in general! -In a similar vein, we make no attempt to introduce the machine -architecture; we do _not_ describe the instruction set, standard -mnemonics, registers or addressing modes that are standard to a -particular architecture. - -1.2 The GNU Assembler -===================== - -GNU 'as' is really a family of assemblers. This manual describes 'as', -a member of that family which is configured for the machine specific -architectures. If you use (or have used) the GNU assembler on one -architecture, you should find a fairly similar environment when you use -it on another architecture. Each version has much in common with the -others, including object file formats, most assembler directives (often -called "pseudo-ops") and assembler syntax. - - 'as' is primarily intended to assemble the output of the GNU C -compiler 'gcc' for use by the linker 'ld'. Nevertheless, we've tried to -make 'as' assemble correctly everything that other assemblers for the -same machine would assemble. - - Unlike older assemblers, 'as' is designed to assemble a source -program in one pass of the source file. This has a subtle impact on the -'.org' directive (*note '.org': Org.). - -1.3 Object File Formats -======================= - -The GNU assembler can be configured to produce several alternative -object file formats. For the most part, this does not affect how you -write assembly language programs; but directives for debugging symbols -are typically different in different file formats. *Note Symbol -Attributes: Symbol Attributes. For the machine specific target, 'as' is -configured to produce ELF format object files. - -1.4 Command Line -================ - -After the program name 'as', the command line may contain options and -file names. Options may appear in any order, and may be before, after, -or between file names. The order of file names is significant. - - '--' (two hyphens) by itself names the standard input file -explicitly, as one of the files for 'as' to assemble. - - Except for '--' any command line argument that begins with a hyphen -('-') is an option. Each option changes the behavior of 'as'. No -option changes the way another option works. An option is a '-' -followed by one or more letters; the case of the letter is important. -All options are optional. - - Some options expect exactly one file name to follow them. The file -name may either immediately follow the option's letter (compatible with -older assemblers) or it may be the next command argument (GNU standard). -These two command lines are equivalent: - - as -o my-object-file.o mumble.s - as -omy-object-file.o mumble.s - -1.5 Input Files -=============== - -We use the phrase "source program", abbreviated "source", to describe -the program input to one run of 'as'. The program may be in one or more -files; how the source is partitioned into files doesn't change the -meaning of the source. - - The source program is a concatenation of the text in all the files, -in the order specified. - - Each time you run 'as' it assembles exactly one source program. The -source program is made up of one or more files. (The standard input is -also a file.) - - You give 'as' a command line that has zero or more input file names. -The input files are read (from left file name to right). A command line -argument (in any position) that has no special meaning is taken to be an -input file name. - - If you give 'as' no file names it attempts to read one input file -from the 'as' standard input, which is normally your terminal. You may -have to type <ctl-D> to tell 'as' there is no more program to assemble. - - Use '--' if you need to explicitly name the standard input file in -your command line. - - If the source is empty, 'as' produces a small, empty object file. - -Filenames and Line-numbers --------------------------- - -There are two ways of locating a line in the input file (or files) and -either may be used in reporting error messages. One way refers to a -line number in a physical file; the other refers to a line number in a -"logical" file. *Note Error and Warning Messages: Errors. - - "Physical files" are those files named in the command line given to -'as'. - - "Logical files" are simply names declared explicitly by assembler -directives; they bear no relation to physical files. Logical file names -help error messages reflect the original source file, when 'as' source -is itself synthesized from other files. 'as' understands the '#' -directives emitted by the 'gcc' preprocessor. See also *note '.file': -File. - -1.6 Output (Object) File -======================== - -Every time you run 'as' it produces an output file, which is your -assembly language program translated into numbers. This file is the -object file. Its default name is 'a.out'. You can give it another name -by using the '-o' option. Conventionally, object file names end with -'.o'. The default name is used for historical reasons: older assemblers -were capable of assembling self-contained programs directly into a -runnable program. (For some formats, this isn't currently possible, but -it can be done for the 'a.out' format.) - - The object file is meant for input to the linker 'ld'. It contains -assembled program code, information to help 'ld' integrate the assembled -program into a runnable file, and (optionally) symbolic information for -the debugger. - -1.7 Error and Warning Messages -============================== - -'as' may write warnings and error messages to the standard error file -(usually your terminal). This should not happen when a compiler runs -'as' automatically. Warnings report an assumption made so that 'as' -could keep assembling a flawed program; errors report a grave problem -that stops the assembly. - - Warning messages have the format - - file_name:NNN:Warning Message Text - -(where NNN is a line number). If a logical file name has been given -(*note '.file': File.) it is used for the filename, otherwise the name -of the current input file is used. If a logical line number was given -then it is used to calculate the number printed, otherwise the actual -line in the current source file is printed. The message text is -intended to be self explanatory (in the grand Unix tradition). - - Error messages have the format - file_name:NNN:FATAL:Error Message Text - The file name and line number are derived as for warning messages. -The actual message text may be rather less explanatory because many of -them aren't supposed to happen. - -2 Command-Line Options -********************** - -This chapter describes command-line options available in _all_ versions -of the GNU assembler; see *note Machine Dependencies::, for options -specific to the machine specific target. - - If you are invoking 'as' via the GNU C compiler, you can use the -'-Wa' option to pass arguments through to the assembler. The assembler -arguments must be separated from each other (and the '-Wa') by commas. -For example: - - gcc -c -g -O -Wa,-alh,-L file.c - -This passes two options to the assembler: '-alh' (emit a listing to -standard output with high-level and assembly source) and '-L' (retain -local symbols in the symbol table). - - Usually you do not need to use this '-Wa' mechanism, since many -compiler command-line options are automatically passed to the assembler -by the compiler. (You can call the GNU compiler driver with the '-v' -option to see precisely what options it passes to each compilation pass, -including the assembler.) - -2.1 Enable Listings: '-a[cdhlns]' -================================= - -These options enable listing output from the assembler. By itself, '-a' -requests high-level, assembly, and symbols listing. You can use other -letters to select specific options for the list: '-ah' requests a -high-level language listing, '-al' requests an output-program assembly -listing, and '-as' requests a symbol table listing. High-level listings -require that a compiler debugging option like '-g' be used, and that -assembly listings ('-al') be requested also. - - Use the '-ac' option to omit false conditionals from a listing. Any -lines which are not assembled because of a false '.if' (or '.ifdef', or -any other conditional), or a true '.if' followed by an '.else', will be -omitted from the listing. - - Use the '-ad' option to omit debugging directives from the listing. - - Once you have specified one of these options, you can further control -listing output and its appearance using the directives '.list', -'.nolist', '.psize', '.eject', '.title', and '.sbttl'. The '-an' option -turns off all forms processing. If you do not request listing output -with one of the '-a' options, the listing-control directives have no -effect. - - The letters after '-a' may be combined into one option, _e.g._, -'-aln'. - - Note if the assembler source is coming from the standard input (e.g., -because it is being created by 'gcc' and the '-pipe' command line switch -is being used) then the listing will not contain any comments or -preprocessor directives. This is because the listing code buffers input -source lines from stdin only after they have been preprocessed by the -assembler. This reduces memory usage and makes the code more efficient. - -2.2 '--alternate' -================= - -Begin in alternate macro mode, see *note '.altmacro': Altmacro. - -2.3 '-D' -======== - -This option has no effect whatsoever, but it is accepted to make it more -likely that scripts written for other assemblers also work with 'as'. - -2.4 Work Faster: '-f' -===================== - -'-f' should only be used when assembling programs written by a (trusted) -compiler. '-f' stops the assembler from doing whitespace and comment -preprocessing on the input file(s) before assembling them. *Note -Preprocessing: Preprocessing. - - _Warning:_ if you use '-f' when the files actually need to be - preprocessed (if they contain comments, for example), 'as' does not - work correctly. - -2.5 '.include' Search Path: '-I' PATH -===================================== - -Use this option to add a PATH to the list of directories 'as' searches -for files specified in '.include' directives (*note '.include': -Include.). You may use '-I' as many times as necessary to include a -variety of paths. The current working directory is always searched -first; after that, 'as' searches any '-I' directories in the same order -as they were specified (left to right) on the command line. - -2.6 Difference Tables: '-K' -=========================== - -On the machine specific family, this option is allowed, but has no -effect. It is permitted for compatibility with the GNU assembler on -other platforms, where it can be used to warn when the assembler alters -the machine code generated for '.word' directives in difference tables. -The machine specific family does not have the addressing limitations -that sometimes lead to this alteration on other platforms. - -2.7 Include Local Symbols: '-L' -=============================== - -Symbols beginning with system-specific local label prefixes, typically -'.L' for ELF systems or 'L' for traditional a.out systems, are called -"local symbols". *Note Symbol Names::. Normally you do not see such -symbols when debugging, because they are intended for the use of -programs (like compilers) that compose assembler programs, not for your -notice. Normally both 'as' and 'ld' discard such symbols, so you do not -normally debug with them. - - This option tells 'as' to retain those local symbols in the object -file. Usually if you do this you also tell the linker 'ld' to preserve -those symbols. - -2.8 Configuring listing output: '--listing' -=========================================== - -The listing feature of the assembler can be enabled via the command line -switch '-a' (*note a::). This feature combines the input source file(s) -with a hex dump of the corresponding locations in the output object -file, and displays them as a listing file. The format of this listing -can be controlled by directives inside the assembler source (i.e., -'.list' (*note List::), '.title' (*note Title::), '.sbttl' (*note -Sbttl::), '.psize' (*note Psize::), and '.eject' (*note Eject::) and -also by the following switches: - -'--listing-lhs-width='number'' - Sets the maximum width, in words, of the first line of the hex byte - dump. This dump appears on the left hand side of the listing - output. - -'--listing-lhs-width2='number'' - Sets the maximum width, in words, of any further lines of the hex - byte dump for a given input source line. If this value is not - specified, it defaults to being the same as the value specified for - '--listing-lhs-width'. If neither switch is used the default is to - one. - -'--listing-rhs-width='number'' - Sets the maximum width, in characters, of the source line that is - displayed alongside the hex dump. The default value for this - parameter is 100. The source line is displayed on the right hand - side of the listing output. - -'--listing-cont-lines='number'' - Sets the maximum number of continuation lines of hex dump that will - be displayed for a given single line of source input. The default - value is 4. - -2.9 Assemble in MRI Compatibility Mode: '-M' -============================================ - -The '-M' or '--mri' option selects MRI compatibility mode. This changes -the syntax and pseudo-op handling of 'as' to make it compatible with the -'ASM68K' or the 'ASM960' (depending upon the configured target) -assembler from Microtec Research. The exact nature of the MRI syntax -will not be documented here; see the MRI manuals for more information. -Note in particular that the handling of macros and macro arguments is -somewhat different. The purpose of this option is to permit assembling -existing MRI assembler code using 'as'. - - The MRI compatibility is not complete. Certain operations of the MRI -assembler depend upon its object file format, and can not be supported -using other object file formats. Supporting these would require -enhancing each object file format individually. These are: - - * global symbols in common section - - The m68k MRI assembler supports common sections which are merged by - the linker. Other object file formats do not support this. 'as' - handles common sections by treating them as a single common symbol. - It permits local symbols to be defined within a common section, but - it can not support global symbols, since it has no way to describe - them. - - * complex relocations - - The MRI assemblers support relocations against a negated section - address, and relocations which combine the start addresses of two - or more sections. These are not support by other object file - formats. - - * 'END' pseudo-op specifying start address - - The MRI 'END' pseudo-op permits the specification of a start - address. This is not supported by other object file formats. The - start address may instead be specified using the '-e' option to the - linker, or in a linker script. - - * 'IDNT', '.ident' and 'NAME' pseudo-ops - - The MRI 'IDNT', '.ident' and 'NAME' pseudo-ops assign a module name - to the output file. This is not supported by other object file - formats. - - * 'ORG' pseudo-op - - The m68k MRI 'ORG' pseudo-op begins an absolute section at a given - address. This differs from the usual 'as' '.org' pseudo-op, which - changes the location within the current section. Absolute sections - are not supported by other object file formats. The address of a - section may be assigned within a linker script. - - There are some other features of the MRI assembler which are not -supported by 'as', typically either because they are difficult or -because they seem of little consequence. Some of these may be supported -in future releases. - - * EBCDIC strings - - EBCDIC strings are not supported. - - * packed binary coded decimal - - Packed binary coded decimal is not supported. This means that the - 'DC.P' and 'DCB.P' pseudo-ops are not supported. - - * 'FEQU' pseudo-op - - The m68k 'FEQU' pseudo-op is not supported. - - * 'NOOBJ' pseudo-op - - The m68k 'NOOBJ' pseudo-op is not supported. - - * 'OPT' branch control options - - The m68k 'OPT' branch control options--'B', 'BRS', 'BRB', 'BRL', - and 'BRW'--are ignored. 'as' automatically relaxes all branches, - whether forward or backward, to an appropriate size, so these - options serve no purpose. - - * 'OPT' list control options - - The following m68k 'OPT' list control options are ignored: 'C', - 'CEX', 'CL', 'CRE', 'E', 'G', 'I', 'M', 'MEX', 'MC', 'MD', 'X'. - - * other 'OPT' options - - The following m68k 'OPT' options are ignored: 'NEST', 'O', 'OLD', - 'OP', 'P', 'PCO', 'PCR', 'PCS', 'R'. - - * 'OPT' 'D' option is default - - The m68k 'OPT' 'D' option is the default, unlike the MRI assembler. - 'OPT NOD' may be used to turn it off. - - * 'XREF' pseudo-op. - - The m68k 'XREF' pseudo-op is ignored. - - * '.debug' pseudo-op - - The i960 '.debug' pseudo-op is not supported. - - * '.extended' pseudo-op - - The i960 '.extended' pseudo-op is not supported. - - * '.list' pseudo-op. - - The various options of the i960 '.list' pseudo-op are not - supported. - - * '.optimize' pseudo-op - - The i960 '.optimize' pseudo-op is not supported. - - * '.output' pseudo-op - - The i960 '.output' pseudo-op is not supported. - - * '.setreal' pseudo-op - - The i960 '.setreal' pseudo-op is not supported. - -2.10 Dependency Tracking: '--MD' -================================ - -'as' can generate a dependency file for the file it creates. This file -consists of a single rule suitable for 'make' describing the -dependencies of the main source file. - - The rule is written to the file named in its argument. - - This feature is used in the automatic updating of makefiles. - -2.11 Name the Object File: '-o' -=============================== - -There is always one object file output when you run 'as'. By default it -has the name 'a.out'. You use this option (which takes exactly one -filename) to give the object file a different name. - - Whatever the object file is called, 'as' overwrites any existing file -of the same name. - -2.12 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 do not 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 or ELF output, this option is only -useful if you use sections named '.text' and '.data'. - -2.13 Display Assembly Statistics: '--statistics' -================================================ - -Use '--statistics' to display two statistics about the resources used by -'as': the maximum amount of space allocated during the assembly (in -bytes), and the total execution time taken for the assembly (in CPU -seconds). - -2.14 Compatible Output: '--traditional-format' -============================================== - -For some targets, the output of 'as' is different in some ways from the -output of some existing assembler. This switch requests 'as' to use the -traditional format instead. - - For example, it disables the exception frame optimizations which 'as' -normally does by default on 'gcc' output. - -2.15 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. - -2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' -====================================================================== - -'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 the '-W' and '--no-warn' options, no warnings are issued. -This 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. - - If you use the '--fatal-warnings' option, 'as' considers files that -generate warnings to be in error. - - You can switch these options off again by specifying '--warn', which -causes warnings to be output as usual. - -2.17 Generate Object File in Spite of Errors: '-Z' -================================================== - -After an error message, 'as' normally produces no output. If for some -reason you are interested in object file output even after 'as' gives an -error message on your program, use the '-Z' option. If there are any -errors, 'as' continues anyways, and writes an object file after a final -warning message of the form 'N errors, M warnings, generating bad object -file.' - -3 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. - -3.1 Preprocessing -================= - -The 'as' internal preprocessor: - * 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. - - It does not do macro processing, include file handling, or anything -else you may get from your C compiler's preprocessor. You can do -include file processing with the '.include' directive (*note '.include': -Include.). You can use the GNU C compiler driver to get other "CPP" -style preprocessing by giving the input file a '.S' suffix. *Note -Options Controlling the Kind of Output: (gcc.info)Overall Options. - - Excess whitespace, comments, and character constants cannot be used -in the portions of the input text that are not preprocessed. - - If the first line of an input file is '#NO_APP' or if you use the -'-f' option, whitespace and comments are not removed from the input -file. Within an input file, you can ask for whitespace and comment -removal in specific portions of the by putting a line that says '#APP' -before the text that may contain whitespace or comments, and putting a -line that says '#NO_APP' after this text. This feature is mainly intend -to support 'asm' statements in compilers whose output is otherwise free -of comments and whitespace. - -3.2 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. - -3.3 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 ARM; '#' on the i386 and x86-64; '#' for Motorola PowerPC; '!' on -the SPARC; see *note Machine Dependencies::. - - To be compatible with past assemblers, lines that begin with '#' have -a special interpretation. Following the '#' should be an absolute -expression (*note Expressions::): the logical line number of the _next_ -line. Then a string (*note Strings: 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'. - -3.4 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 '_.$'. 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::. - -3.5 Statements -============== - -A "statement" ends at a newline character ('\n') or at a semicolon -(';'). The newline or semicolon is considered part of the preceding -statement. Newlines and semicolons within character constants are an -exception: they do not 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. - - 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 -assembles into a machine language instruction. - - 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, ... - -3.6 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. - -3.6.1 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. - -3.6.1.1 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. - -'\x HEX-DIGITS...' - A hex character code. All trailing hex digits are combined. - Either upper or lower case 'x' works. - -'\\' - 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 '\' gives a warning, but - assembles 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, do not use an escape sequence. - -3.6.1.2 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 (or semicolon ';') -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. - -3.6.2 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. - -3.6.2.1 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.). - -3.6.2.2 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. - -3.6.2.3 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. - - * 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'. - -4 Sections and Relocation -************************* - -4.1 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' -assigns the final addresses for the partial program, so that different -partial programs do not overlap. This is actually an -oversimplification, but it suffices 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. - - 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. - - 'as' can also generate whatever other named sections you specify -using the '.section' directive (*note '.section': Section.). If you do -not use any directives that place output in the '.text' or '.data' -sections, these sections still exist, but are 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 changes 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, most expressions 'as' computes have this section-relative -nature. - - 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 the linker never -arranges two partial programs' data sections with overlapping addresses -after linking, _by definition_ their absolute sections must overlap. -Address '{absolute 239}' in one part of a program is always the same -address when the program is running as address '{absolute 239}' in any -other part of the 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 is 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 programs' 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. - -4.2 Linker Sections -=================== - -'ld' deals with just four kinds of sections, summarized below. - -*named sections* - These sections hold your program. 'as' and 'ld' treat them as - separate but equal sections. Anything you can say of one section - is true of 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 contains 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 uninitialized 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 do not 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 ... - -4.3 Assembler Internal Sections -=============================== - -These sections are meant only for the internal use of 'as'. They have -no meaning at run-time. You do not 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. - -4.4 Sub-Sections -================ - -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 go into the object file together with other objects -in the same subsection. 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 do not use subsections, everything -goes in subsection number zero. - - 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 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. You can also use the '.subsection' -directive (*note SubSection::) to specify a subsection: '.subsection -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 changes it, and any label definition -captures its current value. The location counter of the section where -statements are being assembled is said to be the "active" location -counter. - -4.5 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. - - The '.lcomm' pseudo-op defines a symbol in the bss section; see *note -'.lcomm': Lcomm. - - The '.comm' pseudo-op may be used to declare a common symbol, which -is another form of uninitialized symbol; see *note '.comm': Comm. - -5 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. - -5.1 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. - -5.2 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. -In the same way, using a double equals sign '=''=' here represents an -equivalent of the '.eqv' directive. *Note '.eqv': Eqv. - -5.3 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 for a particular -target machine), and underscores. - - 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 ------------------- - -A local symbol is any symbol beginning with certain local label -prefixes. By default, the local label prefix is '.L' for ELF systems or -'L' for traditional a.out systems, but each target may have its own set -of local label prefixes. - - Local symbols are defined and used within the assembler, but they are -normally not saved in object files. Thus, they are not visible when -debugging. You may use the '-L' option (*note Include Local Symbols: -'-L': L.) to retain the local symbols in the object files. - -Local Labels ------------- - -Local labels help compilers and programmers use names temporarily. They -create symbols which are guaranteed to be unique over the entire scope -of the input source code and which can be referred to by a simple -notation. To define a local label, write a label of the form 'N:' -(where N represents any positive integer). To refer to the most recent -previous definition of that label write 'Nb', using the same number as -when you defined the label. To refer to the next definition of a local -label, write 'Nf'--the 'b' stands for "backwards" and the 'f' stands for -"forwards". - - There is no restriction on how you can use these labels, and you can -reuse them too. So that it is possible to repeatedly define the same -local label (using the same number 'N'), although you can only refer to -the most recently defined local label of that number (for a backwards -reference) or the next definition of a specific local label for a -forward reference. It is also worth noting that the first 10 local -labels ('0:'...'9:') are implemented in a slightly more efficient manner -than the others. - - Here is an example: - - 1: branch 1f - 2: branch 1b - 1: branch 2f - 2: branch 1b - - Which is the equivalent of: - - label_1: branch label_3 - label_2: branch label_1 - label_3: branch label_4 - label_4: branch label_3 - - Local label names are only a notational device. They are immediately -transformed into more conventional symbol names before the assembler -uses them. The symbol names are stored in the symbol table, appear in -error messages, and are optionally emitted to the object file. The -names are constructed using these parts: - -'_local label prefix_' - All local symbols begin with the system-specific local label - prefix. Normally both 'as' and 'ld' forget symbols that start with - the local label prefix. These labels are used for symbols you are - never intended to see. If you use the '-L' option then 'as' - retains these symbols in the object file. If you also instruct - 'ld' to retain these symbols, you may use them in debugging. - -'NUMBER' - This is the number that was used in the local label definition. So - if the label is written '55:' then the number is '55'. - -'C-B' - This unusual character is included so you do not accidentally - invent a symbol of the same name. The character has ASCII value of - '\002' (control-B). - -'_ordinal number_' - This is a serial number to keep the labels distinct. The first - definition of '0:' gets the number '1'. The 15th definition of - '0:' gets the number '15', and so on. Likewise the first - definition of '1:' gets the number '1' and its 15th definition gets - '15' as well. - - So for example, the first '1:' may be named '.L1C-B1', and the 44th -'3:' may be named '.L3C-B44'. - -Dollar Local Labels -------------------- - -'as' also supports an even more local form of local labels called dollar -labels. These labels go out of scope (i.e., they become undefined) as -soon as a non-local label is defined. Thus they remain valid for only a -small region of the input source code. Normal local labels, by -contrast, remain in scope for the entire file, or until they are -redefined by another occurrence of the same local label. - - Dollar labels are defined in exactly the same way as ordinary local -labels, except that instead of being terminated by a colon, they are -terminated by a dollar sign, e.g., '55$'. - - They can also be distinguished from ordinary local labels by their -transformed names which use ASCII character '\001' (control-A) as the -magic character to distinguish them from ordinary labels. For example, -the fifth definition of '6$' may be named '.L6'C-A'5'. - -5.4 The Special Dot Symbol -========================== - -The special symbol '.' refers to the current address that 'as' is -assembling into. Thus, the expression 'melvin: .long .' defines -'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'. - -5.5 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. The detailed definitions are in 'a.out.h'. - - 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. - -5.5.1 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 file, and -'ld' tries to determine its value from other files linked into the same -program. 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. - -5.5.2 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. - -6 Expressions -************* - -An "expression" specifies an address or numeric value. Whitespace may -precede and/or follow an expression. - - The result of an expression must be an absolute number, or else an -offset into a particular section. If an expression is not absolute, and -there is not enough information when 'as' sees the expression to know -its section, a second pass over the source program might be necessary to -interpret the expression--but the second pass is currently not -implemented. 'as' aborts with an error message in this situation. - -6.1 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' assumes a value of (absolute) 0. This is -compatible with other assemblers. - -6.2 Integer Expressions -======================= - -An "integer expression" is one or more _arguments_ delimited by -_operators_. - -6.2.1 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. - -6.2.2 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. - -6.2.3 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. - -6.2.4 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. Low Precedence - - '+' - "Addition". If either argument is absolute, the result has - the section of the other argument. You may not add together - arguments from different sections. - - '-' - "Subtraction". If the right argument is absolute, the result - has the section of the left argument. If both arguments are - in the same section, the result is absolute. You may not - subtract arguments from different sections. - - '==' - "Is Equal To" - '<>' - '!=' - "Is Not Equal To" - '<' - "Is Less Than" - '>' - "Is Greater Than" - '>=' - "Is Greater Than Or Equal To" - '<=' - "Is Less Than Or Equal To" - - The comparison operators can be used as infix operators. A - true results has a value of -1 whereas a false result has a - value of 0. Note, these operators perform signed comparisons. - - 4. Lowest Precedence - - '&&' - "Logical And". - - '||' - "Logical Or". - - These two logical operations can be used to combine the - results of sub expressions. Note, unlike the comparison - operators a true result returns a value of 1 but a false - results does still return 0. Also note that the logical or - operator has a slightly lower precedence than logical and. - - In short, it's only meaningful to add or subtract the _offsets_ in an -address; you can only have a defined section in one of the two -arguments. - -7 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. - -7.1 '.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. - -7.2 '.align ABS-EXPR, 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 -alignment required, as described below. - - The second expression (also absolute) gives the fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The way the required alignment is specified varies from system to -system. For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, -s390, sparc, tic4x, tic80 and xtensa, the first expression is the -alignment request in bytes. For example '.align 8' advances the -location counter until it is a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. For the tic54x, the -first expression is the alignment request in words. - - For other systems, including the i386 using a.out format, and the arm -and strongarm, it is the number of low-order zero bits the location -counter must have after advancement. For example '.align 3' advances -the location counter until it a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. - - This inconsistency is due to the different behaviors of the various -native assemblers for these systems which GAS must emulate. GAS also -provides '.balign' and '.p2align' directives, described later, which -have a consistent behavior across all architectures (but are specific to -GAS). - -7.3 '.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. - -7.4 '.asciz "STRING"'... -======================== - -'.asciz' is just like '.ascii', but each string is followed by a zero -byte. The "z" in '.asciz' stands for "zero". - -7.5 '.balign[wl] ABS-EXPR, 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 -alignment request in bytes. For example '.balign 8' advances the -location counter until it is 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 fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The '.balignw' and '.balignl' directives are variants of the -'.balign' directive. The '.balignw' directive treats the fill pattern -as a two byte word value. The '.balignl' directives treats the fill -pattern as a four byte longword value. For example, '.balignw 4,0x368d' -will align to a multiple of 4. If it skips two bytes, they will be -filled in with the value 0x368d (the exact placement of the bytes -depends upon the endianness of the processor). If it skips 1 or 3 -bytes, the fill value is undefined. - -7.6 '.byte EXPRESSIONS' -======================= - -'.byte' expects zero or more expressions, separated by commas. Each -expression is assembled into the next byte. - -7.7 '.comm SYMBOL , LENGTH ' -============================ - -'.comm' declares a common symbol named SYMBOL. When linking, a common -symbol in one object file may be merged with a defined or common symbol -of the same name in another object file. If 'ld' does not see a -definition for the symbol-just one or more common symbols-then it will -allocate LENGTH bytes of uninitialized memory. LENGTH must be an -absolute expression. If 'ld' sees multiple common symbols with the same -name, and they do not all have the same size, it will allocate space -using the largest size. - - When using ELF, the '.comm' directive takes an optional third -argument. This is the desired alignment of the symbol, specified as a -byte boundary (for example, an alignment of 16 means that the least -significant 4 bits of the address should be zero). The alignment must -be an absolute expression, and it must be a power of two. If 'ld' -allocates uninitialized memory for the common symbol, it will use the -alignment when placing the symbol. If no alignment is specified, 'as' -will set the alignment to the largest power of two less than or equal to -the size of the symbol, up to a maximum of 16. - -7.8 '.cfi_startproc [simple]' -============================= - -'.cfi_startproc' is used at the beginning of each function that should -have an entry in '.eh_frame'. It initializes some internal data -structures. Don't forget to close the function by '.cfi_endproc'. - - Unless '.cfi_startproc' is used along with parameter 'simple' it also -emits some architecture dependent initial CFI instructions. - -7.9 '.cfi_endproc' -================== - -'.cfi_endproc' is used at the end of a function where it closes its -unwind entry previously opened by '.cfi_startproc', and emits it to -'.eh_frame'. - -7.10 '.cfi_personality ENCODING [, EXP]' -======================================== - -'.cfi_personality' defines personality routine and its encoding. -ENCODING must be a constant determining how the personality should be -encoded. If it is 255 ('DW_EH_PE_omit'), second argument is not -present, otherwise second argument should be a constant or a symbol -name. When using indirect encodings, the symbol provided should be the -location where personality can be loaded from, not the personality -routine itself. The default after '.cfi_startproc' is '.cfi_personality -0xff', no personality routine. - -7.11 '.cfi_lsda ENCODING [, EXP]' -================================= - -'.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant -determining how the LSDA should be encoded. If it is 255 -('DW_EH_PE_omit'), second argument is not present, otherwise second -argument should be a constant or a symbol name. The default after -'.cfi_startproc' is '.cfi_lsda 0xff', no LSDA. - -7.12 '.cfi_def_cfa REGISTER, OFFSET' -==================================== - -'.cfi_def_cfa' defines a rule for computing CFA as: take address from -REGISTER and add OFFSET to it. - -7.13 '.cfi_def_cfa_register REGISTER' -===================================== - -'.cfi_def_cfa_register' modifies a rule for computing CFA. From now on -REGISTER will be used instead of the old one. Offset remains the same. - -7.14 '.cfi_def_cfa_offset OFFSET' -================================= - -'.cfi_def_cfa_offset' modifies a rule for computing CFA. Register -remains the same, but OFFSET is new. Note that it is the absolute -offset that will be added to a defined register to compute CFA address. - -7.15 '.cfi_adjust_cfa_offset OFFSET' -==================================== - -Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is -added/substracted from the previous offset. - -7.16 '.cfi_offset REGISTER, OFFSET' -=================================== - -Previous value of REGISTER is saved at offset OFFSET from CFA. - -7.17 '.cfi_rel_offset REGISTER, OFFSET' -======================================= - -Previous value of REGISTER is saved at offset OFFSET from the current -CFA register. This is transformed to '.cfi_offset' using the known -displacement of the CFA register from the CFA. This is often easier to -use, because the number will match the code it's annotating. - -7.18 '.cfi_register REGISTER1, REGISTER2' -========================================= - -Previous value of REGISTER1 is saved in register REGISTER2. - -7.19 '.cfi_restore REGISTER' -============================ - -'.cfi_restore' says that the rule for REGISTER is now the same as it was -at the beginning of the function, after all initial instruction added by -'.cfi_startproc' were executed. - -7.20 '.cfi_undefined REGISTER' -============================== - -From now on the previous value of REGISTER can't be restored anymore. - -7.21 '.cfi_same_value REGISTER' -=============================== - -Current value of REGISTER is the same like in the previous frame, i.e. -no restoration needed. - -7.22 '.cfi_remember_state', -=========================== - -First save all current rules for all registers by '.cfi_remember_state', -then totally screw them up by subsequent '.cfi_*' directives and when -everything is hopelessly bad, use '.cfi_restore_state' to restore the -previous saved state. - -7.23 '.cfi_return_column REGISTER' -================================== - -Change return column REGISTER, i.e. the return address is either -directly in REGISTER or can be accessed by rules for REGISTER. - -7.24 '.cfi_signal_frame' -======================== - -Mark current function as signal trampoline. - -7.25 '.cfi_window_save' -======================= - -SPARC register window has been saved. - -7.26 '.cfi_escape' EXPRESSION[, ...] -==================================== - -Allows the user to add arbitrary bytes to the unwind info. One might -use this to add OS-specific CFI opcodes, or generic CFI opcodes that GAS -does not yet support. - -7.27 '.file FILENO FILENAME' -============================ - -When emitting dwarf2 line number information '.file' assigns filenames -to the '.debug_line' file name table. The FILENO operand should be a -unique positive integer to use as the index of the entry in the table. -The FILENAME operand is a C string literal. - - The detail of filename indices is exposed to the user because the -filename table is shared with the '.debug_info' section of the dwarf2 -debugging information, and thus the user must know the exact indices -that table entries will have. - -7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' -============================================ - -The '.loc' directive will add row to the '.debug_line' line number -matrix corresponding to the immediately following assembly instruction. -The FILENO, LINENO, and optional COLUMN arguments will be applied to the -'.debug_line' state machine before the row is added. - - The OPTIONS are a sequence of the following tokens in any order: - -'basic_block' - This option will set the 'basic_block' register in the - '.debug_line' state machine to 'true'. - -'prologue_end' - This option will set the 'prologue_end' register in the - '.debug_line' state machine to 'true'. - -'epilogue_begin' - This option will set the 'epilogue_begin' register in the - '.debug_line' state machine to 'true'. - -'is_stmt VALUE' - This option will set the 'is_stmt' register in the '.debug_line' - state machine to 'value', which must be either 0 or 1. - -'isa VALUE' - This directive will set the 'isa' register in the '.debug_line' - state machine to VALUE, which must be an unsigned integer. - -7.29 '.loc_mark_blocks ENABLE' -============================== - -The '.loc_mark_blocks' directive makes the assembler emit an entry to -the '.debug_line' line number matrix with the 'basic_block' register in -the state machine set whenever a code label is seen. The ENABLE -argument should be either 1 or 0, to enable or disable this function -respectively. - -7.30 '.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. - -7.31 '.double FLONUMS' -====================== - -'.double' expects zero or more flonums, separated by commas. It -assembles floating point numbers. - -7.32 '.eject' -============= - -Force a page break at this point, when generating assembly listings. - -7.33 '.else' -============ - -'.else' is part of the 'as' support for conditional assembly; see *note -'.if': If. It marks the beginning of a section of code to be assembled -if the condition for the preceding '.if' was false. - -7.34 '.elseif' -============== - -'.elseif' is part of the 'as' support for conditional assembly; see -*note '.if': If. It is shorthand for beginning a new '.if' block that -would otherwise fill the entire '.else' section. - -7.35 '.end' -=========== - -'.end' marks the end of the assembly file. 'as' does not process -anything in the file past the '.end' directive. - -7.36 '.endfunc' -=============== - -'.endfunc' marks the end of a function specified with '.func'. - -7.37 '.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. - -7.38 '.equ SYMBOL, EXPRESSION' -============================== - -This directive sets the value of SYMBOL to EXPRESSION. It is synonymous -with '.set'; see *note '.set': Set. - -7.39 '.equiv SYMBOL, EXPRESSION' -================================ - -The '.equiv' directive is like '.equ' and '.set', except that the -assembler will signal an error if SYMBOL is already defined. Note a -symbol which has been referenced but not actually defined is considered -to be undefined. - - Except for the contents of the error message, this is roughly -equivalent to - .ifdef SYM - .err - .endif - .equ SYM,VAL - plus it protects the symbol from later redefinition. - -7.40 '.eqv SYMBOL, EXPRESSION' -============================== - -The '.eqv' directive is like '.equiv', but no attempt is made to -evaluate the expression or any part of it immediately. Instead each -time the resulting symbol is used in an expression, a snapshot of its -current value is taken. - -7.41 '.err' -=========== - -If 'as' assembles a '.err' directive, it will print an error message -and, unless the '-Z' option was used, it will not generate an object -file. This can be used to signal an error in conditionally compiled -code. - -7.42 '.error "STRING"' -====================== - -Similarly to '.err', this directive emits an error, but you can specify -a string that will be emitted as the error message. If you don't -specify the message, it defaults to '".error directive invoked in source -file"'. *Note Error and Warning Messages: Errors. - - .error "This code has not been assembled and tested." - -7.43 '.exitm' -============= - -Exit early from the current macro definition. *Note Macro::. - -7.44 '.extern' -============== - -'.extern' is accepted in the source program--for compatibility with -other assemblers--but it is ignored. 'as' treats all undefined symbols -as external. - -7.45 '.fail EXPRESSION' -======================= - -Generates an error or a warning. If the value of the EXPRESSION is 500 -or more, 'as' will print a warning message. If the value is less than -500, 'as' will print an error message. The message will include the -value of EXPRESSION. This can occasionally be useful inside complex -nested macros or conditional assembly. - -7.46 '.file STRING' -=================== - -'.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. - -7.47 '.fill REPEAT , SIZE , VALUE' -================================== - -REPEAT, 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. - -7.48 '.float FLONUMS' -===================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.single'. - -7.49 '.func NAME[,LABEL]' -========================= - -'.func' emits debugging information to denote function NAME, and is -ignored unless the file is assembled with debugging enabled. Only -'--gstabs[+]' is currently supported. LABEL is the entry point of the -function and if omitted NAME prepended with the 'leading char' is used. -'leading char' is usually '_' or nothing, depending on the target. All -functions are currently defined to have 'void' return type. The -function must be terminated with '.endfunc'. - -7.50 '.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 takes its -attributes from a symbol of the same name from another file linked into -the same program. - - Both spellings ('.globl' and '.global') are accepted, for -compatibility with other assemblers. - -7.51 '.hidden NAMES' -==================== - -This is one of the ELF visibility directives. The other two are -'.internal' (*note '.internal': Internal.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'hidden' which means that the symbols are not visible to -other components. Such symbols are always considered to be 'protected' -as well. - -7.52 '.hword EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - - This directive is a synonym for '.short'. - -7.53 '.ident' -============= - -This directive is used by some assemblers to place tags in object files. -The behavior of this directive varies depending on the target. When -using the a.out object file format, 'as' simply accepts the directive -for source-file compatibility with existing assemblers, but does not -emit anything for it. When using COFF, comments are emitted to the -'.comment' or '.rdata' section, depending on the target. When using -ELF, comments are emitted to the '.comment' section. - -7.54 '.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.). If you have several conditions to -check, '.elseif' may be used to avoid nesting blocks if/else within each -subsequent '.else' block. - - The following variants of '.if' are also supported: -'.ifdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - been defined. Note a symbol which has been referenced but not yet - defined is considered to be undefined. - -'.ifb TEXT' - Assembles the following section of code if the operand is blank - (empty). - -'.ifc STRING1,STRING2' - Assembles the following section of code if the two strings are the - same. The strings may be optionally quoted with single quotes. If - they are not quoted, the first string stops at the first comma, and - the second string stops at the end of the line. Strings which - contain whitespace should be quoted. The string comparison is case - sensitive. - -'.ifeq ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is zero. - -'.ifeqs STRING1,STRING2' - Another form of '.ifc'. The strings must be quoted using double - quotes. - -'.ifge ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than or equal to zero. - -'.ifgt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than zero. - -'.ifle ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than or equal to zero. - -'.iflt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than zero. - -'.ifnb TEXT' - Like '.ifb', but the sense of the test is reversed: this assembles - the following section of code if the operand is non-blank - (non-empty). - -'.ifnc STRING1,STRING2.' - Like '.ifc', but the sense of the test is reversed: this assembles - the following section of code if the two strings are not the same. - -'.ifndef SYMBOL' -'.ifnotdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - not been defined. Both spelling variants are equivalent. Note a - symbol which has been referenced but not yet defined is considered - to be undefined. - -'.ifne ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is not - equal to zero (in other words, this is equivalent to '.if'). - -'.ifnes STRING1,STRING2' - Like '.ifeqs', but the sense of the test is reversed: this - assembles the following section of code if the two strings are not - the same. - -7.55 '.incbin "FILE"[,SKIP[,COUNT]]' -==================================== - -The 'incbin' directive includes FILE verbatim at the current location. -You can control the search paths used with the '-I' command-line option -(*note Command-Line Options: Invoking.). Quotation marks are required -around FILE. - - The SKIP argument skips a number of bytes from the start of the FILE. -The COUNT argument indicates the maximum number of bytes to read. Note -that the data is not aligned in any way, so it is the user's -responsibility to make sure that proper alignment is provided both -before and after the 'incbin' directive. - -7.56 '.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. - -7.57 '.int EXPRESSIONS' -======================= - -Expect zero or more EXPRESSIONS, of any section, separated by commas. -For each expression, emit a number that, at run time, is the value of -that expression. The byte order and bit size of the number depends on -what kind of target the assembly is for. - -7.58 '.internal NAMES' -====================== - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note '.hidden': Hidden.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'internal' which means that the symbols are considered to -be 'hidden' (i.e., not visible to other components), and that some -extra, processor specific processing must also be performed upon the -symbols as well. - -7.59 '.irp SYMBOL,VALUES'... -============================ - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irp' directive, and is -terminated by an '.endr' directive. For each VALUE, SYMBOL is set to -VALUE, and the sequence of statements is assembled. If no VALUE is -listed, the sequence of statements is assembled once, with SYMBOL set to -the null string. To refer to SYMBOL within the sequence of statements, -use \SYMBOL. - - For example, assembling - - .irp param,1,2,3 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also *note Macro::. - -7.60 '.irpc SYMBOL,VALUES'... -============================= - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irpc' directive, and is -terminated by an '.endr' directive. For each character in VALUE, SYMBOL -is set to the character, and the sequence of statements is assembled. -If no VALUE is listed, the sequence of statements is assembled once, -with SYMBOL set to the null string. To refer to SYMBOL within the -sequence of statements, use \SYMBOL. - - For example, assembling - - .irpc param,123 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also the discussion -at *Note Macro::. - -7.61 '.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 that at -run-time the bytes start off zeroed. SYMBOL is not declared global -(*note '.global': Global.), so is normally not visible to 'ld'. - -7.62 '.lflags' -============== - -'as' accepts this directive, for compatibility with other assemblers, -but ignores it. - -7.63 '.line LINE-NUMBER' -======================== - -Even though this is a directive associated with the 'a.out' or 'b.out' -object-code formats, 'as' still recognizes it when producing COFF -output, and treats '.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. - -7.64 '.linkonce [TYPE]' -======================= - -Mark the current section so that the linker only includes a single copy -of it. This may be used to include the same section in several -different object files, but ensure that the linker will only include it -once in the final output file. The '.linkonce' pseudo-op must be used -for each instance of the section. Duplicate sections are detected based -on the section name, so it should be unique. - - This directive is only supported by a few object file formats; as of -this writing, the only object file format which supports it is the -Portable Executable format used on Windows NT. - - The TYPE argument is optional. If specified, it must be one of the -following strings. For example: - .linkonce same_size - Not all types may be supported on all object file formats. - -'discard' - Silently discard duplicate sections. This is the default. - -'one_only' - Warn if there are duplicate sections, but still keep only one copy. - -'same_size' - Warn if any of the duplicates have different sizes. - -'same_contents' - Warn if any of the duplicates do not have exactly the same - contents. - -7.65 '.ln LINE-NUMBER' -====================== - -'.ln' is a synonym for '.line'. - -7.66 '.mri VAL' -=============== - -If VAL is non-zero, this tells 'as' to enter MRI mode. If VAL is zero, -this tells 'as' to exit MRI mode. This change affects code assembled -until the next '.mri' directive, or until the end of the file. *Note -MRI mode: M. - -7.67 '.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. - -7.68 '.long EXPRESSIONS' -======================== - -'.long' is the same as '.int'. *Note '.int': Int. - -7.69 '.macro' -============= - -The commands '.macro' and '.endm' allow you to define macros that -generate assembly output. For example, this definition specifies a -macro 'sum' that puts a sequence of numbers into memory: - - .macro sum from=0, to=5 - .long \from - .if \to-\from - sum "(\from+1)",\to - .endif - .endm - -With that definition, 'SUM 0,5' is equivalent to this assembly input: - - .long 0 - .long 1 - .long 2 - .long 3 - .long 4 - .long 5 - -'.macro MACNAME' -'.macro MACNAME MACARGS ...' - Begin the definition of a macro called MACNAME. If your macro - definition requires arguments, specify their names after the macro - name, separated by commas or spaces. You can qualify the macro - argument to indicate whether all invocations must specify a - non-blank value (through ':'req''), or whether it takes all of the - remaining arguments (through ':'vararg''). You can supply a - default value for any macro argument by following the name with - '=DEFLT'. You cannot define two macros with the same MACNAME - unless it has been subject to the '.purgem' directive (*note - Purgem::) between the two definitions. For example, these are all - valid '.macro' statements: - - '.macro comm' - Begin the definition of a macro called 'comm', which takes no - arguments. - - '.macro plus1 p, p1' - '.macro plus1 p p1' - Either statement begins the definition of a macro called - 'plus1', which takes two arguments; within the macro - definition, write '\p' or '\p1' to evaluate the arguments. - - '.macro reserve_str p1=0 p2' - Begin the definition of a macro called 'reserve_str', with two - arguments. The first argument has a default value, but not - the second. After the definition is complete, you can call - the macro either as 'reserve_str A,B' (with '\p1' evaluating - to A and '\p2' evaluating to B), or as 'reserve_str ,B' (with - '\p1' evaluating as the default, in this case '0', and '\p2' - evaluating to B). - - '.macro m p1:req, p2=0, p3:vararg' - Begin the definition of a macro called 'm', with at least - three arguments. The first argument must always have a value - specified, but not the second, which instead has a default - value. The third formal will get assigned all remaining - arguments specified at invocation time. - - When you call a macro, you can specify the argument values - either by position, or by keyword. For example, 'sum 9,17' is - equivalent to 'sum to=17, from=9'. - - Note that since each of the MACARGS can be an identifier exactly as - any other one permitted by the target architecture, there may be - occasional problems if the target hand-crafts special meanings to - certain characters when they occur in a special position. For - example, if the colon (':') is generally permitted to be part of a - symbol name, but the architecture specific code special-cases it - when occurring as the final character of a symbol (to denote a - label), then the macro parameter replacement code will have no way - of knowing that and consider the whole construct (including the - colon) an identifier, and check only this identifier for being the - subject to parameter substitution. So for example this macro - definition: - - .macro label l - \l: - .endm - - might not work as expected. Invoking 'label foo' might not create - a label called 'foo' but instead just insert the text '\l:' into - the assembler source, probably generating an error about an - unrecognised identifier. - - Similarly problems might occur with the period character ('.') - which is often allowed inside opcode names (and hence identifier - names). So for example constructing a macro to build an opcode - from a base name and a length specifier like this: - - .macro opcode base length - \base.\length - .endm - - and invoking it as 'opcode store l' will not create a 'store.l' - instruction but instead generate some kind of error as the - assembler tries to interpret the text '\base.\length'. - - There are several possible ways around this problem: - - 'Insert white space' - If it is possible to use white space characters then this is - the simplest solution. eg: - - .macro label l - \l : - .endm - - 'Use '\()'' - The string '\()' can be used to separate the end of a macro - argument from the following text. eg: - - .macro opcode base length - \base\().\length - .endm - - 'Use the alternate macro syntax mode' - In the alternative macro syntax mode the ampersand character - ('&') can be used as a separator. eg: - - .altmacro - .macro label l - l&: - .endm - - Note: this problem of correctly identifying string parameters to - pseudo ops also applies to the identifiers used in '.irp' (*note - Irp::) and '.irpc' (*note Irpc::) as well. - -'.endm' - Mark the end of a macro definition. - -'.exitm' - Exit early from the current macro definition. - -'\@' - 'as' maintains a counter of how many macros it has executed in this - pseudo-variable; you can copy that number to your output with '\@', - but _only within a macro definition_. - -'LOCAL NAME [ , ... ]' - _Warning: 'LOCAL' is only available if you select "alternate macro - syntax" with '--alternate' or '.altmacro'._ *Note '.altmacro': - Altmacro. - -7.70 '.altmacro' -================ - -Enable alternate macro mode, enabling: - -'LOCAL NAME [ , ... ]' - One additional directive, 'LOCAL', is available. It is used to - generate a string replacement for each of the NAME arguments, and - replace any instances of NAME in each macro expansion. The - replacement string is unique in the assembly, and different for - each separate macro expansion. 'LOCAL' allows you to write macros - that define symbols, without fear of conflict between separate - macro expansions. - -'String delimiters' - You can write strings delimited in these other ways besides - '"STRING"': - - ''STRING'' - You can delimit strings with single-quote characters. - - '<STRING>' - You can delimit strings with matching angle brackets. - -'single-character string escape' - To include any single character literally in a string (even if the - character would otherwise have some special meaning), you can - prefix the character with '!' (an exclamation mark). For example, - you can write '<4.3 !> 5.4!!>' to get the literal text '4.3 > - 5.4!'. - -'Expression results as strings' - You can write '%EXPR' to evaluate the expression EXPR and use the - result as a string. - -7.71 '.noaltmacro' -================== - -Disable alternate macro mode. *Note Altmacro::. - -7.72 '.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. - -7.73 '.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. - -7.74 '.org NEW-LC , FILL' -========================= - -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' issues a warning, then pretends 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. - -7.75 '.p2align[wl] ABS-EXPR, 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 must have after -advancement. For example '.p2align 3' advances 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 fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The '.p2alignw' and '.p2alignl' directives are variants of the -'.p2align' directive. The '.p2alignw' directive treats the fill pattern -as a two byte word value. The '.p2alignl' directives treats the fill -pattern as a four byte longword value. For example, '.p2alignw -2,0x368d' will align to a multiple of 4. If it skips two bytes, they -will be filled in with the value 0x368d (the exact placement of the -bytes depends upon the endianness of the processor). If it skips 1 or 3 -bytes, the fill value is undefined. - -7.76 '.previous' -================ - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.popsection' -(*note PopSection::). - - This directive swaps the current section (and subsection) with most -recently referenced section (and subsection) prior to this one. -Multiple '.previous' directives in a row will flip between two sections -(and their subsections). - - In terms of the section stack, this directive swaps the current -section with the top section on the section stack. - -7.77 '.popsection' -================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.previous' -(*note Previous::). - - This directive replaces the current section (and subsection) with the -top section (and subsection) on the section stack. This section is -popped off the stack. - -7.78 '.print STRING' -==================== - -'as' will print STRING on the standard output during assembly. You must -put STRING in double quotes. - -7.79 '.protected NAMES' -======================= - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note Hidden::) and '.internal' (*note Internal::). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'protected' which means that any references to the symbols -from within the components that defines them must be resolved to the -definition in that component, even if a definition in another component -would normally preempt this. - -7.80 '.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 do not use '.psize', listings use a default line-count of 60. -You may omit the comma and COLUMNS specification; the default width is -200 columns. - - 'as' generates 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'. - -7.81 '.purgem NAME' -=================== - -Undefine the macro NAME, so that later uses of the string will not be -expanded. *Note Macro::. - -7.82 '.pushsection NAME , SUBSECTION' -===================================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive pushes the current section (and subsection) onto the -top of the section stack, and then replaces the current section and -subsection with 'name' and 'subsection'. - -7.83 '.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. - -7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' -============================================== - -Generate a relocation at OFFSET of type RELOC_NAME with value -EXPRESSION. If OFFSET is a number, the relocation is generated in the -current section. If OFFSET is an expression that resolves to a symbol -plus offset, the relocation is generated in the given symbol's section. -EXPRESSION, if present, must resolve to a symbol plus addend or to an -absolute value, but note that not all targets support an addend. e.g. -ELF REL targets such as i386 store an addend in the section contents -rather than in the relocation. This low level interface does not -support addends stored in the section. - -7.85 '.rept COUNT' -================== - -Repeat the sequence of lines between the '.rept' directive and the next -'.endr' directive COUNT times. - - For example, assembling - - .rept 3 - .long 0 - .endr - - is equivalent to assembling - - .long 0 - .long 0 - .long 0 - -7.86 '.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. - -7.87 '.section NAME' -==================== - -Use the '.section' directive to assemble the following code into a -section named NAME. - - This directive is only supported for targets that actually support -arbitrarily named sections; on 'a.out' targets, for example, it is not -accepted, even with a standard 'a.out' section name. - - This is one of the ELF section stack manipulation directives. The -others are '.subsection' (*note SubSection::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - For ELF targets, the '.section' directive is used like this: - - .section NAME [, "FLAGS"[, @TYPE[,FLAG_SPECIFIC_ARGUMENTS]]] - - The optional FLAGS argument is a quoted string which may contain any -combination of the following characters: -'a' - section is allocatable -'w' - section is writable -'x' - section is executable -'M' - section is mergeable -'S' - section contains zero terminated strings -'G' - section is a member of a section group -'T' - section is used for thread-local-storage - - The optional TYPE argument may contain one of the following -constants: -'@progbits' - section contains data -'@nobits' - section does not contain data (i.e., section only occupies space) -'@note' - section contains data which is used by things other than the - program -'@init_array' - section contains an array of pointers to init functions -'@fini_array' - section contains an array of pointers to finish functions -'@preinit_array' - section contains an array of pointers to pre-init functions - - Many targets only support the first three section types. - - Note on targets where the '@' character is the start of a comment (eg -ARM) then another character is used instead. For example the ARM port -uses the '%' character. - - If FLAGS contains the 'M' symbol then the TYPE argument must be -specified as well as an extra argument--ENTSIZE--like this: - - .section NAME , "FLAGS"M, @TYPE, ENTSIZE - - Sections with the 'M' flag but not 'S' flag must contain fixed size -constants, each ENTSIZE octets long. Sections with both 'M' and 'S' -must contain zero terminated strings where each character is ENTSIZE -bytes long. The linker may remove duplicates within sections with the -same name, same entity size and same flags. ENTSIZE must be an absolute -expression. - - If FLAGS contains the 'G' symbol then the TYPE argument must be -present along with an additional field like this: - - .section NAME , "FLAGS"G, @TYPE, GROUPNAME[, LINKAGE] - - The GROUPNAME field specifies the name of the section group to which -this particular section belongs. The optional linkage field can -contain: -'comdat' - indicates that only one copy of this section should be retained -'.gnu.linkonce' - an alias for comdat - - Note: if both the M and G flags are present then the fields for the -Merge flag should come first, like this: - - .section NAME , "FLAGS"MG, @TYPE, ENTSIZE, GROUPNAME[, LINKAGE] - - If no flags are specified, the default flags depend upon the section -name. If the section name is not recognized, the default will be for -the section to have none of the above flags: it will not be allocated in -memory, nor writable, nor executable. The section will contain data. - - For ELF targets, the assembler supports another type of '.section' -directive for compatibility with the Solaris assembler: - - .section "NAME"[, FLAGS...] - - Note that the section name is quoted. There may be a sequence of -comma separated flags: -'#alloc' - section is allocatable -'#write' - section is writable -'#execinstr' - section is executable -'#tls' - section is used for thread local storage - - This directive replaces the current section and subsection. See the -contents of the gas testsuite directory 'gas/testsuite/gas/elf' for some -examples of how this directive and the other section stack directives -work. - -7.88 '.set SYMBOL, EXPRESSION' -============================== - -Set the value of SYMBOL to EXPRESSION. This changes 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 you '.set' a global symbol, the value stored in the object file is -the last value stored into it. - -7.89 '.short EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - -7.90 '.single FLONUMS' -====================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.float'. - -7.91 '.size' -============ - -This directive is used to set the size associated with a symbol. - - For ELF targets, the '.size' directive is used like this: - - .size NAME , EXPRESSION - - This directive sets the size associated with a symbol NAME. The size -in bytes is computed from EXPRESSION which can make use of label -arithmetic. This directive is typically used to set the size of -function symbols. - -7.92 '.sleb128 EXPRESSIONS' -=========================== - -SLEB128 stands for "signed little endian base 128." This is a compact, -variable length representation of numbers used by the DWARF symbolic -debugging format. *Note '.uleb128': Uleb128. - -7.93 '.skip 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. This is the same as '.space'. - -7.94 '.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. This is the same as '.skip'. - -7.95 '.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 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; you -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 is the - address of the location counter 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. - -7.96 '.string' "STR" -==================== - -Copy the characters in STR to the object file. You may specify more -than one string to copy, separated by commas. Unless otherwise -specified for a particular machine, the assembler marks the end of each -string with a 0 byte. You can use any of the escape sequences described -in *note Strings: Strings. - -7.97 '.struct EXPRESSION' -========================= - -Switch to the absolute section, and set the section offset to -EXPRESSION, which must be an absolute expression. You might use this as -follows: - .struct 0 - field1: - .struct field1 + 4 - field2: - .struct field2 + 4 - field3: - This would define the symbol 'field1' to have the value 0, the symbol -'field2' to have the value 4, and the symbol 'field3' to have the value -8. Assembly would be left in the absolute section, and you would need -to use a '.section' directive of some sort to change to some other -section before further assembly. - -7.98 '.subsection NAME' -======================= - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive replaces the current subsection with 'name'. The -current section is not changed. The replaced subsection is put onto the -section stack in place of the then current top of stack subsection. - -7.99 '.symver' -============== - -Use the '.symver' directive to bind symbols to specific version nodes -within a source file. This is only supported on ELF platforms, and is -typically used when assembling files to be linked into a shared library. -There are cases where it may make sense to use this in objects to be -bound into an application itself so as to override a versioned symbol -from a shared library. - - For ELF targets, the '.symver' directive can be used like this: - .symver NAME, NAME2@NODENAME - If the symbol NAME is defined within the file being assembled, the -'.symver' directive effectively creates a symbol alias with the name -NAME2@NODENAME, and in fact the main reason that we just don't try and -create a regular alias is that the @ character isn't permitted in symbol -names. The NAME2 part of the name is the actual name of the symbol by -which it will be externally referenced. The name NAME itself is merely -a name of convenience that is used so that it is possible to have -definitions for multiple versions of a function within a single source -file, and so that the compiler can unambiguously know which version of a -function is being mentioned. The NODENAME portion of the alias should -be the name of a node specified in the version script supplied to the -linker when building a shared library. If you are attempting to -override a versioned symbol from a shared library, then NODENAME should -correspond to the nodename of the symbol you are trying to override. - - If the symbol NAME is not defined within the file being assembled, -all references to NAME will be changed to NAME2@NODENAME. If no -reference to NAME is made, NAME2@NODENAME will be removed from the -symbol table. - - Another usage of the '.symver' directive is: - .symver NAME, NAME2@@NODENAME - In this case, the symbol NAME must exist and be defined within the -file being assembled. It is similar to NAME2@NODENAME. The difference -is NAME2@@NODENAME will also be used to resolve references to NAME2 by -the linker. - - The third usage of the '.symver' directive is: - .symver NAME, NAME2@@@NODENAME - When NAME is not defined within the file being assembled, it is -treated as NAME2@NODENAME. When NAME is defined within the file being -assembled, the symbol name, NAME, will be changed to NAME2@@NODENAME. - -7.100 '.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. - -7.101 '.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. - -7.102 '.type' -============= - -This directive is used to set the type of a symbol. - - For ELF targets, the '.type' directive is used like this: - - .type NAME , TYPE DESCRIPTION - - This sets the type of symbol NAME to be either a function symbol or -an object symbol. There are five different syntaxes supported for the -TYPE DESCRIPTION field, in order to provide compatibility with various -other assemblers. - - Because some of the characters used in these syntaxes (such as '@' -and '#') are comment characters for some architectures, some of the -syntaxes below do not work on all architectures. The first variant will -be accepted by the GNU assembler on all architectures so that variant -should be used for maximum portability, if you do not need to assemble -your code with other assemblers. - - The syntaxes supported are: - - .type <name> STT_FUNCTION - .type <name> STT_OBJECT - - .type <name>,#function - .type <name>,#object - - .type <name>,@function - .type <name>,@object - - .type <name>,%function - .type <name>,%object - - .type <name>,"function" - .type <name>,"object" - -7.103 '.uleb128 EXPRESSIONS' -============================ - -ULEB128 stands for "unsigned little endian base 128." This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. *Note '.sleb128': Sleb128. - -7.104 '.version "STRING"' -========================= - -This directive creates a '.note' section and places into it an ELF -formatted note of type NT_VERSION. The note's name is set to 'string'. - -7.105 '.vtable_entry TABLE, OFFSET' -=================================== - -This directive finds or creates a symbol 'table' and creates a -'VTABLE_ENTRY' relocation for it with an addend of 'offset'. - -7.106 '.vtable_inherit CHILD, PARENT' -===================================== - -This directive finds the symbol 'child' and finds or creates the symbol -'parent' and then creates a 'VTABLE_INHERIT' relocation for the parent -whose addend is the value of the child symbol. As a special case the -parent name of '0' is treated as referring to the '*ABS*' section. - -7.107 '.warning "STRING"' -========================= - -Similar to the directive '.error' (*note '.error "STRING"': Error.), but -just emits a warning. - -7.108 '.weak NAMES' -=================== - -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - On COFF targets other than PE, weak symbols are a GNU extension. -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - On the PE target, weak symbols are supported natively as weak -aliases. When a weak symbol is created that is not an alias, GAS -creates an alternate symbol to hold the default value. - -7.109 '.weakref ALIAS, TARGET' -============================== - -This directive creates an alias to the target symbol that enables the -symbol to be referenced with weak-symbol semantics, but without actually -making it weak. If direct references or definitions of the symbol are -present, then the symbol will not be weak, but if all references to it -are through weak references, the symbol will be marked as weak in the -symbol table. - - The effect is equivalent to moving all references to the alias to a -separate assembly source file, renaming the alias to the symbol in it, -declaring the symbol as weak there, and running a reloadable link to -merge the object files resulting from the assembly of the new source -file and the old source file that had the references to the alias -removed. - - The alias itself never makes to the symbol table, and is entirely -handled within the assembler. - -7.110 '.word EXPRESSIONS' -========================= - -This directive expects zero or more EXPRESSIONS, of any section, -separated by commas. For each expression, 'as' emits a 32-bit number. - -7.111 Deprecated Directives -=========================== - -One day these directives won't work. They are included for -compatibility with older assemblers. -.abort -.line - -8 ARM Dependent Features -************************ - -8.1 Options -=========== - -'-mcpu=PROCESSOR[+EXTENSION...]' - This option specifies the target processor. The assembler will - issue an error message if an attempt is made to assemble an - instruction which will not execute on the target processor. The - following processor names are recognized: 'arm1', 'arm2', 'arm250', - 'arm3', 'arm6', 'arm60', 'arm600', 'arm610', 'arm620', 'arm7', - 'arm7m', 'arm7d', 'arm7dm', 'arm7di', 'arm7dmi', 'arm70', 'arm700', - 'arm700i', 'arm710', 'arm710t', 'arm720', 'arm720t', 'arm740t', - 'arm710c', 'arm7100', 'arm7500', 'arm7500fe', 'arm7t', 'arm7tdmi', - 'arm7tdmi-s', 'arm8', 'arm810', 'strongarm', 'strongarm1', - 'strongarm110', 'strongarm1100', 'strongarm1110', 'arm9', 'arm920', - 'arm920t', 'arm922t', 'arm940t', 'arm9tdmi', 'arm9e', 'arm926e', - 'arm926ej-s', 'arm946e-r0', 'arm946e', 'arm946e-s', 'arm966e-r0', - 'arm966e', 'arm966e-s', 'arm968e-s', 'arm10t', 'arm10tdmi', - 'arm10e', 'arm1020', 'arm1020t', 'arm1020e', 'arm1022e', - 'arm1026ej-s', 'arm1136j-s', 'arm1136jf-s', 'arm1156t2-s', - 'arm1156t2f-s', 'arm1176jz-s', 'arm1176jzf-s', 'mpcore', - 'mpcorenovfp', 'cortex-a8', 'cortex-r4', 'cortex-m3', 'ep9312' - (ARM920 with Cirrus Maverick coprocessor), 'i80200' (Intel XScale - processor) 'iwmmxt' (Intel(r) XScale processor with Wireless - MMX(tm) technology coprocessor) and 'xscale'. The special name - 'all' may be used to allow the assembler to accept instructions - valid for any ARM processor. - - In addition to the basic instruction set, the assembler can be told - to accept various extension mnemonics that extend the processor - using the co-processor instruction space. For example, - '-mcpu=arm920+maverick' is equivalent to specifying '-mcpu=ep9312'. - The following extensions are currently supported: '+maverick' - '+iwmmxt' and '+xscale'. - -'-march=ARCHITECTURE[+EXTENSION...]' - This option specifies the target architecture. The assembler will - issue an error message if an attempt is made to assemble an - instruction which will not execute on the target architecture. The - following architecture names are recognized: 'armv1', 'armv2', - 'armv2a', 'armv2s', 'armv3', 'armv3m', 'armv4', 'armv4xm', - 'armv4t', 'armv4txm', 'armv5', 'armv5t', 'armv5txm', 'armv5te', - 'armv5texp', 'armv6', 'armv6j', 'armv6k', 'armv6z', 'armv6zk', - 'armv7', 'armv7-a', 'armv7-r', 'armv7-m', 'iwmmxt' and 'xscale'. - If both '-mcpu' and '-march' are specified, the assembler will use - the setting for '-mcpu'. - - The architecture option can be extended with the same instruction - set extension options as the '-mcpu' option. - -'-mfpu=FLOATING-POINT-FORMAT' - - This option specifies the floating point format to assemble for. - The assembler will issue an error message if an attempt is made to - assemble an instruction which will not execute on the target - floating point unit. The following format options are recognized: - 'softfpa', 'fpe', 'fpe2', 'fpe3', 'fpa', 'fpa10', 'fpa11', - 'arm7500fe', 'softvfp', 'softvfp+vfp', 'vfp', 'vfp10', 'vfp10-r0', - 'vfp9', 'vfpxd', 'arm1020t', 'arm1020e', 'arm1136jf-s' and - 'maverick'. - - In addition to determining which instructions are assembled, this - option also affects the way in which the '.double' assembler - directive behaves when assembling little-endian code. - - The default is dependent on the processor selected. For - Architecture 5 or later, the default is to assembler for VFP - instructions; for earlier architectures the default is to assemble - for FPA instructions. - -'-mthumb' - This option specifies that the assembler should start assembling - Thumb instructions; that is, it should behave as though the file - starts with a '.code 16' directive. - -'-mthumb-interwork' - This option specifies that the output generated by the assembler - should be marked as supporting interworking. - -'-mapcs [26|32]' - This option specifies that the output generated by the assembler - should be marked as supporting the indicated version of the Arm - Procedure. Calling Standard. - -'-matpcs' - This option specifies that the output generated by the assembler - should be marked as supporting the Arm/Thumb Procedure Calling - Standard. If enabled this option will cause the assembler to - create an empty debugging section in the object file called - .arm.atpcs. Debuggers can use this to determine the ABI being used - by. - -'-mapcs-float' - This indicates the floating point variant of the APCS should be - used. In this variant floating point arguments are passed in FP - registers rather than integer registers. - -'-mapcs-reentrant' - This indicates that the reentrant variant of the APCS should be - used. This variant supports position independent code. - -'-mfloat-abi=ABI' - This option specifies that the output generated by the assembler - should be marked as using specified floating point ABI. The - following values are recognized: 'soft', 'softfp' and 'hard'. - -'-meabi=VER' - This option specifies which EABI version the produced object files - should conform to. The following values are recognized: 'gnu', '4' - and '5'. - -'-EB' - This option specifies that the output generated by the assembler - should be marked as being encoded for a big-endian processor. - -'-EL' - This option specifies that the output generated by the assembler - should be marked as being encoded for a little-endian processor. - -'-k' - This option specifies that the output of the assembler should be - marked as position-independent code (PIC). - -8.2 Syntax -========== - -8.2.1 Special Characters ------------------------- - -The presence of a '@' on a line indicates the start of a comment that -extends to the end of the current line. If a '#' appears as the first -character of a line, the whole line is treated as a comment. - - The ';' character can be used instead of a newline to separate -statements. - - Either '#' or '$' can be used to indicate immediate operands. - - *TODO* Explain about /data modifier on symbols. - -8.2.2 Register Names --------------------- - -*TODO* Explain about ARM register naming, and the predefined names. - -8.2.3 ARM relocation generation -------------------------------- - -Specific data relocations can be generated by putting the relocation -name in parentheses after the symbol name. For example: - - .word foo(TARGET1) - - This will generate an 'R_ARM_TARGET1' relocation against the symbol -FOO. The following relocations are supported: 'GOT', 'GOTOFF', -'TARGET1', 'TARGET2', 'SBREL', 'TLSGD', 'TLSLDM', 'TLSLDO', 'GOTTPOFF' -and 'TPOFF'. - - For compatibility with older toolchains the assembler also accepts -'(PLT)' after branch targets. This will generate the deprecated -'R_ARM_PLT32' relocation. - - Relocations for 'MOVW' and 'MOVT' instructions can be generated by -prefixing the value with '#:lower16:' and '#:upper16' respectively. For -example to load the 32-bit address of foo into r0: - - MOVW r0, #:lower16:foo - MOVT r0, #:upper16:foo - -8.3 Floating Point -================== - -The ARM family uses IEEE floating-point numbers. - -8.4 ARM Machine Directives -========================== - -'.align EXPRESSION [, EXPRESSION]' - This is the generic .ALIGN directive. For the ARM however if the - first argument is zero (ie no alignment is needed) the assembler - will behave as if the argument had been 2 (ie pad to the next four - byte boundary). This is for compatibility with ARM's own - assembler. - -'NAME .req REGISTER NAME' - This creates an alias for REGISTER NAME called NAME. For example: - - foo .req r0 - -'.unreq ALIAS-NAME' - This undefines a register alias which was previously defined using - the 'req', 'dn' or 'qn' directives. For example: - - foo .req r0 - .unreq foo - - An error occurs if the name is undefined. Note - this pseudo op - can be used to delete builtin in register name aliases (eg 'r0'). - This should only be done if it is really necessary. - -'NAME .dn REGISTER NAME [.TYPE] [[INDEX]]' -'NAME .qn REGISTER NAME [.TYPE] [[INDEX]]' - - The 'dn' and 'qn' directives are used to create typed and/or - indexed register aliases for use in Advanced SIMD Extension (Neon) - instructions. The former should be used to create aliases of - double-precision registers, and the latter to create aliases of - quad-precision registers. - - If these directives are used to create typed aliases, those aliases - can be used in Neon instructions instead of writing types after the - mnemonic or after each operand. For example: - - x .dn d2.f32 - y .dn d3.f32 - z .dn d4.f32[1] - vmul x,y,z - - This is equivalent to writing the following: - - vmul.f32 d2,d3,d4[1] - - Aliases created using 'dn' or 'qn' can be destroyed using 'unreq'. - -'.code [16|32]' - This directive selects the instruction set being generated. The - value 16 selects Thumb, with the value 32 selecting ARM. - -'.thumb' - This performs the same action as .CODE 16. - -'.arm' - This performs the same action as .CODE 32. - -'.force_thumb' - This directive forces the selection of Thumb instructions, even if - the target processor does not support those instructions - -'.thumb_func' - This directive specifies that the following symbol is the name of a - Thumb encoded function. This information is necessary in order to - allow the assembler and linker to generate correct code for - interworking between Arm and Thumb instructions and should be used - even if interworking is not going to be performed. The presence of - this directive also implies '.thumb' - - This directive is not neccessary when generating EABI objects. On - these targets the encoding is implicit when generating Thumb code. - -'.thumb_set' - This performs the equivalent of a '.set' directive in that it - creates a symbol which is an alias for another symbol (possibly not - yet defined). This directive also has the added property in that - it marks the aliased symbol as being a thumb function entry point, - in the same way that the '.thumb_func' directive does. - -'.ltorg' - This directive causes the current contents of the literal pool to - be dumped into the current section (which is assumed to be the - .text section) at the current location (aligned to a word - boundary). 'GAS' maintains a separate literal pool for each - section and each sub-section. The '.ltorg' directive will only - affect the literal pool of the current section and sub-section. At - the end of assembly all remaining, un-empty literal pools will - automatically be dumped. - - Note - older versions of 'GAS' would dump the current literal pool - any time a section change occurred. This is no longer done, since - it prevents accurate control of the placement of literal pools. - -'.pool' - This is a synonym for .ltorg. - -'.unwind_fnstart' - Marks the start of a function with an unwind table entry. - -'.unwind_fnend' - Marks the end of a function with an unwind table entry. The unwind - index table entry is created when this directive is processed. - - If no personality routine has been specified then standard - personality routine 0 or 1 will be used, depending on the number of - unwind opcodes required. - -'.cantunwind' - Prevents unwinding through the current function. No personality - routine or exception table data is required or permitted. - -'.personality NAME' - Sets the personality routine for the current function to NAME. - -'.personalityindex INDEX' - Sets the personality routine for the current function to the EABI - standard routine number INDEX - -'.handlerdata' - Marks the end of the current function, and the start of the - exception table entry for that function. Anything between this - directive and the '.fnend' directive will be added to the exception - table entry. - - Must be preceded by a '.personality' or '.personalityindex' - directive. - -'.save REGLIST' - Generate unwinder annotations to restore the registers in REGLIST. - The format of REGLIST is the same as the corresponding - store-multiple instruction. - - _core registers_ - .save {r4, r5, r6, lr} - stmfd sp!, {r4, r5, r6, lr} - _FPA registers_ - .save f4, 2 - sfmfd f4, 2, [sp]! - _VFP registers_ - .save {d8, d9, d10} - fstmdx sp!, {d8, d9, d10} - _iWMMXt registers_ - .save {wr10, wr11} - wstrd wr11, [sp, #-8]! - wstrd wr10, [sp, #-8]! - or - .save wr11 - wstrd wr11, [sp, #-8]! - .save wr10 - wstrd wr10, [sp, #-8]! - -'.vsave VFP-REGLIST' - Generate unwinder annotations to restore the VFP registers in - VFP-REGLIST using FLDMD. Also works for VFPv3 registers that are to - be restored using VLDM. The format of VFP-REGLIST is the same as - the corresponding store-multiple instruction. - - _VFP registers_ - .vsave {d8, d9, d10} - fstmdd sp!, {d8, d9, d10} - _VFPv3 registers_ - .vsave {d15, d16, d17} - vstm sp!, {d15, d16, d17} - - Since FLDMX and FSTMX are now deprecated, this directive should be - used in favour of '.save' for saving VFP registers for ARMv6 and - above. - -'.pad #COUNT' - Generate unwinder annotations for a stack adjustment of COUNT - bytes. A positive value indicates the function prologue allocated - stack space by decrementing the stack pointer. - -'.movsp REG [, #OFFSET]' - Tell the unwinder that REG contains an offset from the current - stack pointer. If OFFSET is not specified then it is assumed to be - zero. - -'.setfp FPREG, SPREG [, #OFFSET]' - Make all unwinder annotations relaive to a frame pointer. Without - this the unwinder will use offsets from the stack pointer. - - The syntax of this directive is the same as the 'sub' or 'mov' - instruction used to set the frame pointer. SPREG must be either - 'sp' or mentioned in a previous '.movsp' directive. - - .movsp ip - mov ip, sp - ... - .setfp fp, ip, #4 - sub fp, ip, #4 - -'.raw OFFSET, BYTE1, ...' - Insert one of more arbitary unwind opcode bytes, which are known to - adjust the stack pointer by OFFSET bytes. - - For example '.unwind_raw 4, 0xb1, 0x01' is equivalent to '.save - {r0}' - -'.cpu NAME' - Select the target processor. Valid values for NAME are the same as - for the '-mcpu' commandline option. - -'.arch NAME' - Select the target architecture. Valid values for NAME are the same - as for the '-march' commandline option. - -'.object_arch NAME' - Override the architecture recorded in the EABI object attribute - section. Valid values for NAME are the same as for the '.arch' - directive. Typically this is useful when code uses runtime - detection of CPU features. - -'.fpu NAME' - Select the floating point unit to assemble for. Valid values for - NAME are the same as for the '-mfpu' commandline option. - -'.eabi_attribute TAG, VALUE' - Set the EABI object attribute number TAG to VALUE. The value is - either a 'number', '"string"', or 'number, "string"' depending on - the tag. - -8.5 Opcodes -=========== - -'as' implements all the standard ARM opcodes. It also implements -several pseudo opcodes, including several synthetic load instructions. - -'NOP' - nop - - This pseudo op will always evaluate to a legal ARM instruction that - does nothing. Currently it will evaluate to MOV r0, r0. - -'LDR' - ldr <register> , = <expression> - - If expression evaluates to a numeric constant then a MOV or MVN - instruction will be used in place of the LDR instruction, if the - constant can be generated by either of these instructions. - Otherwise the constant will be placed into the nearest literal pool - (if it not already there) and a PC relative LDR instruction will be - generated. - -'ADR' - adr <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to a PC relative ADD or - SUB instruction depending upon where the label is located. If the - label is out of range, or if it is not defined in the same file - (and section) as the ADR instruction, then an error will be - generated. This instruction will not make use of the literal pool. - -'ADRL' - adrl <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to one or two PC relative - ADD or SUB instructions depending upon where the label is located. - If a second instruction is not needed a NOP instruction will be - generated in its place, so that this instruction is always 8 bytes - long. - - If the label is out of range, or if it is not defined in the same - file (and section) as the ADRL instruction, then an error will be - generated. This instruction will not make use of the literal pool. - - For information on the ARM or Thumb instruction sets, see 'ARM -Software Development Toolkit Reference Manual', Advanced RISC Machines -Ltd. - -8.6 Mapping Symbols -=================== - -The ARM ELF specification requires that special symbols be inserted into -object files to mark certain features: - -'$a' - At the start of a region of code containing ARM instructions. - -'$t' - At the start of a region of code containing THUMB instructions. - -'$d' - At the start of a region of data. - - The assembler will automatically insert these symbols for you - there -is no need to code them yourself. Support for tagging symbols ($b, $f, -$p and $m) which is also mentioned in the current ARM ELF specification -is not implemented. This is because they have been dropped from the new -EABI and so tools cannot rely upon their presence. - -9 80386 Dependent Features -************************** - -The i386 version 'as' supports both the original Intel 386 architecture -in both 16 and 32-bit mode as well as AMD x86-64 architecture extending -the Intel architecture to 64-bits. - -9.1 Options -=========== - -The i386 version of 'as' has a few machine dependent options: - -'--32 | --64' - Select the word size, either 32 bits or 64 bits. Selecting 32-bit - implies Intel i386 architecture, while 64-bit implies AMD x86-64 - architecture. - - These options are only available with the ELF object file format, - and require that the necessary BFD support has been included (on a - 32-bit platform you have to add -enable-64-bit-bfd to configure - enable 64-bit usage and use x86-64 as target platform). - -'-n' - By default, x86 GAS replaces multiple nop instructions used for - alignment within code sections with multi-byte nop instructions - such as leal 0(%esi,1),%esi. This switch disables the - optimization. - -'--divide' - On SVR4-derived platforms, the character '/' is treated as a - comment character, which means that it cannot be used in - expressions. The '--divide' option turns '/' into a normal - character. This does not disable '/' at the beginning of a line - starting a comment, or affect using '#' for starting a comment. - -'-march=CPU' - This option specifies an instruction set architecture for - generating instructions. The following architectures are - recognized: 'i8086', 'i186', 'i286', 'i386', 'i486', 'i586', - 'i686', 'pentium', 'pentiumpro', 'pentiumii', 'pentiumiii', - 'pentium4', 'prescott', 'nocona', 'core', 'core2', 'k6', 'k6_2', - 'athlon', 'sledgehammer', 'opteron', 'k8', 'generic32' and - 'generic64'. - - This option only affects instructions generated by the assembler. - The '.arch' directive will take precedent. - -'-mtune=CPU' - This option specifies a processor to optimize for. When used in - conjunction with the '-march' option, only instructions of the - processor specified by the '-march' option will be generated. - - Valid CPU values are identical to '-march=CPU'. - -9.2 AT&T Syntax versus Intel Syntax -=================================== - -'as' now supports assembly using Intel assembler syntax. -'.intel_syntax' selects Intel mode, and '.att_syntax' switches back to -the usual AT&T mode for compatibility with the output of 'gcc'. Either -of these directives may have an optional argument, 'prefix', or -'noprefix' specifying whether registers require a '%' prefix. AT&T -System V/386 assembler syntax is quite different from Intel syntax. We -mention these differences because almost all 80386 documents use 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. Note that instructions with more than - one source operand, such as the 'enter' instruction, do _not_ have - reversed order. *note i386-Bugs::. - - * In AT&T syntax the size of memory operands is determined from the - last character of the instruction mnemonic. Mnemonic suffixes of - 'b', 'w', 'l' and 'q' specify byte (8-bit), word (16-bit), long - (32-bit) and quadruple word (64-bit) memory references. Intel - syntax accomplishes this by prefixing memory operands (_not_ the - instruction mnemonics) with 'byte ptr', 'word ptr', 'dword ptr' and - 'qword 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. - -9.3 Instruction Naming -====================== - -Instruction mnemonics are suffixed with one character modifiers which -specify the size of operands. The letters 'b', 'w', 'l' and 'q' specify -byte, word, long and quadruple word operands. If no suffix is specified -by an instruction 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 mnemonic suffix implies -long operand size. (This incompatibility does not affect compiler -output since compilers always explicitly specify the mnemonic suffix.) - - Almost all instructions 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 instruction mnemonic 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 instruction -mnemonic 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), 'wl' (from word to -long), 'bq' (from byte to quadruple word), 'wq' (from word to quadruple -word), and 'lq' (from long to quadruple word). - - 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', - - * 'cdqe' -- sign-extend dword in '%eax' to quad in '%rax' (x86-64 - only), - - * 'cqo' -- sign-extend quad in '%rax' to octuple in '%rdx:%rax' - (x86-64 only), - -are called 'cbtw', 'cwtl', 'cwtd', 'cltd', 'cltq', and 'cqto' 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. - -9.4 Register Naming -=================== - -Register operands are always prefixed 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)'. These registers are overloaded by 8 MMX registers - '%mm0', '%mm1', '%mm2', '%mm3', '%mm4', '%mm5', '%mm6' and '%mm7'. - - * the 8 SSE registers registers '%xmm0', '%xmm1', '%xmm2', '%xmm3', - '%xmm4', '%xmm5', '%xmm6' and '%xmm7'. - - The AMD x86-64 architecture extends the register set by: - - * enhancing the 8 32-bit registers to 64-bit: '%rax' (the - accumulator), '%rbx', '%rcx', '%rdx', '%rdi', '%rsi', '%rbp' (the - frame pointer), '%rsp' (the stack pointer) - - * the 8 extended registers '%r8'-'%r15'. - - * the 8 32-bit low ends of the extended registers: '%r8d'-'%r15d' - - * the 8 16-bit low ends of the extended registers: '%r8w'-'%r15w' - - * the 8 8-bit low ends of the extended registers: '%r8b'-'%r15b' - - * the 4 8-bit registers: '%sil', '%dil', '%bpl', '%spl'. - - * the 8 debug registers: '%db8'-'%db15'. - - * the 8 SSE registers: '%xmm8'-'%xmm15'. - -9.5 Instruction Prefixes -======================== - -Instruction prefixes are used to modify the following instruction. They -are used to repeat string instructions, to provide section overrides, to -perform bus lock operations, and to change operand and address sizes. -(Most instructions that normally operate on 32-bit operands will use -16-bit operands if the instruction has an "operand size" prefix.) -Instruction prefixes are best written on the same line as the -instruction they act upon. For example, the 'scas' (scan string) -instruction is repeated with: - - repne scas %es:(%edi),%al - - You may also place prefixes on the lines immediately preceding the -instruction, but this circumvents checks that 'as' does with prefixes, -and will not work with all prefixes. - - Here is a list of instruction 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, while 'data32' - and 'addr32' change 16-bit ones (in a '.code16' section) into - 32-bit operands/addresses. These prefixes _must_ appear on the - same line of code as the instruction they modify. For example, in - a 16-bit '.code16' section, you might write: - - addr32 jmpl *(%ebx) - - * 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 ('%cx' times if the - current address size is 16-bits). - * The 'rex' family of prefixes is used by x86-64 to encode extensions - to i386 instruction set. The 'rex' prefix has four bits -- an - operand size overwrite ('64') used to change operand size from - 32-bit to 64-bit and X, Y and Z extensions bits used to extend the - register set. - - You may write the 'rex' prefixes directly. The 'rex64xyz' - instruction emits 'rex' prefix with all the bits set. By omitting - the '64', 'x', 'y' or 'z' you may write other prefixes as well. - Normally, there is no need to write the prefixes explicitly, since - gas will automatically generate them based on the instruction - operands. - -9.6 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_ be -preceded by a '%'. If you specify a section override which coincides -with the default section register, 'as' does _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' always chooses PC -relative addressing for jump/call labels. - - Any instruction that has a memory operand, but no register operand, -_must_ specify its size (byte, word, long, or quadruple) with an -instruction mnemonic suffix ('b', 'w', 'l' or 'q', respectively). - - The x86-64 architecture adds an RIP (instruction pointer relative) -addressing. This addressing mode is specified by using 'rip' as a base -register. Only constant offsets are valid. For example: - -AT&T: '1234(%rip)', Intel: '[rip + 1234]' - Points to the address 1234 bytes past the end of the current - instruction. - -AT&T: 'symbol(%rip)', Intel: '[rip + symbol]' - Points to the 'symbol' in RIP relative way, this is shorter than - the default absolute addressing. - - Other addressing modes remain unchanged in x86-64 architecture, -except registers used are 64-bit instead of 32-bit. - -9.7 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 displacement is used. We do not support word -(16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump -instruction with the 'data16' instruction prefix), since the 80386 -insists upon masking '%eip' to 16 bits after the word displacement is -added. (See also *note i386-Arch::) - - Note that the 'jcxz', 'jecxz', 'loop', 'loopz', 'loope', 'loopnz' and -'loopne' instructions only come in byte displacements, so that if you -use these instructions ('gcc' does not use them) you may get an error -message (and 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: - -9.8 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 instruction mnemonic suffix and a constructor associated with it. -Instruction mnemonic suffixes specify the operand's data type. -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 instruction mnemonic suffixes 's', 'l', and 't'. 't' stands for - 80-bit (ten byte) real. The 80387 only supports this format via - the 'fldt' (load 80-bit real to stack top) and 'fstpt' (store - 80-bit 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 - instruction mnemonic suffixes are 's' (single), 'l' (long), and 'q' - (quad). As with the 80-bit 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 should not use instruction mnemonic -suffixes. 'fstl %st, %st(1)' will give a warning, and be assembled as -if you wrote 'fst %st, %st(1)', since all register to register -operations use 80-bit floating point operands. (Contrast this with -'fstl %st, mem', which converts '%st' from 80-bit to 64-bit floating -point format, then stores the result in the 4 byte location 'mem') - -9.9 Intel's MMX and AMD's 3DNow! SIMD Operations -================================================ - -'as' supports Intel's MMX instruction set (SIMD instructions for integer -data), available on Intel's Pentium MMX processors and Pentium II -processors, AMD's K6 and K6-2 processors, Cyrix' M2 processor, and -probably others. It also supports AMD's 3DNow! instruction set (SIMD -instructions for 32-bit floating point data) available on AMD's K6-2 -processor and possibly others in the future. - - Currently, 'as' does not support Intel's floating point SIMD, Katmai -(KNI). - - The eight 64-bit MMX operands, also used by 3DNow!, are called -'%mm0', '%mm1', ... '%mm7'. They contain eight 8-bit integers, four -16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit -floating point values. The MMX registers cannot be used at the same -time as the floating point stack. - - See Intel and AMD documentation, keeping in mind that the operand -order in instructions is reversed from the Intel syntax. - -9.10 Writing 16-bit Code -======================== - -While 'as' normally writes only "pure" 32-bit i386 code or 64-bit x86-64 -code depending on the default configuration, it also supports writing -code to run in real mode or in 16-bit protected mode code segments. To -do this, put a '.code16' or '.code16gcc' directive before the assembly -language instructions to be run in 16-bit mode. You can switch 'as' -back to writing normal 32-bit code with the '.code32' directive. - - '.code16gcc' provides experimental support for generating 16-bit code -from gcc, and differs from '.code16' in that 'call', 'ret', 'enter', -'leave', 'push', 'pop', 'pusha', 'popa', 'pushf', and 'popf' -instructions default to 32-bit size. This is so that the stack pointer -is manipulated in the same way over function calls, allowing access to -function parameters at the same stack offsets as in 32-bit mode. -'.code16gcc' also automatically adds address size prefixes where -necessary to use the 32-bit addressing modes that gcc generates. - - The code which 'as' generates in 16-bit mode will not necessarily run -on a 16-bit pre-80386 processor. To write code that runs on such a -processor, you must refrain from using _any_ 32-bit constructs which -require 'as' to output address or operand size prefixes. - - Note that writing 16-bit code instructions by explicitly specifying a -prefix or an instruction mnemonic suffix within a 32-bit code section -generates different machine instructions than those generated for a -16-bit code segment. In a 32-bit code section, the following code -generates the machine opcode bytes '66 6a 04', which pushes the value -'4' onto the stack, decrementing '%esp' by 2. - - pushw $4 - - The same code in a 16-bit code section would generate the machine -opcode bytes '6a 04' (i.e., without the operand size prefix), which is -correct since the processor default operand size is assumed to be 16 -bits in a 16-bit code section. - -9.11 AT&T Syntax bugs -===================== - -The UnixWare assembler, and probably other AT&T derived ix86 Unix -assemblers, generate floating point instructions with reversed source -and destination registers in certain cases. Unfortunately, gcc and -possibly many other programs use this reversed syntax, so we're stuck -with it. - - For example - - fsub %st,%st(3) -results in '%st(3)' being updated to '%st - %st(3)' rather than the -expected '%st(3) - %st'. This happens with all the non-commutative -arithmetic floating point operations with two register operands where -the source register is '%st' and the destination register is '%st(i)'. - -9.12 Specifying CPU Architecture -================================ - -'as' may be told to assemble for a particular CPU (sub-)architecture -with the '.arch CPU_TYPE' directive. This directive enables a warning -when gas detects an instruction that is not supported on the CPU -specified. The choices for CPU_TYPE are: - -'i8086' 'i186' 'i286' 'i386' -'i486' 'i586' 'i686' 'pentium' -'pentiumpro' 'pentiumii' 'pentiumiii' 'pentium4' -'prescott' 'nocona' 'core' 'core2' -'amdfam10' -'k6' 'athlon' 'sledgehammer' 'k8' -'.mmx' '.sse' '.sse2' '.sse3' -'.ssse3' '.sse4.1' '.sse4.2' '.sse4' -'.sse4a' '.3dnow' '.3dnowa' '.padlock' -'.pacifica' '.svme' '.abm' - - Apart from the warning, there are only two other effects on 'as' -operation; Firstly, if you specify a CPU other than 'i486', then shift -by one instructions such as 'sarl $1, %eax' will automatically use a two -byte opcode sequence. The larger three byte opcode sequence is used on -the 486 (and when no architecture is specified) because it executes -faster on the 486. Note that you can explicitly request the two byte -opcode by writing 'sarl %eax'. Secondly, if you specify 'i8086', -'i186', or 'i286', _and_ '.code16' or '.code16gcc' then byte offset -conditional jumps will be promoted when necessary to a two instruction -sequence consisting of a conditional jump of the opposite sense around -an unconditional jump to the target. - - Following the CPU architecture (but not a sub-architecture, which are -those starting with a dot), you may specify 'jumps' or 'nojumps' to -control automatic promotion of conditional jumps. 'jumps' is the -default, and enables jump promotion; All external jumps will be of the -long variety, and file-local jumps will be promoted as necessary. -(*note i386-Jumps::) 'nojumps' leaves external conditional jumps as byte -offset jumps, and warns about file-local conditional jumps that 'as' -promotes. Unconditional jumps are treated as for 'jumps'. - - For example - - .arch i8086,nojumps - -9.13 Notes -========== - -There is some trickery concerning the 'mul' and 'imul' instructions that -deserves mention. The 16-, 32-, 64- and 128-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'. - -10 IA-64 Dependent Features -*************************** - -10.1 Options -============ - -'-mconstant-gp' - This option instructs the assembler to mark the resulting object - file as using the "constant GP" model. With this model, it is - assumed that the entire program uses a single global pointer (GP) - value. Note that this option does not in any fashion affect the - machine code emitted by the assembler. All it does is turn on the - EF_IA_64_CONS_GP flag in the ELF file header. - -'-mauto-pic' - This option instructs the assembler to mark the resulting object - file as using the "constant GP without function descriptor" data - model. This model is like the "constant GP" model, except that it - additionally does away with function descriptors. What this means - is that the address of a function refers directly to the function's - code entry-point. Normally, such an address would refer to a - function descriptor, which contains both the code entry-point and - the GP-value needed by the function. Note that this option does - not in any fashion affect the machine code emitted by the - assembler. All it does is turn on the EF_IA_64_NOFUNCDESC_CONS_GP - flag in the ELF file header. - -'-milp32' -'-milp64' -'-mlp64' -'-mp64' - These options select the data model. The assembler defaults to - '-mlp64' (LP64 data model). - -'-mle' -'-mbe' - These options select the byte order. The '-mle' option selects - little-endian byte order (default) and '-mbe' selects big-endian - byte order. Note that IA-64 machine code always uses little-endian - byte order. - -'-mtune=itanium1' -'-mtune=itanium2' - Tune for a particular IA-64 CPU, ITANIUM1 or ITANIUM2. The default - is ITANIUM2. - -'-munwind-check=warning' -'-munwind-check=error' - These options control what the assembler will do when performing - consistency checks on unwind directives. '-munwind-check=warning' - will make the assembler issue a warning when an unwind directive - check fails. This is the default. '-munwind-check=error' will - make the assembler issue an error when an unwind directive check - fails. - -'-mhint.b=ok' -'-mhint.b=warning' -'-mhint.b=error' - These options control what the assembler will do when the 'hint.b' - instruction is used. '-mhint.b=ok' will make the assembler accept - 'hint.b'. '-mint.b=warning' will make the assembler issue a - warning when 'hint.b' is used. '-mhint.b=error' will make the - assembler treat 'hint.b' as an error, which is the default. - -'-x' -'-xexplicit' - These options turn on dependency violation checking. - -'-xauto' - This option instructs the assembler to automatically insert stop - bits where necessary to remove dependency violations. This is the - default mode. - -'-xnone' - This option turns off dependency violation checking. - -'-xdebug' - This turns on debug output intended to help tracking down bugs in - the dependency violation checker. - -'-xdebugn' - This is a shortcut for -xnone -xdebug. - -'-xdebugx' - This is a shortcut for -xexplicit -xdebug. - -10.2 Syntax -=========== - -The assembler syntax closely follows the IA-64 Assembly Language -Reference Guide. - -10.2.1 Special Characters -------------------------- - -'//' is the line comment token. - - ';' can be used instead of a newline to separate statements. - -10.2.2 Register Names ---------------------- - -The 128 integer registers are referred to as 'rN'. The 128 -floating-point registers are referred to as 'fN'. The 128 application -registers are referred to as 'arN'. The 128 control registers are -referred to as 'crN'. The 64 one-bit predicate registers are referred -to as 'pN'. The 8 branch registers are referred to as 'bN'. In -addition, the assembler defines a number of aliases: 'gp' ('r1'), 'sp' -('r12'), 'rp' ('b0'), 'ret0' ('r8'), 'ret1' ('r9'), 'ret2' ('r10'), -'ret3' ('r9'), 'fargN' ('f8+N'), and 'fretN' ('f8+N'). - - For convenience, the assembler also defines aliases for all named -application and control registers. For example, 'ar.bsp' refers to the -register backing store pointer ('ar17'). Similarly, 'cr.eoi' refers to -the end-of-interrupt register ('cr67'). - -10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names ------------------------------------------------------- - -The assembler defines bit masks for each of the bits in the IA-64 -processor status register. For example, 'psr.ic' corresponds to a value -of 0x2000. These masks are primarily intended for use with the -'ssm'/'sum' and 'rsm'/'rum' instructions, but they can be used anywhere -else where an integer constant is expected. - -10.3 Opcodes -============ - -For detailed information on the IA-64 machine instruction set, see the -IA-64 Architecture Handbook -(http://developer.intel.com/design/itanium/arch_spec.htm). - -11 MIPS Dependent Features -************************** - -GNU 'as' for MIPS architectures supports several different MIPS -processors, and MIPS ISA levels I through V, MIPS32, and MIPS64. For -information about the MIPS instruction set, see 'MIPS RISC -Architecture', by Kane and Heindrich (Prentice-Hall). For an overview -of MIPS assembly conventions, see "Appendix D: Assembly Language -Programming" in the same work. - -11.1 Assembler options -====================== - -The MIPS configurations of GNU 'as' support these special options: - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format. The default value is 8. - -'-EB' -'-EL' - Any MIPS configuration of 'as' can select big-endian or - little-endian output at run time (unlike the other GNU development - tools, which must be configured for one or the other). Use '-EB' - to select big-endian output, and '-EL' for little-endian. - -'-KPIC' - Generate SVR4-style PIC. This option tells the assembler to - generate SVR4-style position-independent macro expansions. It also - tells the assembler to mark the output file as PIC. - -'-mvxworks-pic' - Generate VxWorks PIC. This option tells the assembler to generate - VxWorks-style position-independent macro expansions. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' corresponds to the R2000 and R3000 processors, - '-mips2' to the R6000 processor, '-mips3' to the R4000 processor, - and '-mips4' to the R8000 and R10000 processors. '-mips5', - '-mips32', '-mips32r2', '-mips64', and '-mips64r2' correspond to - generic MIPS V, MIPS32, MIPS32 RELEASE 2, MIPS64, and MIPS64 - RELEASE 2 ISA processors, respectively. You can also switch - instruction sets during the assembly; see *note Directives to - override the ISA level: MIPS ISA. - -'-mgp32' -'-mfp32' - Some macros have different expansions for 32-bit and 64-bit - registers. The register sizes are normally inferred from the ISA - and ABI, but these flags force a certain group of registers to be - treated as 32 bits wide at all times. '-mgp32' controls the size - of general-purpose registers and '-mfp32' controls the size of - floating-point registers. - - The '.set gp=32' and '.set fp=32' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - - On some MIPS variants there is a 32-bit mode flag; when this flag - is set, 64-bit instructions generate a trap. Also, some 32-bit - OSes only save the 32-bit registers on a context switch, so it is - essential never to use the 64-bit registers. - -'-mgp64' -'-mfp64' - Assume that 64-bit registers are available. This is provided in - the interests of symmetry with '-mgp32' and '-mfp32'. - - The '.set gp=64' and '.set fp=64' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extensions to the MIPS32 instruction set, - which provides a number of new instructions which target smartcard - and cryptographic applications. This is equivalent to putting - '.set smartmips' at the start of the assembly file. - '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-mno-dspr2' - Generate code for the DSP Release 2 Application Specific Extension. - This option implies -mdsp. This tells the assembler to accept DSP - Release 2 instructions. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'-mfix7000' -'-mno-fix7000' - Cause nops to be inserted if the read of the destination register - of an mfhi or mflo instruction occurs in the following two - instructions. - -'-mfix-vr4120' -'-no-mfix-vr4120' - Insert nops to work around certain VR4120 errata. This option is - intended to be used on GCC-generated code: it is not designed to - catch all problems in hand-written assembler code. - -'-mfix-vr4130' -'-no-mfix-vr4130' - Insert nops to work around the VR4130 'mflo'/'mfhi' errata. - -'-m4010' -'-no-m4010' - Generate code for the LSI R4010 chip. This tells the assembler to - accept the R4010 specific instructions ('addciu', 'ffc', etc.), and - to not schedule 'nop' instructions around accesses to the 'HI' and - 'LO' registers. '-no-m4010' turns off this option. - -'-m4650' -'-no-m4650' - Generate code for the MIPS R4650 chip. This tells the assembler to - accept the 'mad' and 'madu' instruction, and to not schedule 'nop' - instructions around accesses to the 'HI' and 'LO' registers. - '-no-m4650' turns off this option. - -'-m3900' -'-no-m3900' -'-m4100' -'-no-m4100' - For each option '-mNNNN', generate code for the MIPS RNNNN chip. - This tells the assembler to accept instructions specific to that - chip, and to schedule for that chip's hazards. - -'-march=CPU' - Generate code for a particular MIPS cpu. It is exactly equivalent - to '-mCPU', except that there are more value of CPU understood. - Valid CPU value are: - - 2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, - vr4181, 4300, 4400, 4600, 4650, 5000, rm5200, rm5230, rm5231, - rm5261, rm5721, vr5400, vr5500, 6000, rm7000, 8000, rm9000, - 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 4kep, 4ksd, - m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, - 34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. Valid CPU values are - identical to '-march=CPU'. - -'-mabi=ABI' - Record which ABI the source code uses. The recognized arguments - are: '32', 'n32', 'o64', '64' and 'eabi'. - -'-msym32' -'-mno-sym32' - Equivalent to adding '.set sym32' or '.set nosym32' to the - beginning of the assembler input. *Note MIPS symbol sizes::. - -'-nocpp' - This option is ignored. It is accepted for command-line - compatibility with other assemblers, which use it to turn off C - style preprocessing. With GNU 'as', there is no need for '-nocpp', - because the GNU assembler itself never runs the C preprocessor. - -'--construct-floats' -'--no-construct-floats' - The '--no-construct-floats' option disables the construction of - double width floating point constants by loading the two halves of - the value into the two single width floating point registers that - make up the double width register. This feature is useful if the - processor support the FR bit in its status register, and this bit - is known (by the programmer) to be set. This bit prevents the - aliasing of the double width register by the single width - registers. - - By default '--construct-floats' is selected, allowing construction - of these floating point constants. - -'--trap' -'--no-break' - 'as' automatically macro expands certain division and - multiplication instructions to check for overflow and division by - zero. This option causes 'as' to generate code to take a trap - exception rather than a break exception when an error is detected. - The trap instructions are only supported at Instruction Set - Architecture level 2 and higher. - -'--break' -'--no-trap' - Generate code to take a break exception rather than a trap - exception when an error is detected. This is the default. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. Off by default on IRIX, on - elsewhere. - -'-mshared' -'-mno-shared' - When generating code using the Unix calling conventions (selected - by '-KPIC' or '-mcall_shared'), gas will normally generate code - which can go into a shared library. The '-mno-shared' option tells - gas to generate code which uses the calling convention, but can not - go into a shared library. The resulting code is slightly more - efficient. This option only affects the handling of the '.cpload' - and '.cpsetup' pseudo-ops. - -11.2 MIPS ECOFF object code -=========================== - -Assembling for a MIPS ECOFF target supports some additional sections -besides the usual '.text', '.data' and '.bss'. The additional sections -are '.rdata', used for read-only data, '.sdata', used for small data, -and '.sbss', used for small common objects. - - When assembling for ECOFF, the assembler uses the '$gp' ('$28') -register to form the address of a "small object". Any object in the -'.sdata' or '.sbss' sections is considered "small" in this sense. For -external objects, or for objects in the '.bss' section, you can use the -'gcc' '-G' option to control the size of objects addressed via '$gp'; -the default value is 8, meaning that a reference to any object eight -bytes or smaller uses '$gp'. Passing '-G 0' to 'as' prevents it from -using the '$gp' register on the basis of object size (but the assembler -uses '$gp' for objects in '.sdata' or 'sbss' in any case). The size of -an object in the '.bss' section is set by the '.comm' or '.lcomm' -directive that defines it. The size of an external object may be set -with the '.extern' directive. For example, '.extern sym,4' declares -that the object at 'sym' is 4 bytes in length, whie leaving 'sym' -otherwise undefined. - - Using small ECOFF objects requires linker support, and assumes that -the '$gp' register is correctly initialized (normally done automatically -by the startup code). MIPS ECOFF assembly code must not modify the -'$gp' register. - -11.3 Directives for debugging information -========================================= - -MIPS ECOFF 'as' supports several directives used for generating -debugging information which are not support by traditional MIPS -assemblers. These are '.def', '.endef', '.dim', '.file', '.scl', -'.size', '.tag', '.type', '.val', '.stabd', '.stabn', and '.stabs'. The -debugging information generated by the three '.stab' directives can only -be read by GDB, not by traditional MIPS debuggers (this enhancement is -required to fully support C++ debugging). These directives are -primarily used by compilers, not assembly language programmers! - -11.4 Directives to override the size of symbols -=============================================== - -The n64 ABI allows symbols to have any 64-bit value. Although this -provides a great deal of flexibility, it means that some macros have -much longer expansions than their 32-bit counterparts. For example, the -non-PIC expansion of 'dla $4,sym' is usually: - - lui $4,%highest(sym) - lui $1,%hi(sym) - daddiu $4,$4,%higher(sym) - daddiu $1,$1,%lo(sym) - dsll32 $4,$4,0 - daddu $4,$4,$1 - - whereas the 32-bit expansion is simply: - - lui $4,%hi(sym) - daddiu $4,$4,%lo(sym) - - n64 code is sometimes constructed in such a way that all symbolic -constants are known to have 32-bit values, and in such cases, it's -preferable to use the 32-bit expansion instead of the 64-bit expansion. - - You can use the '.set sym32' directive to tell the assembler that, -from this point on, all expressions of the form 'SYMBOL' or 'SYMBOL + -OFFSET' have 32-bit values. For example: - - .set sym32 - dla $4,sym - lw $4,sym+16 - sw $4,sym+0x8000($4) - - will cause the assembler to treat 'sym', 'sym+16' and 'sym+0x8000' as -32-bit values. The handling of non-symbolic addresses is not affected. - - The directive '.set nosym32' ends a '.set sym32' block and reverts to -the normal behavior. It is also possible to change the symbol size -using the command-line options '-msym32' and '-mno-sym32'. - - These options and directives are always accepted, but at present, -they have no effect for anything other than n64. - -11.5 Directives to override the ISA level -========================================= - -GNU 'as' supports an additional directive to change the MIPS Instruction -Set Architecture level on the fly: '.set mipsN'. N should be a number -from 0 to 5, or 32, 32r2, 64 or 64r2. The values other than 0 make the -assembler accept instructions for the corresponding ISA level, from that -point on in the assembly. '.set mipsN' affects not only which -instructions are permitted, but also how certain macros are expanded. -'.set mips0' restores the ISA level to its original level: either the -level you selected with command line options, or the default for your -configuration. You can use this feature to permit specific MIPS3 -instructions while assembling in 32 bit mode. Use this directive with -care! - - The '.set arch=CPU' directive provides even finer control. It -changes the effective CPU target and allows the assembler to use -instructions specific to a particular CPU. All CPUs supported by the -'-march' command line option are also selectable by this directive. The -original value is restored by '.set arch=default'. - - The directive '.set mips16' puts the assembler into MIPS 16 mode, in -which it will assemble instructions for the MIPS 16 processor. Use -'.set nomips16' to return to normal 32 bit mode. - - Traditional MIPS assemblers do not support this directive. - -11.6 Directives for extending MIPS 16 bit instructions -====================================================== - -By default, MIPS 16 instructions are automatically extended to 32 bits -when necessary. The directive '.set noautoextend' will turn this off. -When '.set noautoextend' is in effect, any 32 bit instruction must be -explicitly extended with the '.e' modifier (e.g., 'li.e $4,1000'). The -directive '.set autoextend' may be used to once again automatically -extend instructions when necessary. - - This directive is only meaningful when in MIPS 16 mode. Traditional -MIPS assemblers do not support this directive. - -11.7 Directive to mark data as an instruction -============================================= - -The '.insn' directive tells 'as' that the following data is actually -instructions. This makes a difference in MIPS 16 mode: when loading the -address of a label which precedes instructions, 'as' automatically adds -1 to the value, so that jumping to the loaded address will do the right -thing. - -11.8 Directives to save and restore options -=========================================== - -The directives '.set push' and '.set pop' may be used to save and -restore the current settings for all the options which are controlled by -'.set'. The '.set push' directive saves the current settings on a -stack. The '.set pop' directive pops the stack and restores the -settings. - - These directives can be useful inside an macro which must change an -option such as the ISA level or instruction reordering but does not want -to change the state of the code which invoked the macro. - - Traditional MIPS assemblers do not support these directives. - -11.9 Directives to control generation of MIPS ASE instructions -============================================================== - -The directive '.set mips3d' makes the assembler accept instructions from -the MIPS-3D Application Specific Extension from that point on in the -assembly. The '.set nomips3d' directive prevents MIPS-3D instructions -from being accepted. - - The directive '.set smartmips' makes the assembler accept -instructions from the SmartMIPS Application Specific Extension to the -MIPS32 ISA from that point on in the assembly. The '.set nosmartmips' -directive prevents SmartMIPS instructions from being accepted. - - The directive '.set mdmx' makes the assembler accept instructions -from the MDMX Application Specific Extension from that point on in the -assembly. The '.set nomdmx' directive prevents MDMX instructions from -being accepted. - - The directive '.set dsp' makes the assembler accept instructions from -the DSP Release 1 Application Specific Extension from that point on in -the assembly. The '.set nodsp' directive prevents DSP Release 1 -instructions from being accepted. - - The directive '.set dspr2' makes the assembler accept instructions -from the DSP Release 2 Application Specific Extension from that point on -in the assembly. This dirctive implies '.set dsp'. The '.set nodspr2' -directive prevents DSP Release 2 instructions from being accepted. - - The directive '.set mt' makes the assembler accept instructions from -the MT Application Specific Extension from that point on in the -assembly. The '.set nomt' directive prevents MT instructions from being -accepted. - - Traditional MIPS assemblers do not support these directives. - -12 PowerPC Dependent Features -***************************** - -12.1 Options -============ - -The PowerPC chip family includes several successive levels, using the -same core instruction set, but including a few additional instructions -at each level. There are exceptions to this however. For details on -what instructions each variant supports, please see the chip's -architecture reference manual. - - The following table lists all available PowerPC options. - -'-mpwrx | -mpwr2' - Generate code for POWER/2 (RIOS2). - -'-mpwr' - Generate code for POWER (RIOS1) - -'-m601' - Generate code for PowerPC 601. - -'-mppc, -mppc32, -m603, -m604' - Generate code for PowerPC 603/604. - -'-m403, -m405' - Generate code for PowerPC 403/405. - -'-m440' - Generate code for PowerPC 440. BookE and some 405 instructions. - -'-m7400, -m7410, -m7450, -m7455' - Generate code for PowerPC 7400/7410/7450/7455. - -'-mppc64, -m620' - Generate code for PowerPC 620/625/630. - -'-me500, -me500x2' - Generate code for Motorola e500 core complex. - -'-mspe' - Generate code for Motorola SPE instructions. - -'-mppc64bridge' - Generate code for PowerPC 64, including bridge insns. - -'-mbooke64' - Generate code for 64-bit BookE. - -'-mbooke, mbooke32' - Generate code for 32-bit BookE. - -'-me300' - Generate code for PowerPC e300 family. - -'-maltivec' - Generate code for processors with AltiVec instructions. - -'-mpower4' - Generate code for Power4 architecture. - -'-mpower5' - Generate code for Power5 architecture. - -'-mpower6' - Generate code for Power6 architecture. - -'-mcell' - Generate code for Cell Broadband Engine architecture. - -'-mcom' - Generate code Power/PowerPC common instructions. - -'-many' - Generate code for any architecture (PWR/PWRX/PPC). - -'-mregnames' - Allow symbolic names for registers. - -'-mno-regnames' - Do not allow symbolic names for registers. - -'-mrelocatable' - Support for GCC's -mrelocatable option. - -'-mrelocatable-lib' - Support for GCC's -mrelocatable-lib option. - -'-memb' - Set PPC_EMB bit in ELF flags. - -'-mlittle, -mlittle-endian' - Generate code for a little endian machine. - -'-mbig, -mbig-endian' - Generate code for a big endian machine. - -'-msolaris' - Generate code for Solaris. - -'-mno-solaris' - Do not generate code for Solaris. - -12.2 PowerPC Assembler Directives -================================= - -A number of assembler directives are available for PowerPC. The -following table is far from complete. - -'.machine "string"' - This directive allows you to change the machine for which code is - generated. '"string"' may be any of the -m cpu selection options - (without the -m) enclosed in double quotes, '"push"', or '"pop"'. - '.machine "push"' saves the currently selected cpu, which may be - restored with '.machine "pop"'. - -13 SPARC Dependent Features -*************************** - -13.1 Options -============ - -The SPARC chip family includes several successive levels, using the same -core instruction set, but including a few additional instructions at -each level. There are exceptions to this however. For details on what -instructions each variant supports, please see the chip's architecture -reference manual. - - 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. - - If not configured for SPARC v9 ('sparc64-*-*') GAS will not bump -passed sparclite by default, an option must be passed to enable the v9 -instructions. - - GAS treats sparclite as being compatible with v8, unless an -architecture is explicitly requested. SPARC v9 is always incompatible -with sparclite. - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - 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 an incompatible or higher level. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. - - '-Av9' and '-Av9a' select a 64 bit environment and are not - available unless GAS is explicitly configured with 64 bit - environment support. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn whenever it is necessary to switch to another level. If an - architecture level is explicitly requested, GAS will not issue - warnings until that level is reached, and will then bump the level - as required (except between incompatible levels). - -'-32 | -64' - Select the word size, either 32 bits or 64 bits. These options are - only available with the ELF object file format, and require that - the necessary BFD support has been included. - -13.2 Enforcing aligned data -=========================== - -SPARC GAS normally permits data to be misaligned. For example, it -permits the '.long' pseudo-op to be used on a byte boundary. However, -the native SunOS and Solaris assemblers issue an error when they see -misaligned data. - - You can use the '--enforce-aligned-data' option to make SPARC GAS -also issue an error about misaligned data, just as the SunOS and Solaris -assemblers do. - - The '--enforce-aligned-data' option is not the default because gcc -issues misaligned data pseudo-ops when it initializes certain packed -data structures (structures defined using the 'packed' attribute). You -may have to assemble with GAS in order to initialize packed data -structures in your own code. - -13.3 Floating Point -=================== - -The Sparc uses IEEE floating-point numbers. - -13.4 Sparc Machine Directives -============================= - -The Sparc version of 'as' supports the following additional machine -directives: - -'.align' - This must be followed by the desired alignment in bytes. - -'.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'. - -'.nword' - On the Sparc, the '.nword' directive produces native word sized - value, ie. if assembling with -32 it is equivalent to '.word', if - assembling with -64 it is equivalent to '.xword'. - -'.proc' - This directive is ignored. Any text following it on the same line - is also ignored. - -'.register' - This directive declares use of a global application or system - register. It must be followed by a register name %g2, %g3, %g6 or - %g7, comma and the symbol name for that register. If symbol name - is '#scratch', it is a scratch register, if it is '#ignore', it - just suppresses any errors about using undeclared global register, - but does not emit any information about it into the object file. - This can be useful e.g. if you save the register before use and - restore it after. - -'.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. - -'.xword' - On the Sparc V9 processor, the '.xword' directive produces 64 bit - values. - -14 Reporting Bugs -***************** - -Your bug reports play an essential role in making 'as' reliable. - - Reporting a bug may help you by bringing a solution to your problem, -or it may not. But in any case the principal function of a bug report -is to help the entire community by making the next version of 'as' work -better. Bug reports are your contribution to the maintenance of 'as'. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -14.1 Have You Found a Bug? -========================== - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the assembler gets a fatal signal, for any input whatever, that - is a 'as' bug. Reliable assemblers never crash. - - * If 'as' produces an error message for valid input, that is a bug. - - * If 'as' does not produce an error message for invalid input, that - is a bug. However, you should note that your idea of "invalid - input" might be our idea of "an extension" or "support for - traditional practice". - - * If you are an experienced user of assemblers, your suggestions for - improvement of 'as' are welcome in any case. - -14.2 How to Report Bugs -======================= - -A number of companies and individuals offer support for GNU products. -If you obtained 'as' from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. - - The fundamental principle of reporting bugs usefully is this: *report -all the facts*. If you are not sure whether to state a fact or leave it -out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of a symbol you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is -a stray memory reference which happens to fetch from the location where -that name is stored in memory; perhaps, if the name were different, the -contents of that location would fool the assembler into doing the right -thing despite the bug. Play it safe and give a specific, complete -example. That is the easiest thing for you to do, and the most helpful. - - Keep in mind that the purpose of a bug report is to enable us to fix -the bug if it is new to us. Therefore, always write your bug reports on -the assumption that the bug has not been reported previously. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" This cannot help us fix a bug, so it is basically useless. We -respond by asking for enough details to enable us to investigate. You -might as well expedite matters by sending them to begin with. - - To enable us to fix the bug, you should include all these things: - - * The version of 'as'. 'as' announces it if you start it with the - '--version' argument. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of 'as'. - - * Any patches you may have applied to the 'as' source. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile 'as'--e.g. - "'gcc-2.7'". - - * The command arguments you gave the assembler to assemble your - example and observe the bug. To guarantee you will not omit - something important, list them all. A copy of the Makefile (or the - output from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input file that will reproduce the bug. If the bug is - observed when the assembler is invoked via a compiler, send the - assembler source, not the high level language source. Most - compilers will produce the assembler source when run with the '-S' - option. If you are using 'gcc', use the options '-v --save-temps'; - this will save the assembler source in a file with an extension of - '.s', and also show you exactly how 'as' is being run. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that 'as' gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - Even if the problem you experience is a fatal signal, you should - still say so explicitly. Suppose something strange is going on, - such as, your copy of 'as' is out of sync, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the 'as' source, send us context - diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. - Always send diffs from the old file to the new file. If you even - discuss something in the 'as' source, refer to it by context, not - by line number. - - The line numbers in our development sources will not match those in - your sources. Your line numbers would convey no useful information - to us. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - Often people who encounter a bug spend a lot of time investigating - which changes to the input file will make the bug go away and which - changes will not affect it. - - This is often time consuming and not very useful, because the way - we will find the bug is by running a single example under the - debugger with breakpoints, not by pure deduction from a series of - examples. We recommend that you save your time for something else. - - Of course, if you can find a simpler example to report _instead_ of - the original one, that is a convenience for us. Errors in the - output will be easier to spot, running under the debugger will take - less time, and so on. - - However, simplification is not vital; if you do not want to do - this, report the bug anyway and send us the entire test case you - used. - - * A patch for the bug. - - A patch for the bug does help us if it is a good one. But do not - omit the necessary information, such as the test case, on the - assumption that a patch is all we need. We might see problems with - your patch and decide to fix the problem another way, or we might - not understand it at all. - - Sometimes with a program as complicated as 'as' it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify that - the bug is fixed. - - And if we cannot understand what bug you are trying to fix, or why - your patch should be an improvement, we will not install it. A - test case will help us to understand. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - -15 Acknowledgements -******************* - -If you have contributed to GAS 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 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 back -ends (including heavy rewrite, testing, an integration of the coff and -b.out back ends), 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 and cpu32, did 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 Renesas H8/300 processors (tc-z8k, -tc-h8300), 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 -directives. 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 proverbial one-bit fix. - - Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax -for the 68k, completed support for some COFF targets (68k, i386 SVR3, -and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the -initial RS/6000 and PowerPC assembler, and made a few other minor -patches. - - Steve Chamberlain made GAS able to generate listings. - - Hewlett-Packard contributed support for the HP9000/300. - - Jeff Law wrote GAS and BFD support for the native HPPA object format -(SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF -object formats). This work was supported by both the Center for -Software Science at the University of Utah and Cygnus Support. - - 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). - - Linas Vepstas added GAS support for the ESA/390 "IBM 370" -architecture. - - Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote -GAS and BFD support for openVMS/Alpha. - - Timothy Wall, Michael Hayes, and Greg Smart contributed to the -various tic* flavors. - - David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from -Tensilica, Inc. added support for Xtensa processors. - - 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 have 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 are not intentionally leaving anyone out. - -Appendix A GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000, 2003 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. We - recommend this License principally for works whose purpose is - instruction or reference. - - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (For example, if the - Document is in part a textbook of mathematics, a Secondary Section - may not explain any mathematics.) The relationship could be a - matter of historical connection with the subject or with related - matters, or of legal, commercial, philosophical, ethical or - political position regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed to - thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque." - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and standard-conforming - simple HTML designed for human modification. Opaque formats - include PostScript, PDF, proprietary formats that can be read and - edited only by proprietary word processors, SGML or XML for which - the DTD and/or processing tools are not generally available, and - the machine-generated HTML produced by some word processors for - output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow the - conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies of the Document numbering more than - 100, and the Document's license notice requires Cover Texts, you - must enclose the copies in covers that carry, clearly and legibly, - all these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the title - equally prominent and visible. You may add other material on the - covers in addition. Copying with changes limited to the covers, as - long as they preserve the title of the Document and satisfy these - conditions, can be treated as verbatim copying in other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a machine-readable - Transparent copy along with each Opaque copy, or state in or with - each Opaque copy a publicly-accessible computer-network location - containing a complete Transparent copy of the Document, free of - added material, which the general network-using public has access - to download anonymously at no charge using public-standard network - protocols. If you use the latter option, you must take reasonably - prudent steps, when you begin distribution of Opaque copies in - quantity, to ensure that this Transparent copy will remain thus - accessible at the stated location until at least one year after the - last time you distribute an Opaque copy (directly or through your - agents or retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of copies, - to give them a chance to provide you with an updated version of the - Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus licensing - distribution and modification of the Modified Version to whoever - possesses a copy of it. In addition, you must do these things in - the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the History - section of the Document). You may use the same title as a previous - version if the original publisher of that version gives permission. - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in the - Modified Version, together with at least five of the principal - authors of the Document (all of its principal authors, if it has - less than five). - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - D. Preserve all the copyright notices of the Document. - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified Version - under the terms of this License, in the form shown in the Addendum - below. - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements." Such a section may - not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option designate - some or all of these sections as invariant. To do this, add their - titles to the list of Invariant Sections in the Modified Version's - license notice. These titles must be distinct from any other - section titles. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of - a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end of - the list of Cover Texts in the Modified Version. Only one passage - of Front-Cover Text and one of Back-Cover Text may be added by (or - through arrangements made by) any one entity. If the Document - already includes a cover text for the same cover, previously added - by you or by arrangement made by the same entity you are acting on - behalf of, you may not add another; but you may replace the old - one, on explicit permission from the previous publisher that added - the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination all - of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications." You - must delete all sections entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the documents - in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow this - License in all other respects regarding verbatim copying of that - document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation copyright - is claimed for the compilation. Such a compilation is called an - "aggregate", and this License does not apply to the other - self-contained works thus compiled with the Document, on account of - their being thus compiled, if they are not themselves derivative - works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document 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. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation 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. See - http://www.gnu.org/copyleft/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the GNU General Public License, to permit -their use in free software. - - ---------- Footnotes ---------- - - (1) Any more details? - -AS Index -******** - -* Menu: - -* #: Comments. (line 1306) -* #APP: Preprocessing. (line 1268) -* #NO_APP: Preprocessing. (line 1268) -* '$a': ARM Mapping Symbols. - (line 4193) -* '$d': ARM Mapping Symbols. - (line 4199) -* '$t': ARM Mapping Symbols. - (line 4196) -* --: Command Line. (line 760) -* '--32' option, i386: i386-Options. (line 4220) -* '--32' option, x86-64: i386-Options. (line 4220) -* '--64' option, i386: i386-Options. (line 4220) -* '--64' option, x86-64: i386-Options. (line 4220) -* --alternate: alternate. (line 929) -* '--divide' option, i386: i386-Options. (line 4236) -* --enforce-aligned-data: Sparc-Aligned-Data. (line 5460) -* --fatal-warnings: W. (line 1222) -* --hash-size=NUMBER: Overview. (line 459) -* --listing-cont-lines: listing. (line 1015) -* --listing-lhs-width: listing. (line 997) -* --listing-lhs-width2: listing. (line 1002) -* --listing-rhs-width: listing. (line 1009) -* --MD: MD. (line 1149) -* --no-warn: W. (line 1217) -* --statistics: statistics. (line 1188) -* --traditional-format: traditional-format. (line 1196) -* --warn: W. (line 1225) -* -a: a. (line 894) -* -ac: a. (line 894) -* -ad: a. (line 894) -* -ah: a. (line 894) -* -al: a. (line 894) -* -an: a. (line 894) -* -as: a. (line 894) -* -Asparclet: Sparc-Opts. (line 5421) -* -Asparclite: Sparc-Opts. (line 5421) -* -Av6: Sparc-Opts. (line 5421) -* -Av8: Sparc-Opts. (line 5421) -* -Av9: Sparc-Opts. (line 5421) -* -Av9a: Sparc-Opts. (line 5421) -* -construct-floats: MIPS Opts. (line 5056) -* -D: D. (line 934) -* '-eabi=' command line option, ARM: ARM Options. (line 3844) -* '-EB' command line option, ARM: ARM Options. (line 3849) -* '-EB' option (MIPS): MIPS Opts. (line 4879) -* '-EL' command line option, ARM: ARM Options. (line 3853) -* '-EL' option (MIPS): MIPS Opts. (line 4879) -* -f: f. (line 940) -* '-G' option (MIPS): MIPS Opts. (line 4874) -* -I PATH: I. (line 952) -* -K: K. (line 962) -* '-k' command line option, ARM: ARM Options. (line 3857) -* '-KPIC' option, MIPS: MIPS Opts. (line 4887) -* -L: L. (line 972) -* -M: M. (line 1022) -* '-mapcs' command line option, ARM: ARM Options. (line 3817) -* '-mapcs-float' command line option, ARM: ARM Options. (line 3830) -* '-mapcs-reentrant' command line option, ARM: ARM Options. (line 3835) -* '-march=' command line option, ARM: ARM Options. (line 3773) -* '-march=' option, i386: i386-Options. (line 4243) -* '-march=' option, x86-64: i386-Options. (line 4243) -* '-matpcs' command line option, ARM: ARM Options. (line 3822) -* '-mconstant-gp' command line option, IA-64: IA-64 Options. (line 4733) -* '-mcpu=' command line option, ARM: ARM Options. (line 3742) -* '-mfloat-abi=' command line option, ARM: ARM Options. (line 3839) -* '-mfpu=' command line option, ARM: ARM Options. (line 3788) -* -mno-sym32: MIPS Opts. (line 5045) -* -msym32: MIPS Opts. (line 5045) -* '-mthumb' command line option, ARM: ARM Options. (line 3808) -* '-mthumb-interwork' command line option, ARM: ARM Options. (line 3813) -* '-mtune=' option, i386: i386-Options. (line 4255) -* '-mtune=' option, x86-64: i386-Options. (line 4255) -* '-mvxworks-pic' option, MIPS: MIPS Opts. (line 4892) -* -no-construct-floats: MIPS Opts. (line 5056) -* '-nocpp' ignored (MIPS): MIPS Opts. (line 5048) -* -o: o. (line 1160) -* -R: R. (line 1170) -* -v: v. (line 1206) -* -version: v. (line 1206) -* -W: W. (line 1217) -* '.' (symbol): Dot. (line 1898) -* '.arch' directive, ARM: ARM Directives. (line 4118) -* '.cantunwind' directive, ARM: ARM Directives. (line 4022) -* '.cpu' directive, ARM: ARM Directives. (line 4114) -* '.eabi_attribute' directive, ARM: ARM Directives. (line 4132) -* '.fnend' directive, ARM: ARM Directives. (line 4014) -* '.fnstart' directive, ARM: ARM Directives. (line 4011) -* '.fpu' directive, ARM: ARM Directives. (line 4128) -* '.handlerdata' directive, ARM: ARM Directives. (line 4033) -* '.insn': MIPS insn. (line 5223) -* '.ltorg' directive, ARM: ARM Directives. (line 3994) -* '.movsp' directive, ARM: ARM Directives. (line 4088) -* .o: Object. (line 827) -* '.object_arch' directive, ARM: ARM Directives. (line 4122) -* '.pad' directive, ARM: ARM Directives. (line 4083) -* '.personality' directive, ARM: ARM Directives. (line 4026) -* '.personalityindex' directive, ARM: ARM Directives. (line 4029) -* '.pool' directive, ARM: ARM Directives. (line 4008) -* '.save' directive, ARM: ARM Directives. (line 4042) -* '.set arch=CPU': MIPS ISA. (line 5195) -* '.set autoextend': MIPS autoextend. (line 5210) -* '.set dsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set dspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set mdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set mips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set mipsN': MIPS ISA. (line 5183) -* '.set mt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set noautoextend': MIPS autoextend. (line 5210) -* '.set nodsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set nodspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set nomdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set nomips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set nomt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set nosmartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set nosym32': MIPS symbol sizes. (line 5140) -* '.set pop': MIPS option stack. (line 5232) -* '.set push': MIPS option stack. (line 5232) -* '.set smartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set sym32': MIPS symbol sizes. (line 5140) -* '.setfp' directive, ARM: ARM Directives. (line 4093) -* '.unwind_raw' directive, ARM: ARM Directives. (line 4107) -* '.vsave' directive, ARM: ARM Directives. (line 4066) -* 16-bit code, i386: i386-16bit. (line 4615) -* 3DNow!, i386: i386-SIMD. (line 4593) -* 3DNow!, x86-64: i386-SIMD. (line 4593) -* ':' (label): Statements. (line 1355) -* '\"' (doublequote character): Strings. (line 1423) -* '\b' (backspace character): Strings. (line 1395) -* '\DDD' (octal character code): Strings. (line 1410) -* '\f' (formfeed character): Strings. (line 1398) -* '\n' (newline character): Strings. (line 1401) -* '\r' (carriage return character): Strings. (line 1404) -* '\t' (tab): Strings. (line 1407) -* '\XD...' (hex character code): Strings. (line 1416) -* '\\' ('\' character): Strings. (line 1420) -* a.out: Object. (line 827) -* 'abort' directive: Abort. (line 2114) -* absolute section: Ld Sections. (line 1632) -* addition, permitted arguments: Infix Ops. (line 2055) -* addresses: Expressions. (line 1946) -* addresses, format of: Secs Background. (line 1573) -* 'ADR reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4159) -* 'ADRL reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4169) -* advancing location counter: Org. (line 3101) -* 'align' directive: Align. (line 2123) -* 'align' directive, ARM: ARM Directives. (line 3915) -* 'align' directive, SPARC: Sparc-Directives. (line 5481) -* arch directive, i386: i386-Arch. (line 4670) -* arch directive, x86-64: i386-Arch. (line 4670) -* architectures, PowerPC: PowerPC-Opts. (line 5285) -* architectures, SPARC: Sparc-Opts. (line 5402) -* arguments for addition: Infix Ops. (line 2055) -* arguments for subtraction: Infix Ops. (line 2060) -* arguments in expressions: Arguments. (line 1973) -* arithmetic functions: Operators. (line 1998) -* arithmetic operands: Arguments. (line 1973) -* ARM data relocations: ARM-Relocations. (line 3886) -* 'arm' directive, ARM: ARM Directives. (line 3969) -* ARM floating point (IEEE): ARM Floating Point. (line 3910) -* ARM identifiers: ARM-Chars. (line 3876) -* ARM immediate character: ARM-Chars. (line 3874) -* ARM line comment character: ARM-Chars. (line 3867) -* ARM line separator: ARM-Chars. (line 3871) -* ARM machine directives: ARM Directives. (line 3915) -* ARM opcodes: ARM Opcodes. (line 4140) -* ARM options (none): ARM Options. (line 3742) -* ARM register names: ARM-Regs. (line 3881) -* ARM support: Machine Dependencies. - (line 3739) -* 'ascii' directive: Ascii. (line 2165) -* 'asciz' directive: Asciz. (line 2172) -* assembler bugs, reporting: Bug Reporting. (line 5566) -* assembler crash: Bug Criteria. (line 5550) -* assembler internal logic error: As Sections. (line 1674) -* assembler version: v. (line 1206) -* assembler, and linker: Secs Background. (line 1535) -* assembly listings, enabling: a. (line 894) -* assigning values to symbols: Setting Symbols. (line 1772) -* assigning values to symbols <1>: Equ. (line 2471) -* attributes, symbol: Symbol Attributes. (line 1907) -* att_syntax pseudo op, i386: i386-Syntax. (line 4265) -* att_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* Av7: Sparc-Opts. (line 5421) -* backslash ('\\'): Strings. (line 1420) -* backspace ('\b'): Strings. (line 1395) -* 'balign' directive: Balign. (line 2178) -* 'balignl' directive: Balign. (line 2199) -* 'balignw' directive: Balign. (line 2199) -* big endian output, MIPS: Overview. (line 560) -* big-endian output, MIPS: MIPS Opts. (line 4879) -* bignums: Bignums. (line 1485) -* binary files, including: Incbin. (line 2707) -* binary integers: Integers. (line 1466) -* bit names, IA-64: IA-64-Bits. (line 4846) -* bss section: Ld Sections. (line 1623) -* bss section <1>: bss. (line 1739) -* bug criteria: Bug Criteria. (line 5547) -* bug reports: Bug Reporting. (line 5566) -* bugs in assembler: Reporting Bugs. (line 5534) -* bus lock prefixes, i386: i386-Prefixes. (line 4444) -* 'byte' directive: Byte. (line 2211) -* call instructions, i386: i386-Mnemonics. (line 4353) -* call instructions, x86-64: i386-Mnemonics. (line 4353) -* carriage return ('\r'): Strings. (line 1404) -* 'cfi_endproc' directive: CFI directives. (line 2249) -* 'cfi_startproc' directive: CFI directives. (line 2239) -* character constants: Characters. (line 1377) -* character escape codes: Strings. (line 1395) -* character, single: Chars. (line 1443) -* characters used in symbols: Symbol Intro. (line 1325) -* 'code' directive, ARM: ARM Directives. (line 3962) -* 'code16' directive, i386: i386-16bit. (line 4615) -* 'code16gcc' directive, i386: i386-16bit. (line 4615) -* 'code32' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, x86-64: i386-16bit. (line 4615) -* COMDAT: Linkonce. (line 2831) -* 'comm' directive: Comm. (line 2217) -* command line conventions: Command Line. (line 756) -* comments: Comments. (line 1288) -* comments, removed by preprocessor: Preprocessing. (line 1253) -* 'common' directive, SPARC: Sparc-Directives. (line 5484) -* common sections: Linkonce. (line 2831) -* common variable storage: bss. (line 1739) -* comparison expressions: Infix Ops. (line 2066) -* conditional assembly: If. (line 2629) -* constant, single character: Chars. (line 1443) -* constants: Constants. (line 1366) -* constants, bignum: Bignums. (line 1485) -* constants, character: Characters. (line 1377) -* constants, converted by preprocessor: Preprocessing. (line 1256) -* constants, floating point: Flonums. (line 1493) -* constants, integer: Integers. (line 1466) -* constants, number: Numbers. (line 1457) -* constants, string: Strings. (line 1386) -* conversion instructions, i386: i386-Mnemonics. (line 4334) -* conversion instructions, x86-64: i386-Mnemonics. (line 4334) -* coprocessor wait, i386: i386-Prefixes. (line 4448) -* crash of assembler: Bug Criteria. (line 5550) -* current address: Dot. (line 1898) -* current address, advancing: Org. (line 3101) -* data alignment on SPARC: Sparc-Aligned-Data. (line 5455) -* data and text sections, joining: R. (line 1170) -* 'data' directive: Data. (line 2421) -* data relocations, ARM: ARM-Relocations. (line 3886) -* debuggers, and symbol order: Symbols. (line 1757) -* decimal integers: Integers. (line 1472) -* dependency tracking: MD. (line 1149) -* deprecated directives: Deprecated. (line 3731) -* directives and instructions: Statements. (line 1347) -* directives for PowerPC: PowerPC-Pseudo. (line 5386) -* directives, machine independent: Pseudo Ops. (line 2105) -* 'dn' and 'qn' directives, ARM: ARM Directives. (line 3938) -* dollar local symbols: Symbol Names. (line 1879) -* dot (symbol): Dot. (line 1898) -* 'double' directive: Double. (line 2428) -* 'double' directive, i386: i386-Float. (line 4569) -* 'double' directive, x86-64: i386-Float. (line 4569) -* doublequote ('\"'): Strings. (line 1423) -* ECOFF sections: MIPS Object. (line 5100) -* eight-byte integer: Quad. (line 3245) -* 'eject' directive: Eject. (line 2434) -* ELF symbol type: Type. (line 3620) -* 'else' directive: Else. (line 2439) -* 'elseif' directive: Elseif. (line 2446) -* empty expressions: Empty Exprs. (line 1959) -* emulation: Overview. (line 663) -* 'end' directive: End. (line 2453) -* 'endfunc' directive: Endfunc. (line 2459) -* endianness, MIPS: Overview. (line 560) -* 'endif' directive: Endif. (line 2464) -* 'endm' directive: Macro. (line 3025) -* EOF, newline must precede: Statements. (line 1341) -* 'equ' directive: Equ. (line 2471) -* 'equiv' directive: Equiv. (line 2477) -* 'eqv' directive: Eqv. (line 2493) -* 'err' directive: Err. (line 2501) -* error directive: Error. (line 2509) -* error messages: Errors. (line 844) -* error on valid input: Bug Criteria. (line 5553) -* errors, caused by warnings: W. (line 1222) -* errors, continuing after: Z. (line 1231) -* escape codes, character: Strings. (line 1395) -* 'exitm' directive: Macro. (line 3028) -* expr (internal section): As Sections. (line 1678) -* expression arguments: Arguments. (line 1973) -* expressions: Expressions. (line 1946) -* expressions, comparison: Infix Ops. (line 2066) -* expressions, empty: Empty Exprs. (line 1959) -* expressions, integer: Integer Exprs. (line 1967) -* 'extern' directive: Extern. (line 2524) -* 'fail' directive: Fail. (line 2531) -* faster processing ('-f'): f. (line 940) -* fatal signal: Bug Criteria. (line 5550) -* 'file' directive: LNS directives. (line 2369) -* 'file' directive <1>: File. (line 2540) -* file name, logical: File. (line 2540) -* files, including: Include. (line 2721) -* files, input: Input Files. (line 780) -* 'fill' directive: Fill. (line 2550) -* filling memory: Skip. (line 3452) -* filling memory <1>: Space. (line 3459) -* 'float' directive: Float. (line 2568) -* 'float' directive, i386: i386-Float. (line 4569) -* 'float' directive, x86-64: i386-Float. (line 4569) -* floating point numbers: Flonums. (line 1493) -* floating point numbers (double): Double. (line 2428) -* floating point numbers (single): Float. (line 2568) -* floating point numbers (single) <1>: Single. (line 3425) -* floating point, ARM (IEEE): ARM Floating Point. (line 3910) -* floating point, i386: i386-Float. (line 4561) -* floating point, SPARC (IEEE): Sparc-Float. (line 5473) -* floating point, x86-64: i386-Float. (line 4561) -* flonums: Flonums. (line 1493) -* 'force_thumb' directive, ARM: ARM Directives. (line 3972) -* format of error messages: Errors. (line 861) -* format of warning messages: Errors. (line 850) -* formfeed ('\f'): Strings. (line 1398) -* 'func' directive: Func. (line 2574) -* functions, in expressions: Operators. (line 1998) -* 'global' directive: Global. (line 2585) -* 'gp' register, MIPS: MIPS Object. (line 5105) -* grouping data: Sub-Sections. (line 1686) -* 'half' directive, SPARC: Sparc-Directives. (line 5489) -* hex character code ('\XD...'): Strings. (line 1416) -* hexadecimal integers: Integers. (line 1475) -* 'hidden' directive: Hidden. (line 2597) -* 'hword' directive: hword. (line 2610) -* i386 16-bit code: i386-16bit. (line 4615) -* i386 arch directive: i386-Arch. (line 4670) -* i386 att_syntax pseudo op: i386-Syntax. (line 4265) -* i386 conversion instructions: i386-Mnemonics. (line 4334) -* i386 floating point: i386-Float. (line 4561) -* i386 immediate operands: i386-Syntax. (line 4274) -* i386 instruction naming: i386-Mnemonics. (line 4309) -* i386 instruction prefixes: i386-Prefixes. (line 4414) -* i386 intel_syntax pseudo op: i386-Syntax. (line 4265) -* i386 jump optimization: i386-Jumps. (line 4538) -* i386 jump, call, return: i386-Syntax. (line 4296) -* i386 jump/call operands: i386-Syntax. (line 4274) -* i386 memory references: i386-Memory. (line 4471) -* i386 'mul', 'imul' instructions: i386-Notes. (line 4714) -* i386 options: i386-Options. (line 4218) -* i386 register operands: i386-Syntax. (line 4274) -* i386 registers: i386-Regs. (line 4359) -* i386 sections: i386-Syntax. (line 4302) -* i386 size suffixes: i386-Syntax. (line 4287) -* i386 source, destination operands: i386-Syntax. (line 4280) -* i386 support: . (line 4211) -* i386 syntax compatibility: i386-Syntax. (line 4265) -* i80306 support: . (line 4211) -* IA-64 line comment character: IA-64-Chars. (line 4822) -* IA-64 line separator: IA-64-Chars. (line 4824) -* IA-64 options: IA-64 Options. (line 4733) -* IA-64 Processor-status-Register bit names: IA-64-Bits. (line 4846) -* IA-64 registers: IA-64-Regs. (line 4829) -* IA-64 support: . (line 4730) -* IA-64 Syntax: IA-64 Options. (line 4812) -* 'ident' directive: Ident. (line 2618) -* identifiers, ARM: ARM-Chars. (line 3876) -* 'if' directive: If. (line 2629) -* 'ifb' directive: If. (line 2644) -* 'ifc' directive: If. (line 2648) -* 'ifdef' directive: If. (line 2639) -* 'ifeq' directive: If. (line 2656) -* 'ifeqs' directive: If. (line 2659) -* 'ifge' directive: If. (line 2663) -* 'ifgt' directive: If. (line 2667) -* 'ifle' directive: If. (line 2671) -* 'iflt' directive: If. (line 2675) -* 'ifnb' directive: If. (line 2679) -* 'ifnc' directive: If. (line 2684) -* 'ifndef' directive: If. (line 2688) -* 'ifne' directive: If. (line 2695) -* 'ifnes' directive: If. (line 2699) -* 'ifnotdef' directive: If. (line 2688) -* immediate character, ARM: ARM-Chars. (line 3874) -* immediate operands, i386: i386-Syntax. (line 4274) -* immediate operands, x86-64: i386-Syntax. (line 4274) -* 'imul' instruction, i386: i386-Notes. (line 4714) -* 'imul' instruction, x86-64: i386-Notes. (line 4714) -* 'incbin' directive: Incbin. (line 2707) -* 'include' directive: Include. (line 2721) -* 'include' directive search path: I. (line 952) -* infix operators: Infix Ops. (line 2016) -* inhibiting interrupts, i386: i386-Prefixes. (line 4444) -* input: Input Files. (line 780) -* input file linenumbers: Input Files. (line 809) -* instruction naming, i386: i386-Mnemonics. (line 4309) -* instruction naming, x86-64: i386-Mnemonics. (line 4309) -* instruction prefixes, i386: i386-Prefixes. (line 4414) -* instructions and directives: Statements. (line 1347) -* 'int' directive: Int. (line 2732) -* 'int' directive, i386: i386-Float. (line 4576) -* 'int' directive, x86-64: i386-Float. (line 4576) -* integer expressions: Integer Exprs. (line 1967) -* integer, 16-byte: Octa. (line 3092) -* integer, 8-byte: Quad. (line 3245) -* integers: Integers. (line 1466) -* integers, 16-bit: hword. (line 2610) -* integers, 32-bit: Int. (line 2732) -* integers, binary: Integers. (line 1466) -* integers, decimal: Integers. (line 1472) -* integers, hexadecimal: Integers. (line 1475) -* integers, octal: Integers. (line 1469) -* integers, one byte: Byte. (line 2211) -* intel_syntax pseudo op, i386: i386-Syntax. (line 4265) -* intel_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* internal assembler sections: As Sections. (line 1667) -* 'internal' directive: Internal. (line 2740) -* invalid input: Bug Criteria. (line 5555) -* invocation summary: Overview. (line 249) -* 'irp' directive: Irp. (line 2754) -* 'irpc' directive: Irpc. (line 2779) -* joining text and data sections: R. (line 1170) -* jump instructions, i386: i386-Mnemonics. (line 4353) -* jump instructions, x86-64: i386-Mnemonics. (line 4353) -* jump optimization, i386: i386-Jumps. (line 4538) -* jump optimization, x86-64: i386-Jumps. (line 4538) -* jump/call operands, i386: i386-Syntax. (line 4274) -* jump/call operands, x86-64: i386-Syntax. (line 4274) -* label (':'): Statements. (line 1355) -* labels: Labels. (line 1763) -* 'lcomm' directive: Lcomm. (line 2805) -* ld: Object. (line 836) -* 'LDR reg,=<label>' pseudo op, ARM: ARM Opcodes. (line 4149) -* length of symbols: Symbol Intro. (line 1331) -* 'lflags' directive (ignored): Lflags. (line 2814) -* line comment character: Comments. (line 1301) -* line comment character, ARM: ARM-Chars. (line 3867) -* line comment character, IA-64: IA-64-Chars. (line 4822) -* 'line' directive: Line. (line 2820) -* line numbers, in input files: Input Files. (line 809) -* line numbers, in warnings/errors: Errors. (line 854) -* line separator character: Statements. (line 1336) -* line separator, ARM: ARM-Chars. (line 3871) -* line separator, IA-64: IA-64-Chars. (line 4824) -* lines starting with '#': Comments. (line 1306) -* linker: Object. (line 836) -* linker, and assembler: Secs Background. (line 1535) -* 'linkonce' directive: Linkonce. (line 2831) -* 'list' directive: List. (line 2876) -* listing control, turning off: Nolist. (line 3083) -* listing control, turning on: List. (line 2876) -* listing control: new page: Eject. (line 2434) -* listing control: paper size: Psize. (line 3208) -* listing control: subtitle: Sbttl. (line 3284) -* listing control: title line: Title. (line 3609) -* listings, enabling: a. (line 894) -* little endian output, MIPS: Overview. (line 563) -* little-endian output, MIPS: MIPS Opts. (line 4879) -* 'ln' directive: Ln. (line 2863) -* 'loc' directive: LNS directives. (line 2382) -* local common symbols: Lcomm. (line 2805) -* local labels: Symbol Names. (line 1810) -* local symbol names: Symbol Names. (line 1797) -* local symbols, retaining in output: L. (line 972) -* location counter: Dot. (line 1898) -* location counter, advancing: Org. (line 3101) -* 'loc_mark_blocks' directive: LNS directives. (line 2412) -* logical file name: File. (line 2540) -* logical line number: Line. (line 2820) -* logical line numbers: Comments. (line 1306) -* 'long' directive: Long. (line 2889) -* 'long' directive, i386: i386-Float. (line 4576) -* 'long' directive, x86-64: i386-Float. (line 4576) -* machine directives, ARM: ARM Directives. (line 3915) -* machine directives, SPARC: Sparc-Directives. (line 5478) -* machine independent directives: Pseudo Ops. (line 2105) -* machine instructions (not covered): Manual. (line 716) -* machine-independent syntax: Syntax. (line 1241) -* 'macro' directive: Macro. (line 2916) -* macros: Macro. (line 2894) -* macros, count executed: Macro. (line 3030) -* make rules: MD. (line 1149) -* manual, structure and purpose: Manual. (line 708) -* Maximum number of continuation lines: listing. (line 1015) -* memory references, i386: i386-Memory. (line 4471) -* memory references, x86-64: i386-Memory. (line 4471) -* merging text and data sections: R. (line 1170) -* messages from assembler: Errors. (line 844) -* minus, permitted arguments: Infix Ops. (line 2060) -* MIPS architecture options: MIPS Opts. (line 4895) -* MIPS big-endian output: MIPS Opts. (line 4879) -* MIPS CPU override: MIPS ISA. (line 5195) -* MIPS debugging directives: MIPS Stabs. (line 5128) -* MIPS DSP Release 1 instruction generation override: MIPS ASE instruction generation overrides. - (line 5262) -* MIPS DSP Release 2 instruction generation override: MIPS ASE instruction generation overrides. - (line 5267) -* MIPS ECOFF sections: MIPS Object. (line 5100) -* MIPS endianness: Overview. (line 560) -* MIPS ISA: Overview. (line 566) -* MIPS ISA override: MIPS ISA. (line 5183) -* MIPS little-endian output: MIPS Opts. (line 4879) -* MIPS MDMX instruction generation override: MIPS ASE instruction generation overrides. - (line 5257) -* MIPS MIPS-3D instruction generation override: MIPS ASE instruction generation overrides. - (line 5247) -* MIPS MT instruction generation override: MIPS ASE instruction generation overrides. - (line 5272) -* MIPS option stack: MIPS option stack. (line 5232) -* MIPS processor: . (line 4862) -* MMX, i386: i386-SIMD. (line 4593) -* MMX, x86-64: i386-SIMD. (line 4593) -* mnemonic suffixes, i386: i386-Syntax. (line 4287) -* mnemonic suffixes, x86-64: i386-Syntax. (line 4287) -* MOVW and MOVT relocations, ARM: ARM-Relocations. (line 3900) -* MRI compatibility mode: M. (line 1022) -* 'mri' directive: MRI. (line 2868) -* MRI mode, temporarily: MRI. (line 2868) -* 'mul' instruction, i386: i386-Notes. (line 4714) -* 'mul' instruction, x86-64: i386-Notes. (line 4714) -* named section: Section. (line 3293) -* named sections: Ld Sections. (line 1613) -* names, symbol: Symbol Names. (line 1781) -* naming object file: o. (line 1160) -* new page, in listings: Eject. (line 2434) -* newline ('\n'): Strings. (line 1401) -* newline, required at file end: Statements. (line 1341) -* 'nolist' directive: Nolist. (line 3083) -* 'NOP' pseudo op, ARM: ARM Opcodes. (line 4143) -* null-terminated strings: Asciz. (line 2172) -* number constants: Numbers. (line 1457) -* number of macros executed: Macro. (line 3030) -* numbered subsections: Sub-Sections. (line 1686) -* numbers, 16-bit: hword. (line 2610) -* numeric values: Expressions. (line 1946) -* 'nword' directive, SPARC: Sparc-Directives. (line 5492) -* object file: Object. (line 827) -* object file format: Object Formats. (line 746) -* object file name: o. (line 1160) -* object file, after errors: Z. (line 1231) -* obsolescent directives: Deprecated. (line 3731) -* 'octa' directive: Octa. (line 3092) -* octal character code ('\DDD'): Strings. (line 1410) -* octal integers: Integers. (line 1469) -* opcodes for ARM: ARM Opcodes. (line 4140) -* operand delimiters, i386: i386-Syntax. (line 4274) -* operand delimiters, x86-64: i386-Syntax. (line 4274) -* operands in expressions: Arguments. (line 1973) -* operator precedence: Infix Ops. (line 2021) -* operators, in expressions: Operators. (line 1998) -* operators, permitted arguments: Infix Ops. (line 2016) -* option summary: Overview. (line 249) -* options for ARM (none): ARM Options. (line 3742) -* options for i386: i386-Options. (line 4218) -* options for IA-64: IA-64 Options. (line 4733) -* options for PowerPC: PowerPC-Opts. (line 5285) -* options for SPARC: Sparc-Opts. (line 5402) -* options for x86-64: i386-Options. (line 4218) -* options, all versions of assembler: Invoking. (line 870) -* options, command line: Command Line. (line 763) -* 'org' directive: Org. (line 3101) -* output file: Object. (line 827) -* 'p2align' directive: P2align. (line 3127) -* 'p2alignl' directive: P2align. (line 3149) -* 'p2alignw' directive: P2align. (line 3149) -* padding the location counter: Align. (line 2123) -* padding the location counter given a power of two: P2align. - (line 3127) -* padding the location counter given number of bytes: Balign. - (line 2178) -* page, in listings: Eject. (line 2434) -* paper size, for listings: Psize. (line 3208) -* paths for '.include': I. (line 952) -* patterns, writing in memory: Fill. (line 2550) -* PIC code generation for ARM: ARM Options. (line 3857) -* PIC selection, MIPS: MIPS Opts. (line 4887) -* plus, permitted arguments: Infix Ops. (line 2055) -* 'popsection' directive: PopSection. (line 3177) -* PowerPC architectures: PowerPC-Opts. (line 5285) -* PowerPC directives: PowerPC-Pseudo. (line 5386) -* PowerPC options: PowerPC-Opts. (line 5285) -* PowerPC support: . (line 5282) -* precedence of operators: Infix Ops. (line 2021) -* precision, floating point: Flonums. (line 1493) -* prefix operators: Prefix Ops. (line 2005) -* prefixes, i386: i386-Prefixes. (line 4414) -* preprocessing: Preprocessing. (line 1248) -* preprocessing, turning on and off: Preprocessing. (line 1268) -* 'previous' directive: Previous. (line 3161) -* 'print' directive: Print. (line 3189) -* 'proc' directive, SPARC: Sparc-Directives. (line 5497) -* 'protected' directive: Protected. (line 3195) -* pseudo-ops, machine independent: Pseudo Ops. (line 2105) -* 'psize' directive: Psize. (line 3208) -* PSR bits: IA-64-Bits. (line 4846) -* 'purgem' directive: Purgem. (line 3224) -* purpose of GNU assembler: GNU Assembler. (line 734) -* 'pushsection' directive: PushSection. (line 3230) -* 'quad' directive: Quad. (line 3242) -* 'quad' directive, i386: i386-Float. (line 4576) -* 'quad' directive, x86-64: i386-Float. (line 4576) -* real-mode code, i386: i386-16bit. (line 4615) -* 'register' directive, SPARC: Sparc-Directives. (line 5501) -* register names, ARM: ARM-Regs. (line 3881) -* register names, IA-64: IA-64-Regs. (line 4829) -* register operands, i386: i386-Syntax. (line 4274) -* register operands, x86-64: i386-Syntax. (line 4274) -* registers, i386: i386-Regs. (line 4359) -* registers, x86-64: i386-Regs. (line 4359) -* 'reloc' directive: Reloc. (line 3253) -* relocation: Sections. (line 1528) -* relocation example: Ld Sections. (line 1643) -* repeat prefixes, i386: i386-Prefixes. (line 4452) -* reporting bugs in assembler: Reporting Bugs. (line 5534) -* 'rept' directive: Rept. (line 3266) -* 'req' directive, ARM: ARM Directives. (line 3922) -* 'reserve' directive, SPARC: Sparc-Directives. (line 5511) -* return instructions, i386: i386-Syntax. (line 4296) -* return instructions, x86-64: i386-Syntax. (line 4296) -* REX prefixes, i386: i386-Prefixes. (line 4454) -* 'sbttl' directive: Sbttl. (line 3284) -* search path for '.include': I. (line 952) -* 'section' directive (ELF version): Section. (line 3305) -* section override prefixes, i386: i386-Prefixes. (line 4431) -* Section Stack: Previous. (line 3161) -* Section Stack <1>: PopSection. (line 3177) -* Section Stack <2>: PushSection. (line 3230) -* Section Stack <3>: Section. (line 3300) -* Section Stack <4>: SubSection. (line 3545) -* section-relative addressing: Secs Background. (line 1573) -* sections: Sections. (line 1528) -* sections in messages, internal: As Sections. (line 1667) -* sections, i386: i386-Syntax. (line 4302) -* sections, named: Ld Sections. (line 1613) -* sections, x86-64: i386-Syntax. (line 4302) -* 'seg' directive, SPARC: Sparc-Directives. (line 5516) -* 'set' directive: Set. (line 3407) -* 'short' directive: Short. (line 3419) -* SIMD, i386: i386-SIMD. (line 4593) -* SIMD, x86-64: i386-SIMD. (line 4593) -* single character constant: Chars. (line 1443) -* 'single' directive: Single. (line 3425) -* 'single' directive, i386: i386-Float. (line 4569) -* 'single' directive, x86-64: i386-Float. (line 4569) -* sixteen bit integers: hword. (line 2610) -* sixteen byte integer: Octa. (line 3092) -* 'size' directive (ELF version): Size. (line 3433) -* size prefixes, i386: i386-Prefixes. (line 4435) -* sizes operands, i386: i386-Syntax. (line 4287) -* sizes operands, x86-64: i386-Syntax. (line 4287) -* 'skip' directive: Skip. (line 3452) -* 'skip' directive, SPARC: Sparc-Directives. (line 5520) -* 'sleb128' directive: Sleb128. (line 3445) -* small objects, MIPS ECOFF: MIPS Object. (line 5105) -* SmartMIPS instruction generation override: MIPS ASE instruction generation overrides. - (line 5252) -* source program: Input Files. (line 780) -* source, destination operands; i386: i386-Syntax. (line 4280) -* source, destination operands; x86-64: i386-Syntax. (line 4280) -* 'space' directive: Space. (line 3459) -* space used, maximum for assembly: statistics. (line 1188) -* SPARC architectures: Sparc-Opts. (line 5402) -* SPARC data alignment: Sparc-Aligned-Data. (line 5455) -* SPARC floating point (IEEE): Sparc-Float. (line 5473) -* SPARC machine directives: Sparc-Directives. (line 5478) -* SPARC options: Sparc-Opts. (line 5402) -* SPARC support: . (line 5399) -* 'stabd' directive: Stab. (line 3498) -* 'stabn' directive: Stab. (line 3509) -* 'stabs' directive: Stab. (line 3512) -* 'stabX' directives: Stab. (line 3466) -* standard assembler sections: Secs Background. (line 1550) -* standard input, as input file: Command Line. (line 760) -* statement separator character: Statements. (line 1336) -* statement separator, ARM: ARM-Chars. (line 3871) -* statement separator, IA-64: IA-64-Chars. (line 4824) -* statements, structure of: Statements. (line 1336) -* statistics, about assembly: statistics. (line 1188) -* stopping the assembly: Abort. (line 2114) -* string constants: Strings. (line 1386) -* 'string' directive: String. (line 3518) -* string literals: Ascii. (line 2165) -* string, copying to object file: String. (line 3518) -* 'struct' directive: Struct. (line 3527) -* subexpressions: Arguments. (line 1991) -* 'subsection' directive: SubSection. (line 3545) -* subtitles for listings: Sbttl. (line 3284) -* subtraction, permitted arguments: Infix Ops. (line 2060) -* summary of options: Overview. (line 249) -* supporting files, including: Include. (line 2721) -* suppressing warnings: W. (line 1217) -* symbol attributes: Symbol Attributes. (line 1907) -* symbol names: Symbol Names. (line 1781) -* symbol names, local: Symbol Names. (line 1797) -* symbol names, temporary: Symbol Names. (line 1810) -* symbol type: Symbol Type. (line 1938) -* symbol type, ELF: Type. (line 3620) -* symbol value: Symbol Value. (line 1918) -* symbol value, setting: Set. (line 3407) -* symbol values, assigning: Setting Symbols. (line 1772) -* symbol versioning: Symver. (line 3557) -* symbol, common: Comm. (line 2217) -* symbol, making visible to linker: Global. (line 2585) -* symbolic debuggers, information for: Stab. (line 3466) -* symbols: Symbols. (line 1753) -* symbols, assigning values to: Equ. (line 2471) -* symbols, local common: Lcomm. (line 2805) -* 'symver' directive: Symver. (line 3557) -* syntax compatibility, i386: i386-Syntax. (line 4265) -* syntax compatibility, x86-64: i386-Syntax. (line 4265) -* syntax, machine-independent: Syntax. (line 1241) -* tab ('\t'): Strings. (line 1407) -* temporary symbol names: Symbol Names. (line 1810) -* text and data sections, joining: R. (line 1170) -* 'text' directive: Text. (line 3602) -* 'tfloat' directive, i386: i386-Float. (line 4569) -* 'tfloat' directive, x86-64: i386-Float. (line 4569) -* 'thumb' directive, ARM: ARM Directives. (line 3966) -* Thumb support: Machine Dependencies. - (line 3739) -* 'thumb_func' directive, ARM: ARM Directives. (line 3976) -* 'thumb_set' directive, ARM: ARM Directives. (line 3987) -* time, total for assembly: statistics. (line 1188) -* 'title' directive: Title. (line 3609) -* trusted compiler: f. (line 940) -* turning preprocessing on and off: Preprocessing. (line 1268) -* 'type' directive (ELF version): Type. (line 3620) -* type of a symbol: Symbol Type. (line 1938) -* 'uleb128' directive: Uleb128. (line 3656) -* undefined section: Ld Sections. (line 1639) -* 'unreq' directive, ARM: ARM Directives. (line 3927) -* value of a symbol: Symbol Value. (line 1918) -* 'version' directive: Version. (line 3663) -* version of assembler: v. (line 1206) -* versions of symbols: Symver. (line 3557) -* visibility: Hidden. (line 2597) -* visibility <1>: Internal. (line 2740) -* visibility <2>: Protected. (line 3195) -* 'vtable_entry' directive: VTableEntry. (line 3669) -* 'vtable_inherit' directive: VTableInherit. (line 3675) -* warning directive: Warning. (line 3683) -* warning messages: Errors. (line 844) -* warnings, causing error: W. (line 1222) -* warnings, suppressing: W. (line 1217) -* warnings, switching on: W. (line 1225) -* 'weak' directive: Weak. (line 3689) -* 'weakref' directive: Weakref. (line 3705) -* whitespace: Whitespace. (line 1280) -* whitespace, removed by preprocessor: Preprocessing. (line 1249) -* Width of continuation lines of disassembly output: listing. - (line 1002) -* Width of first line disassembly output: listing. (line 997) -* Width of source line output: listing. (line 1009) -* 'word' directive: Word. (line 3725) -* 'word' directive, i386: i386-Float. (line 4576) -* 'word' directive, SPARC: Sparc-Directives. (line 5523) -* 'word' directive, x86-64: i386-Float. (line 4576) -* writing patterns in memory: Fill. (line 2550) -* x86-64 arch directive: i386-Arch. (line 4670) -* x86-64 att_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 conversion instructions: i386-Mnemonics. (line 4334) -* x86-64 floating point: i386-Float. (line 4561) -* x86-64 immediate operands: i386-Syntax. (line 4274) -* x86-64 instruction naming: i386-Mnemonics. (line 4309) -* x86-64 intel_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 jump optimization: i386-Jumps. (line 4538) -* x86-64 jump, call, return: i386-Syntax. (line 4296) -* x86-64 jump/call operands: i386-Syntax. (line 4274) -* x86-64 memory references: i386-Memory. (line 4471) -* x86-64 options: i386-Options. (line 4218) -* x86-64 register operands: i386-Syntax. (line 4274) -* x86-64 registers: i386-Regs. (line 4359) -* x86-64 sections: i386-Syntax. (line 4302) -* x86-64 size suffixes: i386-Syntax. (line 4287) -* x86-64 source, destination operands: i386-Syntax. (line 4280) -* x86-64 support: . (line 4211) -* x86-64 syntax compatibility: i386-Syntax. (line 4265) -* 'xword' directive, SPARC: Sparc-Directives. (line 5527) -* zero-terminated strings: Asciz. (line 2172) - -START-INFO-DIR-ENTRY -* As: (as). The GNU assembler. -* Gas: (as). The GNU assembler. -END-INFO-DIR-ENTRY - -Using as -1 Overview - 1.1 Structure of this Manual - 1.2 The GNU Assembler - 1.3 Object File Formats - 1.4 Command Line - 1.5 Input Files - 1.6 Output (Object) File - 1.7 Error and Warning Messages -2 Command-Line Options - 2.1 Enable Listings: '-a[cdhlns]' - 2.2 '--alternate' - 2.3 '-D' - 2.4 Work Faster: '-f' - 2.5 '.include' Search Path: '-I' PATH - 2.6 Difference Tables: '-K' - 2.7 Include Local Symbols: '-L' - 2.8 Configuring listing output: '--listing' - 2.9 Assemble in MRI Compatibility Mode: '-M' - 2.10 Dependency Tracking: '--MD' - 2.11 Name the Object File: '-o' - 2.12 Join Data and Text Sections: '-R' - 2.13 Display Assembly Statistics: '--statistics' - 2.14 Compatible Output: '--traditional-format' - 2.15 Announce Version: '-v' - 2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' - 2.17 Generate Object File in Spite of Errors: '-Z' -3 Syntax - 3.1 Preprocessing - 3.2 Whitespace - 3.3 Comments - 3.4 Symbols - 3.5 Statements - 3.6 Constants - 3.6.1 Character Constants - 3.6.1.1 Strings - 3.6.1.2 Characters - 3.6.2 Number Constants - 3.6.2.1 Integers - 3.6.2.2 Bignums - 3.6.2.3 Flonums -4 Sections and Relocation - 4.1 Background - 4.2 Linker Sections - 4.3 Assembler Internal Sections - 4.4 Sub-Sections - 4.5 bss Section -5 Symbols - 5.1 Labels - 5.2 Giving Symbols Other Values - 5.3 Symbol Names - 5.4 The Special Dot Symbol - 5.5 Symbol Attributes - 5.5.1 Value - 5.5.2 Type -6 Expressions - 6.1 Empty Expressions - 6.2 Integer Expressions - 6.2.1 Arguments - 6.2.2 Operators - 6.2.3 Prefix Operator - 6.2.4 Infix Operators -7 Assembler Directives - 7.1 '.abort' - 7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.3 '.ascii "STRING"'... - 7.4 '.asciz "STRING"'... - 7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.6 '.byte EXPRESSIONS' - 7.7 '.comm SYMBOL , LENGTH ' - 7.8 '.cfi_startproc [simple]' - 7.9 '.cfi_endproc' - 7.10 '.cfi_personality ENCODING [, EXP]' - 7.11 '.cfi_lsda ENCODING [, EXP]' - 7.12 '.cfi_def_cfa REGISTER, OFFSET' - 7.13 '.cfi_def_cfa_register REGISTER' - 7.14 '.cfi_def_cfa_offset OFFSET' - 7.15 '.cfi_adjust_cfa_offset OFFSET' - 7.16 '.cfi_offset REGISTER, OFFSET' - 7.17 '.cfi_rel_offset REGISTER, OFFSET' - 7.18 '.cfi_register REGISTER1, REGISTER2' - 7.19 '.cfi_restore REGISTER' - 7.20 '.cfi_undefined REGISTER' - 7.21 '.cfi_same_value REGISTER' - 7.22 '.cfi_remember_state', - 7.23 '.cfi_return_column REGISTER' - 7.24 '.cfi_signal_frame' - 7.25 '.cfi_window_save' - 7.26 '.cfi_escape' EXPRESSION[, ...] - 7.27 '.file FILENO FILENAME' - 7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' - 7.29 '.loc_mark_blocks ENABLE' - 7.30 '.data SUBSECTION' - 7.31 '.double FLONUMS' - 7.32 '.eject' - 7.33 '.else' - 7.34 '.elseif' - 7.35 '.end' - 7.36 '.endfunc' - 7.37 '.endif' - 7.38 '.equ SYMBOL, EXPRESSION' - 7.39 '.equiv SYMBOL, EXPRESSION' - 7.40 '.eqv SYMBOL, EXPRESSION' - 7.41 '.err' - 7.42 '.error "STRING"' - 7.43 '.exitm' - 7.44 '.extern' - 7.45 '.fail EXPRESSION' - 7.46 '.file STRING' - 7.47 '.fill REPEAT , SIZE , VALUE' - 7.48 '.float FLONUMS' - 7.49 '.func NAME[,LABEL]' - 7.50 '.global SYMBOL', '.globl SYMBOL' - 7.51 '.hidden NAMES' - 7.52 '.hword EXPRESSIONS' - 7.53 '.ident' - 7.54 '.if ABSOLUTE EXPRESSION' - 7.55 '.incbin "FILE"[,SKIP[,COUNT]]' - 7.56 '.include "FILE"' - 7.57 '.int EXPRESSIONS' - 7.58 '.internal NAMES' - 7.59 '.irp SYMBOL,VALUES'... - 7.60 '.irpc SYMBOL,VALUES'... - 7.61 '.lcomm SYMBOL , LENGTH' - 7.62 '.lflags' - 7.63 '.line LINE-NUMBER' - 7.64 '.linkonce [TYPE]' - 7.65 '.ln LINE-NUMBER' - 7.66 '.mri VAL' - 7.67 '.list' - 7.68 '.long EXPRESSIONS' - 7.69 '.macro' - 7.70 '.altmacro' - 7.71 '.noaltmacro' - 7.72 '.nolist' - 7.73 '.octa BIGNUMS' - 7.74 '.org NEW-LC , FILL' - 7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.76 '.previous' - 7.77 '.popsection' - 7.78 '.print STRING' - 7.79 '.protected NAMES' - 7.80 '.psize LINES , COLUMNS' - 7.81 '.purgem NAME' - 7.82 '.pushsection NAME , SUBSECTION' - 7.83 '.quad BIGNUMS' - 7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' - 7.85 '.rept COUNT' - 7.86 '.sbttl "SUBHEADING"' - 7.87 '.section NAME' - 7.88 '.set SYMBOL, EXPRESSION' - 7.89 '.short EXPRESSIONS' - 7.90 '.single FLONUMS' - 7.91 '.size' - 7.92 '.sleb128 EXPRESSIONS' - 7.93 '.skip SIZE , FILL' - 7.94 '.space SIZE , FILL' - 7.95 '.stabd, .stabn, .stabs' - 7.96 '.string' "STR" - 7.97 '.struct EXPRESSION' - 7.98 '.subsection NAME' - 7.99 '.symver' - 7.100 '.text SUBSECTION' - 7.101 '.title "HEADING"' - 7.102 '.type' - 7.103 '.uleb128 EXPRESSIONS' - 7.104 '.version "STRING"' - 7.105 '.vtable_entry TABLE, OFFSET' - 7.106 '.vtable_inherit CHILD, PARENT' - 7.107 '.warning "STRING"' - 7.108 '.weak NAMES' - 7.109 '.weakref ALIAS, TARGET' - 7.110 '.word EXPRESSIONS' - 7.111 Deprecated Directives -8 ARM Dependent Features - 8.1 Options - 8.2 Syntax - 8.2.1 Special Characters - 8.2.2 Register Names - 8.2.3 ARM relocation generation - 8.3 Floating Point - 8.4 ARM Machine Directives - 8.5 Opcodes - 8.6 Mapping Symbols -9 80386 Dependent Features - 9.1 Options - 9.2 AT&T Syntax versus Intel Syntax - 9.3 Instruction Naming - 9.4 Register Naming - 9.5 Instruction Prefixes - 9.6 Memory References - 9.7 Handling of Jump Instructions - 9.8 Floating Point - 9.9 Intel's MMX and AMD's 3DNow! SIMD Operations - 9.10 Writing 16-bit Code - 9.11 AT&T Syntax bugs - 9.12 Specifying CPU Architecture - 9.13 Notes -10 IA-64 Dependent Features - 10.1 Options - 10.2 Syntax - 10.2.1 Special Characters - 10.2.2 Register Names - 10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names - 10.3 Opcodes -11 MIPS Dependent Features - 11.1 Assembler options - 11.2 MIPS ECOFF object code - 11.3 Directives for debugging information - 11.4 Directives to override the size of symbols - 11.5 Directives to override the ISA level - 11.6 Directives for extending MIPS 16 bit instructions - 11.7 Directive to mark data as an instruction - 11.8 Directives to save and restore options - 11.9 Directives to control generation of MIPS ASE instructions -12 PowerPC Dependent Features - 12.1 Options - 12.2 PowerPC Assembler Directives -13 SPARC Dependent Features - 13.1 Options - 13.2 Enforcing aligned data - 13.3 Floating Point - 13.4 Sparc Machine Directives -14 Reporting Bugs - 14.1 Have You Found a Bug? - 14.2 How to Report Bugs -15 Acknowledgements -Appendix A GNU Free Documentation License - ADDENDUM: How to use this License for your documents -AS Index -Using as -******** - -This file is a user guide to the GNU assembler 'as' version "2.17.50 -[FreeBSD] 2007-07-03". This version of the file describes 'as' -configured to generate code for machine specific architectures. - - This document is distributed under the terms of the GNU Free -Documentation License. A copy of the license is included in the section -entitled "GNU Free Documentation License". - -1 Overview -********** - -Here is a brief summary of how to invoke 'as'. For details, see *note -Command-Line Options: Invoking. - - as [-a[cdhlns][=FILE]] [-alternate] [-D] - [-defsym SYM=VAL] [-f] [-g] [-gstabs] - [-gstabs+] [-gdwarf-2] [-help] [-I DIR] [-J] - [-K] [-L] [-listing-lhs-width=NUM] - [-listing-lhs-width2=NUM] [-listing-rhs-width=NUM] - [-listing-cont-lines=NUM] [-keep-locals] [-o - OBJFILE] [-R] [-reduce-memory-overheads] [-statistics] - [-v] [-version] [-version] [-W] [-warn] - [-fatal-warnings] [-w] [-x] [-Z] [@FILE] - [-target-help] [TARGET-OPTIONS] - [-|FILES ...] - - _Target ARM options:_ - [-mcpu=PROCESSOR[+EXTENSION...]] - [-march=ARCHITECTURE[+EXTENSION...]] - [-mfpu=FLOATING-POINT-FORMAT] - [-mfloat-abi=ABI] - [-meabi=VER] - [-mthumb] - [-EB|-EL] - [-mapcs-32|-mapcs-26|-mapcs-float| - -mapcs-reentrant] - [-mthumb-interwork] [-k] - - _Target i386 options:_ - [-32|-64] [-n] - [-march=CPU] [-mtune=CPU] - - _Target IA-64 options:_ - [-mconstant-gp|-mauto-pic] - [-milp32|-milp64|-mlp64|-mp64] - [-mle|mbe] - [-mtune=itanium1|-mtune=itanium2] - [-munwind-check=warning|-munwind-check=error] - [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] - [-x|-xexplicit] [-xauto] [-xdebug] - - _Target MIPS options:_ - [-nocpp] [-EL] [-EB] [-O[OPTIMIZATION LEVEL]] - [-g[DEBUG LEVEL]] [-G NUM] [-KPIC] [-call_shared] - [-non_shared] [-xgot [-mvxworks-pic] - [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] - [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] - [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] - [-mips64] [-mips64r2] - [-construct-floats] [-no-construct-floats] - [-trap] [-no-break] [-break] [-no-trap] - [-mfix7000] [-mno-fix7000] - [-mips16] [-no-mips16] - [-msmartmips] [-mno-smartmips] - [-mips3d] [-no-mips3d] - [-mdmx] [-no-mdmx] - [-mdsp] [-mno-dsp] - [-mdspr2] [-mno-dspr2] - [-mmt] [-mno-mt] - [-mdebug] [-no-mdebug] - [-mpdr] [-mno-pdr] - - _Target PowerPC options:_ - [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| - -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| - -mbooke32|-mbooke64] - [-mcom|-many|-maltivec] [-memb] - [-mregnames|-mno-regnames] - [-mrelocatable|-mrelocatable-lib] - [-mlittle|-mlittle-endian|-mbig|-mbig-endian] - [-msolaris|-mno-solaris] - - _Target SPARC options:_ - [-Av6|-Av7|-Av8|-Asparclet|-Asparclite - -Av8plus|-Av8plusa|-Av9|-Av9a] - [-xarch=v8plus|-xarch=v8plusa] [-bump] - [-32|-64] - - - -'@FILE' - Read command-line options from FILE. The options read are inserted - in place of the original @FILE option. If FILE does not exist, or - cannot be read, then the option will be treated literally, and not - removed. - - Options in FILE are separated by whitespace. A whitespace - character may be included in an option by surrounding the entire - option in either single or double quotes. Any character (including - a backslash) may be included by prefixing the character to be - included with a backslash. The FILE may itself contain additional - @FILE options; any such options will be processed recursively. - -'-a[cdhlmns]' - Turn on listings, in any of a variety of ways: - - '-ac' - omit false conditionals - - '-ad' - omit debugging directives - - '-ah' - include high-level source - - '-al' - include assembly - - '-am' - include macro expansions - - '-an' - omit forms processing - - '-as' - include symbols - - '=file' - set the name of the listing file - - You may combine these options; for example, use '-aln' for assembly - listing without forms processing. The '=file' option, if used, - must be the last one. By itself, '-a' defaults to '-ahls'. - -'--alternate' - Begin in alternate macro mode. *Note '.altmacro': Altmacro. - -'-D' - Ignored. This option is accepted for script compatibility with - calls to other assemblers. - -'--defsym SYM=VALUE' - Define the symbol SYM to be VALUE before assembling the input file. - VALUE must be an integer constant. As in C, a leading '0x' - indicates a hexadecimal value, and a leading '0' indicates an octal - value. The value of the symbol can be overridden inside a source - file via the use of a '.set' pseudo-op. - -'-f' - "fast"--skip whitespace and comment preprocessing (assume source is - compiler output). - -'-g' -'--gen-debug' - Generate debugging information for each assembler source line using - whichever debug format is preferred by the target. This currently - means either STABS, ECOFF or DWARF2. - -'--gstabs' - Generate stabs debugging information for each assembler line. This - may help debugging assembler code, if the debugger can handle it. - -'--gstabs+' - Generate stabs debugging information for each assembler line, with - GNU extensions that probably only gdb can handle, and that could - make other debuggers crash or refuse to read your program. This - may help debugging assembler code. Currently the only GNU - extension is the location of the current working directory at - assembling time. - -'--gdwarf-2' - Generate DWARF2 debugging information for each assembler line. - This may help debugging assembler code, if the debugger can handle - it. Note--this option is only supported by some targets, not all - of them. - -'--help' - Print a summary of the command line options and exit. - -'--target-help' - Print a summary of all target specific options and exit. - -'-I DIR' - Add directory DIR to the search list for '.include' directives. - -'-J' - Don't warn about signed overflow. - -'-K' - This option is accepted but has no effect on the machine specific - family. - -'-L' -'--keep-locals' - Keep (in the symbol table) local symbols. These symbols start with - system-specific local label prefixes, typically '.L' for ELF - systems or 'L' for traditional a.out systems. *Note Symbol - Names::. - -'--listing-lhs-width=NUMBER' - Set the maximum width, in words, of the output data column for an - assembler listing to NUMBER. - -'--listing-lhs-width2=NUMBER' - Set the maximum width, in words, of the output data column for - continuation lines in an assembler listing to NUMBER. - -'--listing-rhs-width=NUMBER' - Set the maximum width of an input source line, as displayed in a - listing, to NUMBER bytes. - -'--listing-cont-lines=NUMBER' - Set the maximum number of lines printed in a listing for a single - line of input to NUMBER + 1. - -'-o OBJFILE' - Name the object-file output from 'as' OBJFILE. - -'-R' - Fold the data section into the text section. - - Set the default size of GAS's hash tables to a prime number close - to NUMBER. Increasing this value can reduce the length of time it - takes the assembler to perform its tasks, at the expense of - increasing the assembler's memory requirements. Similarly reducing - this value can reduce the memory requirements at the expense of - speed. - -'--reduce-memory-overheads' - This option reduces GAS's memory requirements, at the expense of - making the assembly processes slower. Currently this switch is a - synonym for '--hash-size=4051', but in the future it may have other - effects as well. - -'--statistics' - Print the maximum space (in bytes) and total time (in seconds) used - by assembly. - -'--strip-local-absolute' - Remove local absolute symbols from the outgoing symbol table. - -'-v' -'-version' - Print the 'as' version. - -'--version' - Print the 'as' version and exit. - -'-W' -'--no-warn' - Suppress warning messages. - -'--fatal-warnings' - Treat warnings as errors. - -'--warn' - Don't suppress warning messages or treat them as errors. - -'-w' - Ignored. - -'-x' - Ignored. - -'-Z' - Generate an object file even after errors. - -'-- | FILES ...' - Standard input, or source files to assemble. - - The following options are available when as is configured for the ARM -processor family. - -'-mcpu=PROCESSOR[+EXTENSION...]' - Specify which ARM processor variant is the target. -'-march=ARCHITECTURE[+EXTENSION...]' - Specify which ARM architecture variant is used by the target. -'-mfpu=FLOATING-POINT-FORMAT' - Select which Floating Point architecture is the target. -'-mfloat-abi=ABI' - Select which floating point ABI is in use. -'-mthumb' - Enable Thumb only instruction decoding. -'-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant' - Select which procedure calling convention is in use. -'-EB | -EL' - Select either big-endian (-EB) or little-endian (-EL) output. -'-mthumb-interwork' - Specify that the code has been generated with interworking between - Thumb and ARM code in mind. -'-k' - Specify that PIC code has been generated. - - The following options are available when 'as' is configured for the -SPARC architecture: - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - Explicitly select a variant of the SPARC architecture. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. '-Av9' and - '-Av9a' select a 64 bit environment. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn when the assembler switches to another architecture. - - The following options are available when as is configured for a MIPS -processor. - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format, such as a DECstation running - Ultrix. The default value is 8. - -'-EB' - Generate "big endian" format output. - -'-EL' - Generate "little endian" format output. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' is an alias for '-march=r3000', '-mips2' is an - alias for '-march=r6000', '-mips3' is an alias for '-march=r4000' - and '-mips4' is an alias for '-march=r8000'. '-mips5', '-mips32', - '-mips32r2', '-mips64', and '-mips64r2' correspond to generic 'MIPS - V', 'MIPS32', 'MIPS32 Release 2', 'MIPS64', and 'MIPS64 Release 2' - ISA processors, respectively. - -'-march=CPU' - Generate code for a particular MIPS cpu. - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. - -'-mfix7000' -'-mno-fix7000' - Cause nops to be inserted if the read of the destination register - of an mfhi or mflo instruction occurs in the following two - instructions. - -'-mdebug' -'-no-mdebug' - Cause stabs-style debugging output to go into an ECOFF-style - .mdebug section instead of the standard ELF .stabs sections. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. - -'-mgp32' -'-mfp32' - The register sizes are normally inferred from the ISA and ABI, but - these flags force a certain group of registers to be treated as 32 - bits wide at all times. '-mgp32' controls the size of - general-purpose registers and '-mfp32' controls the size of - floating-point registers. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extension to the MIPS32 instruction set. - This is equivalent to putting '.set smartmips' at the start of the - assembly file. '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-mno-dspr2' - Generate code for the DSP Release 2 Application Specific Extension. - This option implies -mdsp. This tells the assembler to accept DSP - Release 2 instructions. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'--construct-floats' -'--no-construct-floats' - The '--no-construct-floats' option disables the construction of - double width floating point constants by loading the two halves of - the value into the two single width floating point registers that - make up the double width register. By default '--construct-floats' - is selected, allowing construction of these floating point - constants. - -'--emulation=NAME' - This option causes 'as' to emulate 'as' configured for some other - target, in all respects, including output format (choosing between - ELF and ECOFF only), handling of pseudo-opcodes which may generate - debugging information or store symbol table information, and - default endianness. The available configuration names are: - 'mipsecoff', 'mipself', 'mipslecoff', 'mipsbecoff', 'mipslelf', - 'mipsbelf'. The first two do not alter the default endianness from - that of the primary target for which the assembler was configured; - the others change the default to little- or big-endian as indicated - by the 'b' or 'l' in the name. Using '-EB' or '-EL' will override - the endianness selection in any case. - - This option is currently supported only when the primary target - 'as' is configured for is a MIPS ELF or ECOFF target. Furthermore, - the primary target or others specified with '--enable-targets=...' - at configuration time must include support for the other format, if - both are to be available. For example, the Irix 5 configuration - includes support for both. - - Eventually, this option will support more configurations, with more - fine-grained control over the assembler's behavior, and will be - supported for more processors. - -'-nocpp' - 'as' ignores this option. It is accepted for compatibility with - the native tools. - -'--trap' -'--no-trap' -'--break' -'--no-break' - Control how to deal with multiplication overflow and division by - zero. '--trap' or '--no-break' (which are synonyms) take a trap - exception (and only work for Instruction Set Architecture level 2 - and higher); '--break' or '--no-trap' (also synonyms, and the - default) take a break exception. - -'-n' - When this option is used, 'as' will issue a warning every time it - generates a nop instruction from a macro. - -1.1 Structure of this Manual -============================ - -This manual is intended to describe what you need to know to use GNU -'as'. We cover the syntax expected in source files, including notation -for symbols, constants, and expressions; the directives that 'as' -understands; and of course how to invoke 'as'. - - We also cover special features in the machine specific configuration -of 'as', including assembler directives. - - On the other hand, this manual is _not_ intended as an introduction -to programming in assembly language--let alone programming in general! -In a similar vein, we make no attempt to introduce the machine -architecture; we do _not_ describe the instruction set, standard -mnemonics, registers or addressing modes that are standard to a -particular architecture. - -1.2 The GNU Assembler -===================== - -GNU 'as' is really a family of assemblers. This manual describes 'as', -a member of that family which is configured for the machine specific -architectures. If you use (or have used) the GNU assembler on one -architecture, you should find a fairly similar environment when you use -it on another architecture. Each version has much in common with the -others, including object file formats, most assembler directives (often -called "pseudo-ops") and assembler syntax. - - 'as' is primarily intended to assemble the output of the GNU C -compiler 'gcc' for use by the linker 'ld'. Nevertheless, we've tried to -make 'as' assemble correctly everything that other assemblers for the -same machine would assemble. - - Unlike older assemblers, 'as' is designed to assemble a source -program in one pass of the source file. This has a subtle impact on the -'.org' directive (*note '.org': Org.). - -1.3 Object File Formats -======================= - -The GNU assembler can be configured to produce several alternative -object file formats. For the most part, this does not affect how you -write assembly language programs; but directives for debugging symbols -are typically different in different file formats. *Note Symbol -Attributes: Symbol Attributes. For the machine specific target, 'as' is -configured to produce ELF format object files. - -1.4 Command Line -================ - -After the program name 'as', the command line may contain options and -file names. Options may appear in any order, and may be before, after, -or between file names. The order of file names is significant. - - '--' (two hyphens) by itself names the standard input file -explicitly, as one of the files for 'as' to assemble. - - Except for '--' any command line argument that begins with a hyphen -('-') is an option. Each option changes the behavior of 'as'. No -option changes the way another option works. An option is a '-' -followed by one or more letters; the case of the letter is important. -All options are optional. - - Some options expect exactly one file name to follow them. The file -name may either immediately follow the option's letter (compatible with -older assemblers) or it may be the next command argument (GNU standard). -These two command lines are equivalent: - - as -o my-object-file.o mumble.s - as -omy-object-file.o mumble.s - -1.5 Input Files -=============== - -We use the phrase "source program", abbreviated "source", to describe -the program input to one run of 'as'. The program may be in one or more -files; how the source is partitioned into files doesn't change the -meaning of the source. - - The source program is a concatenation of the text in all the files, -in the order specified. - - Each time you run 'as' it assembles exactly one source program. The -source program is made up of one or more files. (The standard input is -also a file.) - - You give 'as' a command line that has zero or more input file names. -The input files are read (from left file name to right). A command line -argument (in any position) that has no special meaning is taken to be an -input file name. - - If you give 'as' no file names it attempts to read one input file -from the 'as' standard input, which is normally your terminal. You may -have to type <ctl-D> to tell 'as' there is no more program to assemble. - - Use '--' if you need to explicitly name the standard input file in -your command line. - - If the source is empty, 'as' produces a small, empty object file. - -Filenames and Line-numbers --------------------------- - -There are two ways of locating a line in the input file (or files) and -either may be used in reporting error messages. One way refers to a -line number in a physical file; the other refers to a line number in a -"logical" file. *Note Error and Warning Messages: Errors. - - "Physical files" are those files named in the command line given to -'as'. - - "Logical files" are simply names declared explicitly by assembler -directives; they bear no relation to physical files. Logical file names -help error messages reflect the original source file, when 'as' source -is itself synthesized from other files. 'as' understands the '#' -directives emitted by the 'gcc' preprocessor. See also *note '.file': -File. - -1.6 Output (Object) File -======================== - -Every time you run 'as' it produces an output file, which is your -assembly language program translated into numbers. This file is the -object file. Its default name is 'a.out'. You can give it another name -by using the '-o' option. Conventionally, object file names end with -'.o'. The default name is used for historical reasons: older assemblers -were capable of assembling self-contained programs directly into a -runnable program. (For some formats, this isn't currently possible, but -it can be done for the 'a.out' format.) - - The object file is meant for input to the linker 'ld'. It contains -assembled program code, information to help 'ld' integrate the assembled -program into a runnable file, and (optionally) symbolic information for -the debugger. - -1.7 Error and Warning Messages -============================== - -'as' may write warnings and error messages to the standard error file -(usually your terminal). This should not happen when a compiler runs -'as' automatically. Warnings report an assumption made so that 'as' -could keep assembling a flawed program; errors report a grave problem -that stops the assembly. - - Warning messages have the format - - file_name:NNN:Warning Message Text - -(where NNN is a line number). If a logical file name has been given -(*note '.file': File.) it is used for the filename, otherwise the name -of the current input file is used. If a logical line number was given -then it is used to calculate the number printed, otherwise the actual -line in the current source file is printed. The message text is -intended to be self explanatory (in the grand Unix tradition). - - Error messages have the format - file_name:NNN:FATAL:Error Message Text - The file name and line number are derived as for warning messages. -The actual message text may be rather less explanatory because many of -them aren't supposed to happen. - -2 Command-Line Options -********************** - -This chapter describes command-line options available in _all_ versions -of the GNU assembler; see *note Machine Dependencies::, for options -specific to the machine specific target. - - If you are invoking 'as' via the GNU C compiler, you can use the -'-Wa' option to pass arguments through to the assembler. The assembler -arguments must be separated from each other (and the '-Wa') by commas. -For example: - - gcc -c -g -O -Wa,-alh,-L file.c - -This passes two options to the assembler: '-alh' (emit a listing to -standard output with high-level and assembly source) and '-L' (retain -local symbols in the symbol table). - - Usually you do not need to use this '-Wa' mechanism, since many -compiler command-line options are automatically passed to the assembler -by the compiler. (You can call the GNU compiler driver with the '-v' -option to see precisely what options it passes to each compilation pass, -including the assembler.) - -2.1 Enable Listings: '-a[cdhlns]' -================================= - -These options enable listing output from the assembler. By itself, '-a' -requests high-level, assembly, and symbols listing. You can use other -letters to select specific options for the list: '-ah' requests a -high-level language listing, '-al' requests an output-program assembly -listing, and '-as' requests a symbol table listing. High-level listings -require that a compiler debugging option like '-g' be used, and that -assembly listings ('-al') be requested also. - - Use the '-ac' option to omit false conditionals from a listing. Any -lines which are not assembled because of a false '.if' (or '.ifdef', or -any other conditional), or a true '.if' followed by an '.else', will be -omitted from the listing. - - Use the '-ad' option to omit debugging directives from the listing. - - Once you have specified one of these options, you can further control -listing output and its appearance using the directives '.list', -'.nolist', '.psize', '.eject', '.title', and '.sbttl'. The '-an' option -turns off all forms processing. If you do not request listing output -with one of the '-a' options, the listing-control directives have no -effect. - - The letters after '-a' may be combined into one option, _e.g._, -'-aln'. - - Note if the assembler source is coming from the standard input (e.g., -because it is being created by 'gcc' and the '-pipe' command line switch -is being used) then the listing will not contain any comments or -preprocessor directives. This is because the listing code buffers input -source lines from stdin only after they have been preprocessed by the -assembler. This reduces memory usage and makes the code more efficient. - -2.2 '--alternate' -================= - -Begin in alternate macro mode, see *note '.altmacro': Altmacro. - -2.3 '-D' -======== - -This option has no effect whatsoever, but it is accepted to make it more -likely that scripts written for other assemblers also work with 'as'. - -2.4 Work Faster: '-f' -===================== - -'-f' should only be used when assembling programs written by a (trusted) -compiler. '-f' stops the assembler from doing whitespace and comment -preprocessing on the input file(s) before assembling them. *Note -Preprocessing: Preprocessing. - - _Warning:_ if you use '-f' when the files actually need to be - preprocessed (if they contain comments, for example), 'as' does not - work correctly. - -2.5 '.include' Search Path: '-I' PATH -===================================== - -Use this option to add a PATH to the list of directories 'as' searches -for files specified in '.include' directives (*note '.include': -Include.). You may use '-I' as many times as necessary to include a -variety of paths. The current working directory is always searched -first; after that, 'as' searches any '-I' directories in the same order -as they were specified (left to right) on the command line. - -2.6 Difference Tables: '-K' -=========================== - -On the machine specific family, this option is allowed, but has no -effect. It is permitted for compatibility with the GNU assembler on -other platforms, where it can be used to warn when the assembler alters -the machine code generated for '.word' directives in difference tables. -The machine specific family does not have the addressing limitations -that sometimes lead to this alteration on other platforms. - -2.7 Include Local Symbols: '-L' -=============================== - -Symbols beginning with system-specific local label prefixes, typically -'.L' for ELF systems or 'L' for traditional a.out systems, are called -"local symbols". *Note Symbol Names::. Normally you do not see such -symbols when debugging, because they are intended for the use of -programs (like compilers) that compose assembler programs, not for your -notice. Normally both 'as' and 'ld' discard such symbols, so you do not -normally debug with them. - - This option tells 'as' to retain those local symbols in the object -file. Usually if you do this you also tell the linker 'ld' to preserve -those symbols. - -2.8 Configuring listing output: '--listing' -=========================================== - -The listing feature of the assembler can be enabled via the command line -switch '-a' (*note a::). This feature combines the input source file(s) -with a hex dump of the corresponding locations in the output object -file, and displays them as a listing file. The format of this listing -can be controlled by directives inside the assembler source (i.e., -'.list' (*note List::), '.title' (*note Title::), '.sbttl' (*note -Sbttl::), '.psize' (*note Psize::), and '.eject' (*note Eject::) and -also by the following switches: - -'--listing-lhs-width='number'' - Sets the maximum width, in words, of the first line of the hex byte - dump. This dump appears on the left hand side of the listing - output. - -'--listing-lhs-width2='number'' - Sets the maximum width, in words, of any further lines of the hex - byte dump for a given input source line. If this value is not - specified, it defaults to being the same as the value specified for - '--listing-lhs-width'. If neither switch is used the default is to - one. - -'--listing-rhs-width='number'' - Sets the maximum width, in characters, of the source line that is - displayed alongside the hex dump. The default value for this - parameter is 100. The source line is displayed on the right hand - side of the listing output. - -'--listing-cont-lines='number'' - Sets the maximum number of continuation lines of hex dump that will - be displayed for a given single line of source input. The default - value is 4. - -2.9 Assemble in MRI Compatibility Mode: '-M' -============================================ - -The '-M' or '--mri' option selects MRI compatibility mode. This changes -the syntax and pseudo-op handling of 'as' to make it compatible with the -'ASM68K' or the 'ASM960' (depending upon the configured target) -assembler from Microtec Research. The exact nature of the MRI syntax -will not be documented here; see the MRI manuals for more information. -Note in particular that the handling of macros and macro arguments is -somewhat different. The purpose of this option is to permit assembling -existing MRI assembler code using 'as'. - - The MRI compatibility is not complete. Certain operations of the MRI -assembler depend upon its object file format, and can not be supported -using other object file formats. Supporting these would require -enhancing each object file format individually. These are: - - * global symbols in common section - - The m68k MRI assembler supports common sections which are merged by - the linker. Other object file formats do not support this. 'as' - handles common sections by treating them as a single common symbol. - It permits local symbols to be defined within a common section, but - it can not support global symbols, since it has no way to describe - them. - - * complex relocations - - The MRI assemblers support relocations against a negated section - address, and relocations which combine the start addresses of two - or more sections. These are not support by other object file - formats. - - * 'END' pseudo-op specifying start address - - The MRI 'END' pseudo-op permits the specification of a start - address. This is not supported by other object file formats. The - start address may instead be specified using the '-e' option to the - linker, or in a linker script. - - * 'IDNT', '.ident' and 'NAME' pseudo-ops - - The MRI 'IDNT', '.ident' and 'NAME' pseudo-ops assign a module name - to the output file. This is not supported by other object file - formats. - - * 'ORG' pseudo-op - - The m68k MRI 'ORG' pseudo-op begins an absolute section at a given - address. This differs from the usual 'as' '.org' pseudo-op, which - changes the location within the current section. Absolute sections - are not supported by other object file formats. The address of a - section may be assigned within a linker script. - - There are some other features of the MRI assembler which are not -supported by 'as', typically either because they are difficult or -because they seem of little consequence. Some of these may be supported -in future releases. - - * EBCDIC strings - - EBCDIC strings are not supported. - - * packed binary coded decimal - - Packed binary coded decimal is not supported. This means that the - 'DC.P' and 'DCB.P' pseudo-ops are not supported. - - * 'FEQU' pseudo-op - - The m68k 'FEQU' pseudo-op is not supported. - - * 'NOOBJ' pseudo-op - - The m68k 'NOOBJ' pseudo-op is not supported. - - * 'OPT' branch control options - - The m68k 'OPT' branch control options--'B', 'BRS', 'BRB', 'BRL', - and 'BRW'--are ignored. 'as' automatically relaxes all branches, - whether forward or backward, to an appropriate size, so these - options serve no purpose. - - * 'OPT' list control options - - The following m68k 'OPT' list control options are ignored: 'C', - 'CEX', 'CL', 'CRE', 'E', 'G', 'I', 'M', 'MEX', 'MC', 'MD', 'X'. - - * other 'OPT' options - - The following m68k 'OPT' options are ignored: 'NEST', 'O', 'OLD', - 'OP', 'P', 'PCO', 'PCR', 'PCS', 'R'. - - * 'OPT' 'D' option is default - - The m68k 'OPT' 'D' option is the default, unlike the MRI assembler. - 'OPT NOD' may be used to turn it off. - - * 'XREF' pseudo-op. - - The m68k 'XREF' pseudo-op is ignored. - - * '.debug' pseudo-op - - The i960 '.debug' pseudo-op is not supported. - - * '.extended' pseudo-op - - The i960 '.extended' pseudo-op is not supported. - - * '.list' pseudo-op. - - The various options of the i960 '.list' pseudo-op are not - supported. - - * '.optimize' pseudo-op - - The i960 '.optimize' pseudo-op is not supported. - - * '.output' pseudo-op - - The i960 '.output' pseudo-op is not supported. - - * '.setreal' pseudo-op - - The i960 '.setreal' pseudo-op is not supported. - -2.10 Dependency Tracking: '--MD' -================================ - -'as' can generate a dependency file for the file it creates. This file -consists of a single rule suitable for 'make' describing the -dependencies of the main source file. - - The rule is written to the file named in its argument. - - This feature is used in the automatic updating of makefiles. - -2.11 Name the Object File: '-o' -=============================== - -There is always one object file output when you run 'as'. By default it -has the name 'a.out'. You use this option (which takes exactly one -filename) to give the object file a different name. - - Whatever the object file is called, 'as' overwrites any existing file -of the same name. - -2.12 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 do not 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 or ELF output, this option is only -useful if you use sections named '.text' and '.data'. - -2.13 Display Assembly Statistics: '--statistics' -================================================ - -Use '--statistics' to display two statistics about the resources used by -'as': the maximum amount of space allocated during the assembly (in -bytes), and the total execution time taken for the assembly (in CPU -seconds). - -2.14 Compatible Output: '--traditional-format' -============================================== - -For some targets, the output of 'as' is different in some ways from the -output of some existing assembler. This switch requests 'as' to use the -traditional format instead. - - For example, it disables the exception frame optimizations which 'as' -normally does by default on 'gcc' output. - -2.15 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. - -2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' -====================================================================== - -'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 the '-W' and '--no-warn' options, no warnings are issued. -This 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. - - If you use the '--fatal-warnings' option, 'as' considers files that -generate warnings to be in error. - - You can switch these options off again by specifying '--warn', which -causes warnings to be output as usual. - -2.17 Generate Object File in Spite of Errors: '-Z' -================================================== - -After an error message, 'as' normally produces no output. If for some -reason you are interested in object file output even after 'as' gives an -error message on your program, use the '-Z' option. If there are any -errors, 'as' continues anyways, and writes an object file after a final -warning message of the form 'N errors, M warnings, generating bad object -file.' - -3 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. - -3.1 Preprocessing -================= - -The 'as' internal preprocessor: - * 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. - - It does not do macro processing, include file handling, or anything -else you may get from your C compiler's preprocessor. You can do -include file processing with the '.include' directive (*note '.include': -Include.). You can use the GNU C compiler driver to get other "CPP" -style preprocessing by giving the input file a '.S' suffix. *Note -Options Controlling the Kind of Output: (gcc.info)Overall Options. - - Excess whitespace, comments, and character constants cannot be used -in the portions of the input text that are not preprocessed. - - If the first line of an input file is '#NO_APP' or if you use the -'-f' option, whitespace and comments are not removed from the input -file. Within an input file, you can ask for whitespace and comment -removal in specific portions of the by putting a line that says '#APP' -before the text that may contain whitespace or comments, and putting a -line that says '#NO_APP' after this text. This feature is mainly intend -to support 'asm' statements in compilers whose output is otherwise free -of comments and whitespace. - -3.2 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. - -3.3 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 ARM; '#' on the i386 and x86-64; '#' for Motorola PowerPC; '!' on -the SPARC; see *note Machine Dependencies::. - - To be compatible with past assemblers, lines that begin with '#' have -a special interpretation. Following the '#' should be an absolute -expression (*note Expressions::): the logical line number of the _next_ -line. Then a string (*note Strings: 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'. - -3.4 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 '_.$'. 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::. - -3.5 Statements -============== - -A "statement" ends at a newline character ('\n') or at a semicolon -(';'). The newline or semicolon is considered part of the preceding -statement. Newlines and semicolons within character constants are an -exception: they do not 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. - - 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 -assembles into a machine language instruction. - - 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, ... - -3.6 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. - -3.6.1 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. - -3.6.1.1 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. - -'\x HEX-DIGITS...' - A hex character code. All trailing hex digits are combined. - Either upper or lower case 'x' works. - -'\\' - 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 '\' gives a warning, but - assembles 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, do not use an escape sequence. - -3.6.1.2 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 (or semicolon ';') -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. - -3.6.2 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. - -3.6.2.1 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.). - -3.6.2.2 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. - -3.6.2.3 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. - - * 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'. - -4 Sections and Relocation -************************* - -4.1 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' -assigns the final addresses for the partial program, so that different -partial programs do not overlap. This is actually an -oversimplification, but it suffices 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. - - 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. - - 'as' can also generate whatever other named sections you specify -using the '.section' directive (*note '.section': Section.). If you do -not use any directives that place output in the '.text' or '.data' -sections, these sections still exist, but are 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 changes 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, most expressions 'as' computes have this section-relative -nature. - - 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 the linker never -arranges two partial programs' data sections with overlapping addresses -after linking, _by definition_ their absolute sections must overlap. -Address '{absolute 239}' in one part of a program is always the same -address when the program is running as address '{absolute 239}' in any -other part of the 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 is 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 programs' 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. - -4.2 Linker Sections -=================== - -'ld' deals with just four kinds of sections, summarized below. - -*named sections* - These sections hold your program. 'as' and 'ld' treat them as - separate but equal sections. Anything you can say of one section - is true of 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 contains 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 uninitialized 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 do not 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 ... - -4.3 Assembler Internal Sections -=============================== - -These sections are meant only for the internal use of 'as'. They have -no meaning at run-time. You do not 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. - -4.4 Sub-Sections -================ - -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 go into the object file together with other objects -in the same subsection. 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 do not use subsections, everything -goes in subsection number zero. - - 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 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. You can also use the '.subsection' -directive (*note SubSection::) to specify a subsection: '.subsection -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 changes it, and any label definition -captures its current value. The location counter of the section where -statements are being assembled is said to be the "active" location -counter. - -4.5 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. - - The '.lcomm' pseudo-op defines a symbol in the bss section; see *note -'.lcomm': Lcomm. - - The '.comm' pseudo-op may be used to declare a common symbol, which -is another form of uninitialized symbol; see *note '.comm': Comm. - -5 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. - -5.1 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. - -5.2 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. -In the same way, using a double equals sign '=''=' here represents an -equivalent of the '.eqv' directive. *Note '.eqv': Eqv. - -5.3 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 for a particular -target machine), and underscores. - - 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 ------------------- - -A local symbol is any symbol beginning with certain local label -prefixes. By default, the local label prefix is '.L' for ELF systems or -'L' for traditional a.out systems, but each target may have its own set -of local label prefixes. - - Local symbols are defined and used within the assembler, but they are -normally not saved in object files. Thus, they are not visible when -debugging. You may use the '-L' option (*note Include Local Symbols: -'-L': L.) to retain the local symbols in the object files. - -Local Labels ------------- - -Local labels help compilers and programmers use names temporarily. They -create symbols which are guaranteed to be unique over the entire scope -of the input source code and which can be referred to by a simple -notation. To define a local label, write a label of the form 'N:' -(where N represents any positive integer). To refer to the most recent -previous definition of that label write 'Nb', using the same number as -when you defined the label. To refer to the next definition of a local -label, write 'Nf'--the 'b' stands for "backwards" and the 'f' stands for -"forwards". - - There is no restriction on how you can use these labels, and you can -reuse them too. So that it is possible to repeatedly define the same -local label (using the same number 'N'), although you can only refer to -the most recently defined local label of that number (for a backwards -reference) or the next definition of a specific local label for a -forward reference. It is also worth noting that the first 10 local -labels ('0:'...'9:') are implemented in a slightly more efficient manner -than the others. - - Here is an example: - - 1: branch 1f - 2: branch 1b - 1: branch 2f - 2: branch 1b - - Which is the equivalent of: - - label_1: branch label_3 - label_2: branch label_1 - label_3: branch label_4 - label_4: branch label_3 - - Local label names are only a notational device. They are immediately -transformed into more conventional symbol names before the assembler -uses them. The symbol names are stored in the symbol table, appear in -error messages, and are optionally emitted to the object file. The -names are constructed using these parts: - -'_local label prefix_' - All local symbols begin with the system-specific local label - prefix. Normally both 'as' and 'ld' forget symbols that start with - the local label prefix. These labels are used for symbols you are - never intended to see. If you use the '-L' option then 'as' - retains these symbols in the object file. If you also instruct - 'ld' to retain these symbols, you may use them in debugging. - -'NUMBER' - This is the number that was used in the local label definition. So - if the label is written '55:' then the number is '55'. - -'C-B' - This unusual character is included so you do not accidentally - invent a symbol of the same name. The character has ASCII value of - '\002' (control-B). - -'_ordinal number_' - This is a serial number to keep the labels distinct. The first - definition of '0:' gets the number '1'. The 15th definition of - '0:' gets the number '15', and so on. Likewise the first - definition of '1:' gets the number '1' and its 15th definition gets - '15' as well. - - So for example, the first '1:' may be named '.L1C-B1', and the 44th -'3:' may be named '.L3C-B44'. - -Dollar Local Labels -------------------- - -'as' also supports an even more local form of local labels called dollar -labels. These labels go out of scope (i.e., they become undefined) as -soon as a non-local label is defined. Thus they remain valid for only a -small region of the input source code. Normal local labels, by -contrast, remain in scope for the entire file, or until they are -redefined by another occurrence of the same local label. - - Dollar labels are defined in exactly the same way as ordinary local -labels, except that instead of being terminated by a colon, they are -terminated by a dollar sign, e.g., '55$'. - - They can also be distinguished from ordinary local labels by their -transformed names which use ASCII character '\001' (control-A) as the -magic character to distinguish them from ordinary labels. For example, -the fifth definition of '6$' may be named '.L6'C-A'5'. - -5.4 The Special Dot Symbol -========================== - -The special symbol '.' refers to the current address that 'as' is -assembling into. Thus, the expression 'melvin: .long .' defines -'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'. - -5.5 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. The detailed definitions are in 'a.out.h'. - - 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. - -5.5.1 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 file, and -'ld' tries to determine its value from other files linked into the same -program. 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. - -5.5.2 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. - -6 Expressions -************* - -An "expression" specifies an address or numeric value. Whitespace may -precede and/or follow an expression. - - The result of an expression must be an absolute number, or else an -offset into a particular section. If an expression is not absolute, and -there is not enough information when 'as' sees the expression to know -its section, a second pass over the source program might be necessary to -interpret the expression--but the second pass is currently not -implemented. 'as' aborts with an error message in this situation. - -6.1 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' assumes a value of (absolute) 0. This is -compatible with other assemblers. - -6.2 Integer Expressions -======================= - -An "integer expression" is one or more _arguments_ delimited by -_operators_. - -6.2.1 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. - -6.2.2 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. - -6.2.3 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. - -6.2.4 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. Low Precedence - - '+' - "Addition". If either argument is absolute, the result has - the section of the other argument. You may not add together - arguments from different sections. - - '-' - "Subtraction". If the right argument is absolute, the result - has the section of the left argument. If both arguments are - in the same section, the result is absolute. You may not - subtract arguments from different sections. - - '==' - "Is Equal To" - '<>' - '!=' - "Is Not Equal To" - '<' - "Is Less Than" - '>' - "Is Greater Than" - '>=' - "Is Greater Than Or Equal To" - '<=' - "Is Less Than Or Equal To" - - The comparison operators can be used as infix operators. A - true results has a value of -1 whereas a false result has a - value of 0. Note, these operators perform signed comparisons. - - 4. Lowest Precedence - - '&&' - "Logical And". - - '||' - "Logical Or". - - These two logical operations can be used to combine the - results of sub expressions. Note, unlike the comparison - operators a true result returns a value of 1 but a false - results does still return 0. Also note that the logical or - operator has a slightly lower precedence than logical and. - - In short, it's only meaningful to add or subtract the _offsets_ in an -address; you can only have a defined section in one of the two -arguments. - -7 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. - -7.1 '.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. - -7.2 '.align ABS-EXPR, 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 -alignment required, as described below. - - The second expression (also absolute) gives the fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The way the required alignment is specified varies from system to -system. For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, -s390, sparc, tic4x, tic80 and xtensa, the first expression is the -alignment request in bytes. For example '.align 8' advances the -location counter until it is a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. For the tic54x, the -first expression is the alignment request in words. - - For other systems, including the i386 using a.out format, and the arm -and strongarm, it is the number of low-order zero bits the location -counter must have after advancement. For example '.align 3' advances -the location counter until it a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. - - This inconsistency is due to the different behaviors of the various -native assemblers for these systems which GAS must emulate. GAS also -provides '.balign' and '.p2align' directives, described later, which -have a consistent behavior across all architectures (but are specific to -GAS). - -7.3 '.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. - -7.4 '.asciz "STRING"'... -======================== - -'.asciz' is just like '.ascii', but each string is followed by a zero -byte. The "z" in '.asciz' stands for "zero". - -7.5 '.balign[wl] ABS-EXPR, 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 -alignment request in bytes. For example '.balign 8' advances the -location counter until it is 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 fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The '.balignw' and '.balignl' directives are variants of the -'.balign' directive. The '.balignw' directive treats the fill pattern -as a two byte word value. The '.balignl' directives treats the fill -pattern as a four byte longword value. For example, '.balignw 4,0x368d' -will align to a multiple of 4. If it skips two bytes, they will be -filled in with the value 0x368d (the exact placement of the bytes -depends upon the endianness of the processor). If it skips 1 or 3 -bytes, the fill value is undefined. - -7.6 '.byte EXPRESSIONS' -======================= - -'.byte' expects zero or more expressions, separated by commas. Each -expression is assembled into the next byte. - -7.7 '.comm SYMBOL , LENGTH ' -============================ - -'.comm' declares a common symbol named SYMBOL. When linking, a common -symbol in one object file may be merged with a defined or common symbol -of the same name in another object file. If 'ld' does not see a -definition for the symbol-just one or more common symbols-then it will -allocate LENGTH bytes of uninitialized memory. LENGTH must be an -absolute expression. If 'ld' sees multiple common symbols with the same -name, and they do not all have the same size, it will allocate space -using the largest size. - - When using ELF, the '.comm' directive takes an optional third -argument. This is the desired alignment of the symbol, specified as a -byte boundary (for example, an alignment of 16 means that the least -significant 4 bits of the address should be zero). The alignment must -be an absolute expression, and it must be a power of two. If 'ld' -allocates uninitialized memory for the common symbol, it will use the -alignment when placing the symbol. If no alignment is specified, 'as' -will set the alignment to the largest power of two less than or equal to -the size of the symbol, up to a maximum of 16. - -7.8 '.cfi_startproc [simple]' -============================= - -'.cfi_startproc' is used at the beginning of each function that should -have an entry in '.eh_frame'. It initializes some internal data -structures. Don't forget to close the function by '.cfi_endproc'. - - Unless '.cfi_startproc' is used along with parameter 'simple' it also -emits some architecture dependent initial CFI instructions. - -7.9 '.cfi_endproc' -================== - -'.cfi_endproc' is used at the end of a function where it closes its -unwind entry previously opened by '.cfi_startproc', and emits it to -'.eh_frame'. - -7.10 '.cfi_personality ENCODING [, EXP]' -======================================== - -'.cfi_personality' defines personality routine and its encoding. -ENCODING must be a constant determining how the personality should be -encoded. If it is 255 ('DW_EH_PE_omit'), second argument is not -present, otherwise second argument should be a constant or a symbol -name. When using indirect encodings, the symbol provided should be the -location where personality can be loaded from, not the personality -routine itself. The default after '.cfi_startproc' is '.cfi_personality -0xff', no personality routine. - -7.11 '.cfi_lsda ENCODING [, EXP]' -================================= - -'.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant -determining how the LSDA should be encoded. If it is 255 -('DW_EH_PE_omit'), second argument is not present, otherwise second -argument should be a constant or a symbol name. The default after -'.cfi_startproc' is '.cfi_lsda 0xff', no LSDA. - -7.12 '.cfi_def_cfa REGISTER, OFFSET' -==================================== - -'.cfi_def_cfa' defines a rule for computing CFA as: take address from -REGISTER and add OFFSET to it. - -7.13 '.cfi_def_cfa_register REGISTER' -===================================== - -'.cfi_def_cfa_register' modifies a rule for computing CFA. From now on -REGISTER will be used instead of the old one. Offset remains the same. - -7.14 '.cfi_def_cfa_offset OFFSET' -================================= - -'.cfi_def_cfa_offset' modifies a rule for computing CFA. Register -remains the same, but OFFSET is new. Note that it is the absolute -offset that will be added to a defined register to compute CFA address. - -7.15 '.cfi_adjust_cfa_offset OFFSET' -==================================== - -Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is -added/substracted from the previous offset. - -7.16 '.cfi_offset REGISTER, OFFSET' -=================================== - -Previous value of REGISTER is saved at offset OFFSET from CFA. - -7.17 '.cfi_rel_offset REGISTER, OFFSET' -======================================= - -Previous value of REGISTER is saved at offset OFFSET from the current -CFA register. This is transformed to '.cfi_offset' using the known -displacement of the CFA register from the CFA. This is often easier to -use, because the number will match the code it's annotating. - -7.18 '.cfi_register REGISTER1, REGISTER2' -========================================= - -Previous value of REGISTER1 is saved in register REGISTER2. - -7.19 '.cfi_restore REGISTER' -============================ - -'.cfi_restore' says that the rule for REGISTER is now the same as it was -at the beginning of the function, after all initial instruction added by -'.cfi_startproc' were executed. - -7.20 '.cfi_undefined REGISTER' -============================== - -From now on the previous value of REGISTER can't be restored anymore. - -7.21 '.cfi_same_value REGISTER' -=============================== - -Current value of REGISTER is the same like in the previous frame, i.e. -no restoration needed. - -7.22 '.cfi_remember_state', -=========================== - -First save all current rules for all registers by '.cfi_remember_state', -then totally screw them up by subsequent '.cfi_*' directives and when -everything is hopelessly bad, use '.cfi_restore_state' to restore the -previous saved state. - -7.23 '.cfi_return_column REGISTER' -================================== - -Change return column REGISTER, i.e. the return address is either -directly in REGISTER or can be accessed by rules for REGISTER. - -7.24 '.cfi_signal_frame' -======================== - -Mark current function as signal trampoline. - -7.25 '.cfi_window_save' -======================= - -SPARC register window has been saved. - -7.26 '.cfi_escape' EXPRESSION[, ...] -==================================== - -Allows the user to add arbitrary bytes to the unwind info. One might -use this to add OS-specific CFI opcodes, or generic CFI opcodes that GAS -does not yet support. - -7.27 '.file FILENO FILENAME' -============================ - -When emitting dwarf2 line number information '.file' assigns filenames -to the '.debug_line' file name table. The FILENO operand should be a -unique positive integer to use as the index of the entry in the table. -The FILENAME operand is a C string literal. - - The detail of filename indices is exposed to the user because the -filename table is shared with the '.debug_info' section of the dwarf2 -debugging information, and thus the user must know the exact indices -that table entries will have. - -7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' -============================================ - -The '.loc' directive will add row to the '.debug_line' line number -matrix corresponding to the immediately following assembly instruction. -The FILENO, LINENO, and optional COLUMN arguments will be applied to the -'.debug_line' state machine before the row is added. - - The OPTIONS are a sequence of the following tokens in any order: - -'basic_block' - This option will set the 'basic_block' register in the - '.debug_line' state machine to 'true'. - -'prologue_end' - This option will set the 'prologue_end' register in the - '.debug_line' state machine to 'true'. - -'epilogue_begin' - This option will set the 'epilogue_begin' register in the - '.debug_line' state machine to 'true'. - -'is_stmt VALUE' - This option will set the 'is_stmt' register in the '.debug_line' - state machine to 'value', which must be either 0 or 1. - -'isa VALUE' - This directive will set the 'isa' register in the '.debug_line' - state machine to VALUE, which must be an unsigned integer. - -7.29 '.loc_mark_blocks ENABLE' -============================== - -The '.loc_mark_blocks' directive makes the assembler emit an entry to -the '.debug_line' line number matrix with the 'basic_block' register in -the state machine set whenever a code label is seen. The ENABLE -argument should be either 1 or 0, to enable or disable this function -respectively. - -7.30 '.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. - -7.31 '.double FLONUMS' -====================== - -'.double' expects zero or more flonums, separated by commas. It -assembles floating point numbers. - -7.32 '.eject' -============= - -Force a page break at this point, when generating assembly listings. - -7.33 '.else' -============ - -'.else' is part of the 'as' support for conditional assembly; see *note -'.if': If. It marks the beginning of a section of code to be assembled -if the condition for the preceding '.if' was false. - -7.34 '.elseif' -============== - -'.elseif' is part of the 'as' support for conditional assembly; see -*note '.if': If. It is shorthand for beginning a new '.if' block that -would otherwise fill the entire '.else' section. - -7.35 '.end' -=========== - -'.end' marks the end of the assembly file. 'as' does not process -anything in the file past the '.end' directive. - -7.36 '.endfunc' -=============== - -'.endfunc' marks the end of a function specified with '.func'. - -7.37 '.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. - -7.38 '.equ SYMBOL, EXPRESSION' -============================== - -This directive sets the value of SYMBOL to EXPRESSION. It is synonymous -with '.set'; see *note '.set': Set. - -7.39 '.equiv SYMBOL, EXPRESSION' -================================ - -The '.equiv' directive is like '.equ' and '.set', except that the -assembler will signal an error if SYMBOL is already defined. Note a -symbol which has been referenced but not actually defined is considered -to be undefined. - - Except for the contents of the error message, this is roughly -equivalent to - .ifdef SYM - .err - .endif - .equ SYM,VAL - plus it protects the symbol from later redefinition. - -7.40 '.eqv SYMBOL, EXPRESSION' -============================== - -The '.eqv' directive is like '.equiv', but no attempt is made to -evaluate the expression or any part of it immediately. Instead each -time the resulting symbol is used in an expression, a snapshot of its -current value is taken. - -7.41 '.err' -=========== - -If 'as' assembles a '.err' directive, it will print an error message -and, unless the '-Z' option was used, it will not generate an object -file. This can be used to signal an error in conditionally compiled -code. - -7.42 '.error "STRING"' -====================== - -Similarly to '.err', this directive emits an error, but you can specify -a string that will be emitted as the error message. If you don't -specify the message, it defaults to '".error directive invoked in source -file"'. *Note Error and Warning Messages: Errors. - - .error "This code has not been assembled and tested." - -7.43 '.exitm' -============= - -Exit early from the current macro definition. *Note Macro::. - -7.44 '.extern' -============== - -'.extern' is accepted in the source program--for compatibility with -other assemblers--but it is ignored. 'as' treats all undefined symbols -as external. - -7.45 '.fail EXPRESSION' -======================= - -Generates an error or a warning. If the value of the EXPRESSION is 500 -or more, 'as' will print a warning message. If the value is less than -500, 'as' will print an error message. The message will include the -value of EXPRESSION. This can occasionally be useful inside complex -nested macros or conditional assembly. - -7.46 '.file STRING' -=================== - -'.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. - -7.47 '.fill REPEAT , SIZE , VALUE' -================================== - -REPEAT, 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. - -7.48 '.float FLONUMS' -===================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.single'. - -7.49 '.func NAME[,LABEL]' -========================= - -'.func' emits debugging information to denote function NAME, and is -ignored unless the file is assembled with debugging enabled. Only -'--gstabs[+]' is currently supported. LABEL is the entry point of the -function and if omitted NAME prepended with the 'leading char' is used. -'leading char' is usually '_' or nothing, depending on the target. All -functions are currently defined to have 'void' return type. The -function must be terminated with '.endfunc'. - -7.50 '.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 takes its -attributes from a symbol of the same name from another file linked into -the same program. - - Both spellings ('.globl' and '.global') are accepted, for -compatibility with other assemblers. - -7.51 '.hidden NAMES' -==================== - -This is one of the ELF visibility directives. The other two are -'.internal' (*note '.internal': Internal.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'hidden' which means that the symbols are not visible to -other components. Such symbols are always considered to be 'protected' -as well. - -7.52 '.hword EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - - This directive is a synonym for '.short'. - -7.53 '.ident' -============= - -This directive is used by some assemblers to place tags in object files. -The behavior of this directive varies depending on the target. When -using the a.out object file format, 'as' simply accepts the directive -for source-file compatibility with existing assemblers, but does not -emit anything for it. When using COFF, comments are emitted to the -'.comment' or '.rdata' section, depending on the target. When using -ELF, comments are emitted to the '.comment' section. - -7.54 '.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.). If you have several conditions to -check, '.elseif' may be used to avoid nesting blocks if/else within each -subsequent '.else' block. - - The following variants of '.if' are also supported: -'.ifdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - been defined. Note a symbol which has been referenced but not yet - defined is considered to be undefined. - -'.ifb TEXT' - Assembles the following section of code if the operand is blank - (empty). - -'.ifc STRING1,STRING2' - Assembles the following section of code if the two strings are the - same. The strings may be optionally quoted with single quotes. If - they are not quoted, the first string stops at the first comma, and - the second string stops at the end of the line. Strings which - contain whitespace should be quoted. The string comparison is case - sensitive. - -'.ifeq ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is zero. - -'.ifeqs STRING1,STRING2' - Another form of '.ifc'. The strings must be quoted using double - quotes. - -'.ifge ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than or equal to zero. - -'.ifgt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than zero. - -'.ifle ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than or equal to zero. - -'.iflt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than zero. - -'.ifnb TEXT' - Like '.ifb', but the sense of the test is reversed: this assembles - the following section of code if the operand is non-blank - (non-empty). - -'.ifnc STRING1,STRING2.' - Like '.ifc', but the sense of the test is reversed: this assembles - the following section of code if the two strings are not the same. - -'.ifndef SYMBOL' -'.ifnotdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - not been defined. Both spelling variants are equivalent. Note a - symbol which has been referenced but not yet defined is considered - to be undefined. - -'.ifne ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is not - equal to zero (in other words, this is equivalent to '.if'). - -'.ifnes STRING1,STRING2' - Like '.ifeqs', but the sense of the test is reversed: this - assembles the following section of code if the two strings are not - the same. - -7.55 '.incbin "FILE"[,SKIP[,COUNT]]' -==================================== - -The 'incbin' directive includes FILE verbatim at the current location. -You can control the search paths used with the '-I' command-line option -(*note Command-Line Options: Invoking.). Quotation marks are required -around FILE. - - The SKIP argument skips a number of bytes from the start of the FILE. -The COUNT argument indicates the maximum number of bytes to read. Note -that the data is not aligned in any way, so it is the user's -responsibility to make sure that proper alignment is provided both -before and after the 'incbin' directive. - -7.56 '.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. - -7.57 '.int EXPRESSIONS' -======================= - -Expect zero or more EXPRESSIONS, of any section, separated by commas. -For each expression, emit a number that, at run time, is the value of -that expression. The byte order and bit size of the number depends on -what kind of target the assembly is for. - -7.58 '.internal NAMES' -====================== - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note '.hidden': Hidden.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'internal' which means that the symbols are considered to -be 'hidden' (i.e., not visible to other components), and that some -extra, processor specific processing must also be performed upon the -symbols as well. - -7.59 '.irp SYMBOL,VALUES'... -============================ - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irp' directive, and is -terminated by an '.endr' directive. For each VALUE, SYMBOL is set to -VALUE, and the sequence of statements is assembled. If no VALUE is -listed, the sequence of statements is assembled once, with SYMBOL set to -the null string. To refer to SYMBOL within the sequence of statements, -use \SYMBOL. - - For example, assembling - - .irp param,1,2,3 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also *note Macro::. - -7.60 '.irpc SYMBOL,VALUES'... -============================= - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irpc' directive, and is -terminated by an '.endr' directive. For each character in VALUE, SYMBOL -is set to the character, and the sequence of statements is assembled. -If no VALUE is listed, the sequence of statements is assembled once, -with SYMBOL set to the null string. To refer to SYMBOL within the -sequence of statements, use \SYMBOL. - - For example, assembling - - .irpc param,123 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also the discussion -at *Note Macro::. - -7.61 '.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 that at -run-time the bytes start off zeroed. SYMBOL is not declared global -(*note '.global': Global.), so is normally not visible to 'ld'. - -7.62 '.lflags' -============== - -'as' accepts this directive, for compatibility with other assemblers, -but ignores it. - -7.63 '.line LINE-NUMBER' -======================== - -Even though this is a directive associated with the 'a.out' or 'b.out' -object-code formats, 'as' still recognizes it when producing COFF -output, and treats '.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. - -7.64 '.linkonce [TYPE]' -======================= - -Mark the current section so that the linker only includes a single copy -of it. This may be used to include the same section in several -different object files, but ensure that the linker will only include it -once in the final output file. The '.linkonce' pseudo-op must be used -for each instance of the section. Duplicate sections are detected based -on the section name, so it should be unique. - - This directive is only supported by a few object file formats; as of -this writing, the only object file format which supports it is the -Portable Executable format used on Windows NT. - - The TYPE argument is optional. If specified, it must be one of the -following strings. For example: - .linkonce same_size - Not all types may be supported on all object file formats. - -'discard' - Silently discard duplicate sections. This is the default. - -'one_only' - Warn if there are duplicate sections, but still keep only one copy. - -'same_size' - Warn if any of the duplicates have different sizes. - -'same_contents' - Warn if any of the duplicates do not have exactly the same - contents. - -7.65 '.ln LINE-NUMBER' -====================== - -'.ln' is a synonym for '.line'. - -7.66 '.mri VAL' -=============== - -If VAL is non-zero, this tells 'as' to enter MRI mode. If VAL is zero, -this tells 'as' to exit MRI mode. This change affects code assembled -until the next '.mri' directive, or until the end of the file. *Note -MRI mode: M. - -7.67 '.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. - -7.68 '.long EXPRESSIONS' -======================== - -'.long' is the same as '.int'. *Note '.int': Int. - -7.69 '.macro' -============= - -The commands '.macro' and '.endm' allow you to define macros that -generate assembly output. For example, this definition specifies a -macro 'sum' that puts a sequence of numbers into memory: - - .macro sum from=0, to=5 - .long \from - .if \to-\from - sum "(\from+1)",\to - .endif - .endm - -With that definition, 'SUM 0,5' is equivalent to this assembly input: - - .long 0 - .long 1 - .long 2 - .long 3 - .long 4 - .long 5 - -'.macro MACNAME' -'.macro MACNAME MACARGS ...' - Begin the definition of a macro called MACNAME. If your macro - definition requires arguments, specify their names after the macro - name, separated by commas or spaces. You can qualify the macro - argument to indicate whether all invocations must specify a - non-blank value (through ':'req''), or whether it takes all of the - remaining arguments (through ':'vararg''). You can supply a - default value for any macro argument by following the name with - '=DEFLT'. You cannot define two macros with the same MACNAME - unless it has been subject to the '.purgem' directive (*note - Purgem::) between the two definitions. For example, these are all - valid '.macro' statements: - - '.macro comm' - Begin the definition of a macro called 'comm', which takes no - arguments. - - '.macro plus1 p, p1' - '.macro plus1 p p1' - Either statement begins the definition of a macro called - 'plus1', which takes two arguments; within the macro - definition, write '\p' or '\p1' to evaluate the arguments. - - '.macro reserve_str p1=0 p2' - Begin the definition of a macro called 'reserve_str', with two - arguments. The first argument has a default value, but not - the second. After the definition is complete, you can call - the macro either as 'reserve_str A,B' (with '\p1' evaluating - to A and '\p2' evaluating to B), or as 'reserve_str ,B' (with - '\p1' evaluating as the default, in this case '0', and '\p2' - evaluating to B). - - '.macro m p1:req, p2=0, p3:vararg' - Begin the definition of a macro called 'm', with at least - three arguments. The first argument must always have a value - specified, but not the second, which instead has a default - value. The third formal will get assigned all remaining - arguments specified at invocation time. - - When you call a macro, you can specify the argument values - either by position, or by keyword. For example, 'sum 9,17' is - equivalent to 'sum to=17, from=9'. - - Note that since each of the MACARGS can be an identifier exactly as - any other one permitted by the target architecture, there may be - occasional problems if the target hand-crafts special meanings to - certain characters when they occur in a special position. For - example, if the colon (':') is generally permitted to be part of a - symbol name, but the architecture specific code special-cases it - when occurring as the final character of a symbol (to denote a - label), then the macro parameter replacement code will have no way - of knowing that and consider the whole construct (including the - colon) an identifier, and check only this identifier for being the - subject to parameter substitution. So for example this macro - definition: - - .macro label l - \l: - .endm - - might not work as expected. Invoking 'label foo' might not create - a label called 'foo' but instead just insert the text '\l:' into - the assembler source, probably generating an error about an - unrecognised identifier. - - Similarly problems might occur with the period character ('.') - which is often allowed inside opcode names (and hence identifier - names). So for example constructing a macro to build an opcode - from a base name and a length specifier like this: - - .macro opcode base length - \base.\length - .endm - - and invoking it as 'opcode store l' will not create a 'store.l' - instruction but instead generate some kind of error as the - assembler tries to interpret the text '\base.\length'. - - There are several possible ways around this problem: - - 'Insert white space' - If it is possible to use white space characters then this is - the simplest solution. eg: - - .macro label l - \l : - .endm - - 'Use '\()'' - The string '\()' can be used to separate the end of a macro - argument from the following text. eg: - - .macro opcode base length - \base\().\length - .endm - - 'Use the alternate macro syntax mode' - In the alternative macro syntax mode the ampersand character - ('&') can be used as a separator. eg: - - .altmacro - .macro label l - l&: - .endm - - Note: this problem of correctly identifying string parameters to - pseudo ops also applies to the identifiers used in '.irp' (*note - Irp::) and '.irpc' (*note Irpc::) as well. - -'.endm' - Mark the end of a macro definition. - -'.exitm' - Exit early from the current macro definition. - -'\@' - 'as' maintains a counter of how many macros it has executed in this - pseudo-variable; you can copy that number to your output with '\@', - but _only within a macro definition_. - -'LOCAL NAME [ , ... ]' - _Warning: 'LOCAL' is only available if you select "alternate macro - syntax" with '--alternate' or '.altmacro'._ *Note '.altmacro': - Altmacro. - -7.70 '.altmacro' -================ - -Enable alternate macro mode, enabling: - -'LOCAL NAME [ , ... ]' - One additional directive, 'LOCAL', is available. It is used to - generate a string replacement for each of the NAME arguments, and - replace any instances of NAME in each macro expansion. The - replacement string is unique in the assembly, and different for - each separate macro expansion. 'LOCAL' allows you to write macros - that define symbols, without fear of conflict between separate - macro expansions. - -'String delimiters' - You can write strings delimited in these other ways besides - '"STRING"': - - ''STRING'' - You can delimit strings with single-quote characters. - - '<STRING>' - You can delimit strings with matching angle brackets. - -'single-character string escape' - To include any single character literally in a string (even if the - character would otherwise have some special meaning), you can - prefix the character with '!' (an exclamation mark). For example, - you can write '<4.3 !> 5.4!!>' to get the literal text '4.3 > - 5.4!'. - -'Expression results as strings' - You can write '%EXPR' to evaluate the expression EXPR and use the - result as a string. - -7.71 '.noaltmacro' -================== - -Disable alternate macro mode. *Note Altmacro::. - -7.72 '.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. - -7.73 '.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. - -7.74 '.org NEW-LC , FILL' -========================= - -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' issues a warning, then pretends 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. - -7.75 '.p2align[wl] ABS-EXPR, 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 must have after -advancement. For example '.p2align 3' advances 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 fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The '.p2alignw' and '.p2alignl' directives are variants of the -'.p2align' directive. The '.p2alignw' directive treats the fill pattern -as a two byte word value. The '.p2alignl' directives treats the fill -pattern as a four byte longword value. For example, '.p2alignw -2,0x368d' will align to a multiple of 4. If it skips two bytes, they -will be filled in with the value 0x368d (the exact placement of the -bytes depends upon the endianness of the processor). If it skips 1 or 3 -bytes, the fill value is undefined. - -7.76 '.previous' -================ - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.popsection' -(*note PopSection::). - - This directive swaps the current section (and subsection) with most -recently referenced section (and subsection) prior to this one. -Multiple '.previous' directives in a row will flip between two sections -(and their subsections). - - In terms of the section stack, this directive swaps the current -section with the top section on the section stack. - -7.77 '.popsection' -================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.previous' -(*note Previous::). - - This directive replaces the current section (and subsection) with the -top section (and subsection) on the section stack. This section is -popped off the stack. - -7.78 '.print STRING' -==================== - -'as' will print STRING on the standard output during assembly. You must -put STRING in double quotes. - -7.79 '.protected NAMES' -======================= - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note Hidden::) and '.internal' (*note Internal::). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'protected' which means that any references to the symbols -from within the components that defines them must be resolved to the -definition in that component, even if a definition in another component -would normally preempt this. - -7.80 '.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 do not use '.psize', listings use a default line-count of 60. -You may omit the comma and COLUMNS specification; the default width is -200 columns. - - 'as' generates 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'. - -7.81 '.purgem NAME' -=================== - -Undefine the macro NAME, so that later uses of the string will not be -expanded. *Note Macro::. - -7.82 '.pushsection NAME , SUBSECTION' -===================================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive pushes the current section (and subsection) onto the -top of the section stack, and then replaces the current section and -subsection with 'name' and 'subsection'. - -7.83 '.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. - -7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' -============================================== - -Generate a relocation at OFFSET of type RELOC_NAME with value -EXPRESSION. If OFFSET is a number, the relocation is generated in the -current section. If OFFSET is an expression that resolves to a symbol -plus offset, the relocation is generated in the given symbol's section. -EXPRESSION, if present, must resolve to a symbol plus addend or to an -absolute value, but note that not all targets support an addend. e.g. -ELF REL targets such as i386 store an addend in the section contents -rather than in the relocation. This low level interface does not -support addends stored in the section. - -7.85 '.rept COUNT' -================== - -Repeat the sequence of lines between the '.rept' directive and the next -'.endr' directive COUNT times. - - For example, assembling - - .rept 3 - .long 0 - .endr - - is equivalent to assembling - - .long 0 - .long 0 - .long 0 - -7.86 '.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. - -7.87 '.section NAME' -==================== - -Use the '.section' directive to assemble the following code into a -section named NAME. - - This directive is only supported for targets that actually support -arbitrarily named sections; on 'a.out' targets, for example, it is not -accepted, even with a standard 'a.out' section name. - - This is one of the ELF section stack manipulation directives. The -others are '.subsection' (*note SubSection::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - For ELF targets, the '.section' directive is used like this: - - .section NAME [, "FLAGS"[, @TYPE[,FLAG_SPECIFIC_ARGUMENTS]]] - - The optional FLAGS argument is a quoted string which may contain any -combination of the following characters: -'a' - section is allocatable -'w' - section is writable -'x' - section is executable -'M' - section is mergeable -'S' - section contains zero terminated strings -'G' - section is a member of a section group -'T' - section is used for thread-local-storage - - The optional TYPE argument may contain one of the following -constants: -'@progbits' - section contains data -'@nobits' - section does not contain data (i.e., section only occupies space) -'@note' - section contains data which is used by things other than the - program -'@init_array' - section contains an array of pointers to init functions -'@fini_array' - section contains an array of pointers to finish functions -'@preinit_array' - section contains an array of pointers to pre-init functions - - Many targets only support the first three section types. - - Note on targets where the '@' character is the start of a comment (eg -ARM) then another character is used instead. For example the ARM port -uses the '%' character. - - If FLAGS contains the 'M' symbol then the TYPE argument must be -specified as well as an extra argument--ENTSIZE--like this: - - .section NAME , "FLAGS"M, @TYPE, ENTSIZE - - Sections with the 'M' flag but not 'S' flag must contain fixed size -constants, each ENTSIZE octets long. Sections with both 'M' and 'S' -must contain zero terminated strings where each character is ENTSIZE -bytes long. The linker may remove duplicates within sections with the -same name, same entity size and same flags. ENTSIZE must be an absolute -expression. - - If FLAGS contains the 'G' symbol then the TYPE argument must be -present along with an additional field like this: - - .section NAME , "FLAGS"G, @TYPE, GROUPNAME[, LINKAGE] - - The GROUPNAME field specifies the name of the section group to which -this particular section belongs. The optional linkage field can -contain: -'comdat' - indicates that only one copy of this section should be retained -'.gnu.linkonce' - an alias for comdat - - Note: if both the M and G flags are present then the fields for the -Merge flag should come first, like this: - - .section NAME , "FLAGS"MG, @TYPE, ENTSIZE, GROUPNAME[, LINKAGE] - - If no flags are specified, the default flags depend upon the section -name. If the section name is not recognized, the default will be for -the section to have none of the above flags: it will not be allocated in -memory, nor writable, nor executable. The section will contain data. - - For ELF targets, the assembler supports another type of '.section' -directive for compatibility with the Solaris assembler: - - .section "NAME"[, FLAGS...] - - Note that the section name is quoted. There may be a sequence of -comma separated flags: -'#alloc' - section is allocatable -'#write' - section is writable -'#execinstr' - section is executable -'#tls' - section is used for thread local storage - - This directive replaces the current section and subsection. See the -contents of the gas testsuite directory 'gas/testsuite/gas/elf' for some -examples of how this directive and the other section stack directives -work. - -7.88 '.set SYMBOL, EXPRESSION' -============================== - -Set the value of SYMBOL to EXPRESSION. This changes 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 you '.set' a global symbol, the value stored in the object file is -the last value stored into it. - -7.89 '.short EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - -7.90 '.single FLONUMS' -====================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.float'. - -7.91 '.size' -============ - -This directive is used to set the size associated with a symbol. - - For ELF targets, the '.size' directive is used like this: - - .size NAME , EXPRESSION - - This directive sets the size associated with a symbol NAME. The size -in bytes is computed from EXPRESSION which can make use of label -arithmetic. This directive is typically used to set the size of -function symbols. - -7.92 '.sleb128 EXPRESSIONS' -=========================== - -SLEB128 stands for "signed little endian base 128." This is a compact, -variable length representation of numbers used by the DWARF symbolic -debugging format. *Note '.uleb128': Uleb128. - -7.93 '.skip 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. This is the same as '.space'. - -7.94 '.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. This is the same as '.skip'. - -7.95 '.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 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; you -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 is the - address of the location counter 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. - -7.96 '.string' "STR" -==================== - -Copy the characters in STR to the object file. You may specify more -than one string to copy, separated by commas. Unless otherwise -specified for a particular machine, the assembler marks the end of each -string with a 0 byte. You can use any of the escape sequences described -in *note Strings: Strings. - -7.97 '.struct EXPRESSION' -========================= - -Switch to the absolute section, and set the section offset to -EXPRESSION, which must be an absolute expression. You might use this as -follows: - .struct 0 - field1: - .struct field1 + 4 - field2: - .struct field2 + 4 - field3: - This would define the symbol 'field1' to have the value 0, the symbol -'field2' to have the value 4, and the symbol 'field3' to have the value -8. Assembly would be left in the absolute section, and you would need -to use a '.section' directive of some sort to change to some other -section before further assembly. - -7.98 '.subsection NAME' -======================= - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive replaces the current subsection with 'name'. The -current section is not changed. The replaced subsection is put onto the -section stack in place of the then current top of stack subsection. - -7.99 '.symver' -============== - -Use the '.symver' directive to bind symbols to specific version nodes -within a source file. This is only supported on ELF platforms, and is -typically used when assembling files to be linked into a shared library. -There are cases where it may make sense to use this in objects to be -bound into an application itself so as to override a versioned symbol -from a shared library. - - For ELF targets, the '.symver' directive can be used like this: - .symver NAME, NAME2@NODENAME - If the symbol NAME is defined within the file being assembled, the -'.symver' directive effectively creates a symbol alias with the name -NAME2@NODENAME, and in fact the main reason that we just don't try and -create a regular alias is that the @ character isn't permitted in symbol -names. The NAME2 part of the name is the actual name of the symbol by -which it will be externally referenced. The name NAME itself is merely -a name of convenience that is used so that it is possible to have -definitions for multiple versions of a function within a single source -file, and so that the compiler can unambiguously know which version of a -function is being mentioned. The NODENAME portion of the alias should -be the name of a node specified in the version script supplied to the -linker when building a shared library. If you are attempting to -override a versioned symbol from a shared library, then NODENAME should -correspond to the nodename of the symbol you are trying to override. - - If the symbol NAME is not defined within the file being assembled, -all references to NAME will be changed to NAME2@NODENAME. If no -reference to NAME is made, NAME2@NODENAME will be removed from the -symbol table. - - Another usage of the '.symver' directive is: - .symver NAME, NAME2@@NODENAME - In this case, the symbol NAME must exist and be defined within the -file being assembled. It is similar to NAME2@NODENAME. The difference -is NAME2@@NODENAME will also be used to resolve references to NAME2 by -the linker. - - The third usage of the '.symver' directive is: - .symver NAME, NAME2@@@NODENAME - When NAME is not defined within the file being assembled, it is -treated as NAME2@NODENAME. When NAME is defined within the file being -assembled, the symbol name, NAME, will be changed to NAME2@@NODENAME. - -7.100 '.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. - -7.101 '.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. - -7.102 '.type' -============= - -This directive is used to set the type of a symbol. - - For ELF targets, the '.type' directive is used like this: - - .type NAME , TYPE DESCRIPTION - - This sets the type of symbol NAME to be either a function symbol or -an object symbol. There are five different syntaxes supported for the -TYPE DESCRIPTION field, in order to provide compatibility with various -other assemblers. - - Because some of the characters used in these syntaxes (such as '@' -and '#') are comment characters for some architectures, some of the -syntaxes below do not work on all architectures. The first variant will -be accepted by the GNU assembler on all architectures so that variant -should be used for maximum portability, if you do not need to assemble -your code with other assemblers. - - The syntaxes supported are: - - .type <name> STT_FUNCTION - .type <name> STT_OBJECT - - .type <name>,#function - .type <name>,#object - - .type <name>,@function - .type <name>,@object - - .type <name>,%function - .type <name>,%object - - .type <name>,"function" - .type <name>,"object" - -7.103 '.uleb128 EXPRESSIONS' -============================ - -ULEB128 stands for "unsigned little endian base 128." This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. *Note '.sleb128': Sleb128. - -7.104 '.version "STRING"' -========================= - -This directive creates a '.note' section and places into it an ELF -formatted note of type NT_VERSION. The note's name is set to 'string'. - -7.105 '.vtable_entry TABLE, OFFSET' -=================================== - -This directive finds or creates a symbol 'table' and creates a -'VTABLE_ENTRY' relocation for it with an addend of 'offset'. - -7.106 '.vtable_inherit CHILD, PARENT' -===================================== - -This directive finds the symbol 'child' and finds or creates the symbol -'parent' and then creates a 'VTABLE_INHERIT' relocation for the parent -whose addend is the value of the child symbol. As a special case the -parent name of '0' is treated as referring to the '*ABS*' section. - -7.107 '.warning "STRING"' -========================= - -Similar to the directive '.error' (*note '.error "STRING"': Error.), but -just emits a warning. - -7.108 '.weak NAMES' -=================== - -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - On COFF targets other than PE, weak symbols are a GNU extension. -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - On the PE target, weak symbols are supported natively as weak -aliases. When a weak symbol is created that is not an alias, GAS -creates an alternate symbol to hold the default value. - -7.109 '.weakref ALIAS, TARGET' -============================== - -This directive creates an alias to the target symbol that enables the -symbol to be referenced with weak-symbol semantics, but without actually -making it weak. If direct references or definitions of the symbol are -present, then the symbol will not be weak, but if all references to it -are through weak references, the symbol will be marked as weak in the -symbol table. - - The effect is equivalent to moving all references to the alias to a -separate assembly source file, renaming the alias to the symbol in it, -declaring the symbol as weak there, and running a reloadable link to -merge the object files resulting from the assembly of the new source -file and the old source file that had the references to the alias -removed. - - The alias itself never makes to the symbol table, and is entirely -handled within the assembler. - -7.110 '.word EXPRESSIONS' -========================= - -This directive expects zero or more EXPRESSIONS, of any section, -separated by commas. For each expression, 'as' emits a 32-bit number. - -7.111 Deprecated Directives -=========================== - -One day these directives won't work. They are included for -compatibility with older assemblers. -.abort -.line - -8 ARM Dependent Features -************************ - -8.1 Options -=========== - -'-mcpu=PROCESSOR[+EXTENSION...]' - This option specifies the target processor. The assembler will - issue an error message if an attempt is made to assemble an - instruction which will not execute on the target processor. The - following processor names are recognized: 'arm1', 'arm2', 'arm250', - 'arm3', 'arm6', 'arm60', 'arm600', 'arm610', 'arm620', 'arm7', - 'arm7m', 'arm7d', 'arm7dm', 'arm7di', 'arm7dmi', 'arm70', 'arm700', - 'arm700i', 'arm710', 'arm710t', 'arm720', 'arm720t', 'arm740t', - 'arm710c', 'arm7100', 'arm7500', 'arm7500fe', 'arm7t', 'arm7tdmi', - 'arm7tdmi-s', 'arm8', 'arm810', 'strongarm', 'strongarm1', - 'strongarm110', 'strongarm1100', 'strongarm1110', 'arm9', 'arm920', - 'arm920t', 'arm922t', 'arm940t', 'arm9tdmi', 'arm9e', 'arm926e', - 'arm926ej-s', 'arm946e-r0', 'arm946e', 'arm946e-s', 'arm966e-r0', - 'arm966e', 'arm966e-s', 'arm968e-s', 'arm10t', 'arm10tdmi', - 'arm10e', 'arm1020', 'arm1020t', 'arm1020e', 'arm1022e', - 'arm1026ej-s', 'arm1136j-s', 'arm1136jf-s', 'arm1156t2-s', - 'arm1156t2f-s', 'arm1176jz-s', 'arm1176jzf-s', 'mpcore', - 'mpcorenovfp', 'cortex-a8', 'cortex-r4', 'cortex-m3', 'ep9312' - (ARM920 with Cirrus Maverick coprocessor), 'i80200' (Intel XScale - processor) 'iwmmxt' (Intel(r) XScale processor with Wireless - MMX(tm) technology coprocessor) and 'xscale'. The special name - 'all' may be used to allow the assembler to accept instructions - valid for any ARM processor. - - In addition to the basic instruction set, the assembler can be told - to accept various extension mnemonics that extend the processor - using the co-processor instruction space. For example, - '-mcpu=arm920+maverick' is equivalent to specifying '-mcpu=ep9312'. - The following extensions are currently supported: '+maverick' - '+iwmmxt' and '+xscale'. - -'-march=ARCHITECTURE[+EXTENSION...]' - This option specifies the target architecture. The assembler will - issue an error message if an attempt is made to assemble an - instruction which will not execute on the target architecture. The - following architecture names are recognized: 'armv1', 'armv2', - 'armv2a', 'armv2s', 'armv3', 'armv3m', 'armv4', 'armv4xm', - 'armv4t', 'armv4txm', 'armv5', 'armv5t', 'armv5txm', 'armv5te', - 'armv5texp', 'armv6', 'armv6j', 'armv6k', 'armv6z', 'armv6zk', - 'armv7', 'armv7-a', 'armv7-r', 'armv7-m', 'iwmmxt' and 'xscale'. - If both '-mcpu' and '-march' are specified, the assembler will use - the setting for '-mcpu'. - - The architecture option can be extended with the same instruction - set extension options as the '-mcpu' option. - -'-mfpu=FLOATING-POINT-FORMAT' - - This option specifies the floating point format to assemble for. - The assembler will issue an error message if an attempt is made to - assemble an instruction which will not execute on the target - floating point unit. The following format options are recognized: - 'softfpa', 'fpe', 'fpe2', 'fpe3', 'fpa', 'fpa10', 'fpa11', - 'arm7500fe', 'softvfp', 'softvfp+vfp', 'vfp', 'vfp10', 'vfp10-r0', - 'vfp9', 'vfpxd', 'arm1020t', 'arm1020e', 'arm1136jf-s' and - 'maverick'. - - In addition to determining which instructions are assembled, this - option also affects the way in which the '.double' assembler - directive behaves when assembling little-endian code. - - The default is dependent on the processor selected. For - Architecture 5 or later, the default is to assembler for VFP - instructions; for earlier architectures the default is to assemble - for FPA instructions. - -'-mthumb' - This option specifies that the assembler should start assembling - Thumb instructions; that is, it should behave as though the file - starts with a '.code 16' directive. - -'-mthumb-interwork' - This option specifies that the output generated by the assembler - should be marked as supporting interworking. - -'-mapcs [26|32]' - This option specifies that the output generated by the assembler - should be marked as supporting the indicated version of the Arm - Procedure. Calling Standard. - -'-matpcs' - This option specifies that the output generated by the assembler - should be marked as supporting the Arm/Thumb Procedure Calling - Standard. If enabled this option will cause the assembler to - create an empty debugging section in the object file called - .arm.atpcs. Debuggers can use this to determine the ABI being used - by. - -'-mapcs-float' - This indicates the floating point variant of the APCS should be - used. In this variant floating point arguments are passed in FP - registers rather than integer registers. - -'-mapcs-reentrant' - This indicates that the reentrant variant of the APCS should be - used. This variant supports position independent code. - -'-mfloat-abi=ABI' - This option specifies that the output generated by the assembler - should be marked as using specified floating point ABI. The - following values are recognized: 'soft', 'softfp' and 'hard'. - -'-meabi=VER' - This option specifies which EABI version the produced object files - should conform to. The following values are recognized: 'gnu', '4' - and '5'. - -'-EB' - This option specifies that the output generated by the assembler - should be marked as being encoded for a big-endian processor. - -'-EL' - This option specifies that the output generated by the assembler - should be marked as being encoded for a little-endian processor. - -'-k' - This option specifies that the output of the assembler should be - marked as position-independent code (PIC). - -8.2 Syntax -========== - -8.2.1 Special Characters ------------------------- - -The presence of a '@' on a line indicates the start of a comment that -extends to the end of the current line. If a '#' appears as the first -character of a line, the whole line is treated as a comment. - - The ';' character can be used instead of a newline to separate -statements. - - Either '#' or '$' can be used to indicate immediate operands. - - *TODO* Explain about /data modifier on symbols. - -8.2.2 Register Names --------------------- - -*TODO* Explain about ARM register naming, and the predefined names. - -8.2.3 ARM relocation generation -------------------------------- - -Specific data relocations can be generated by putting the relocation -name in parentheses after the symbol name. For example: - - .word foo(TARGET1) - - This will generate an 'R_ARM_TARGET1' relocation against the symbol -FOO. The following relocations are supported: 'GOT', 'GOTOFF', -'TARGET1', 'TARGET2', 'SBREL', 'TLSGD', 'TLSLDM', 'TLSLDO', 'GOTTPOFF' -and 'TPOFF'. - - For compatibility with older toolchains the assembler also accepts -'(PLT)' after branch targets. This will generate the deprecated -'R_ARM_PLT32' relocation. - - Relocations for 'MOVW' and 'MOVT' instructions can be generated by -prefixing the value with '#:lower16:' and '#:upper16' respectively. For -example to load the 32-bit address of foo into r0: - - MOVW r0, #:lower16:foo - MOVT r0, #:upper16:foo - -8.3 Floating Point -================== - -The ARM family uses IEEE floating-point numbers. - -8.4 ARM Machine Directives -========================== - -'.align EXPRESSION [, EXPRESSION]' - This is the generic .ALIGN directive. For the ARM however if the - first argument is zero (ie no alignment is needed) the assembler - will behave as if the argument had been 2 (ie pad to the next four - byte boundary). This is for compatibility with ARM's own - assembler. - -'NAME .req REGISTER NAME' - This creates an alias for REGISTER NAME called NAME. For example: - - foo .req r0 - -'.unreq ALIAS-NAME' - This undefines a register alias which was previously defined using - the 'req', 'dn' or 'qn' directives. For example: - - foo .req r0 - .unreq foo - - An error occurs if the name is undefined. Note - this pseudo op - can be used to delete builtin in register name aliases (eg 'r0'). - This should only be done if it is really necessary. - -'NAME .dn REGISTER NAME [.TYPE] [[INDEX]]' -'NAME .qn REGISTER NAME [.TYPE] [[INDEX]]' - - The 'dn' and 'qn' directives are used to create typed and/or - indexed register aliases for use in Advanced SIMD Extension (Neon) - instructions. The former should be used to create aliases of - double-precision registers, and the latter to create aliases of - quad-precision registers. - - If these directives are used to create typed aliases, those aliases - can be used in Neon instructions instead of writing types after the - mnemonic or after each operand. For example: - - x .dn d2.f32 - y .dn d3.f32 - z .dn d4.f32[1] - vmul x,y,z - - This is equivalent to writing the following: - - vmul.f32 d2,d3,d4[1] - - Aliases created using 'dn' or 'qn' can be destroyed using 'unreq'. - -'.code [16|32]' - This directive selects the instruction set being generated. The - value 16 selects Thumb, with the value 32 selecting ARM. - -'.thumb' - This performs the same action as .CODE 16. - -'.arm' - This performs the same action as .CODE 32. - -'.force_thumb' - This directive forces the selection of Thumb instructions, even if - the target processor does not support those instructions - -'.thumb_func' - This directive specifies that the following symbol is the name of a - Thumb encoded function. This information is necessary in order to - allow the assembler and linker to generate correct code for - interworking between Arm and Thumb instructions and should be used - even if interworking is not going to be performed. The presence of - this directive also implies '.thumb' - - This directive is not neccessary when generating EABI objects. On - these targets the encoding is implicit when generating Thumb code. - -'.thumb_set' - This performs the equivalent of a '.set' directive in that it - creates a symbol which is an alias for another symbol (possibly not - yet defined). This directive also has the added property in that - it marks the aliased symbol as being a thumb function entry point, - in the same way that the '.thumb_func' directive does. - -'.ltorg' - This directive causes the current contents of the literal pool to - be dumped into the current section (which is assumed to be the - .text section) at the current location (aligned to a word - boundary). 'GAS' maintains a separate literal pool for each - section and each sub-section. The '.ltorg' directive will only - affect the literal pool of the current section and sub-section. At - the end of assembly all remaining, un-empty literal pools will - automatically be dumped. - - Note - older versions of 'GAS' would dump the current literal pool - any time a section change occurred. This is no longer done, since - it prevents accurate control of the placement of literal pools. - -'.pool' - This is a synonym for .ltorg. - -'.unwind_fnstart' - Marks the start of a function with an unwind table entry. - -'.unwind_fnend' - Marks the end of a function with an unwind table entry. The unwind - index table entry is created when this directive is processed. - - If no personality routine has been specified then standard - personality routine 0 or 1 will be used, depending on the number of - unwind opcodes required. - -'.cantunwind' - Prevents unwinding through the current function. No personality - routine or exception table data is required or permitted. - -'.personality NAME' - Sets the personality routine for the current function to NAME. - -'.personalityindex INDEX' - Sets the personality routine for the current function to the EABI - standard routine number INDEX - -'.handlerdata' - Marks the end of the current function, and the start of the - exception table entry for that function. Anything between this - directive and the '.fnend' directive will be added to the exception - table entry. - - Must be preceded by a '.personality' or '.personalityindex' - directive. - -'.save REGLIST' - Generate unwinder annotations to restore the registers in REGLIST. - The format of REGLIST is the same as the corresponding - store-multiple instruction. - - _core registers_ - .save {r4, r5, r6, lr} - stmfd sp!, {r4, r5, r6, lr} - _FPA registers_ - .save f4, 2 - sfmfd f4, 2, [sp]! - _VFP registers_ - .save {d8, d9, d10} - fstmdx sp!, {d8, d9, d10} - _iWMMXt registers_ - .save {wr10, wr11} - wstrd wr11, [sp, #-8]! - wstrd wr10, [sp, #-8]! - or - .save wr11 - wstrd wr11, [sp, #-8]! - .save wr10 - wstrd wr10, [sp, #-8]! - -'.vsave VFP-REGLIST' - Generate unwinder annotations to restore the VFP registers in - VFP-REGLIST using FLDMD. Also works for VFPv3 registers that are to - be restored using VLDM. The format of VFP-REGLIST is the same as - the corresponding store-multiple instruction. - - _VFP registers_ - .vsave {d8, d9, d10} - fstmdd sp!, {d8, d9, d10} - _VFPv3 registers_ - .vsave {d15, d16, d17} - vstm sp!, {d15, d16, d17} - - Since FLDMX and FSTMX are now deprecated, this directive should be - used in favour of '.save' for saving VFP registers for ARMv6 and - above. - -'.pad #COUNT' - Generate unwinder annotations for a stack adjustment of COUNT - bytes. A positive value indicates the function prologue allocated - stack space by decrementing the stack pointer. - -'.movsp REG [, #OFFSET]' - Tell the unwinder that REG contains an offset from the current - stack pointer. If OFFSET is not specified then it is assumed to be - zero. - -'.setfp FPREG, SPREG [, #OFFSET]' - Make all unwinder annotations relaive to a frame pointer. Without - this the unwinder will use offsets from the stack pointer. - - The syntax of this directive is the same as the 'sub' or 'mov' - instruction used to set the frame pointer. SPREG must be either - 'sp' or mentioned in a previous '.movsp' directive. - - .movsp ip - mov ip, sp - ... - .setfp fp, ip, #4 - sub fp, ip, #4 - -'.raw OFFSET, BYTE1, ...' - Insert one of more arbitary unwind opcode bytes, which are known to - adjust the stack pointer by OFFSET bytes. - - For example '.unwind_raw 4, 0xb1, 0x01' is equivalent to '.save - {r0}' - -'.cpu NAME' - Select the target processor. Valid values for NAME are the same as - for the '-mcpu' commandline option. - -'.arch NAME' - Select the target architecture. Valid values for NAME are the same - as for the '-march' commandline option. - -'.object_arch NAME' - Override the architecture recorded in the EABI object attribute - section. Valid values for NAME are the same as for the '.arch' - directive. Typically this is useful when code uses runtime - detection of CPU features. - -'.fpu NAME' - Select the floating point unit to assemble for. Valid values for - NAME are the same as for the '-mfpu' commandline option. - -'.eabi_attribute TAG, VALUE' - Set the EABI object attribute number TAG to VALUE. The value is - either a 'number', '"string"', or 'number, "string"' depending on - the tag. - -8.5 Opcodes -=========== - -'as' implements all the standard ARM opcodes. It also implements -several pseudo opcodes, including several synthetic load instructions. - -'NOP' - nop - - This pseudo op will always evaluate to a legal ARM instruction that - does nothing. Currently it will evaluate to MOV r0, r0. - -'LDR' - ldr <register> , = <expression> - - If expression evaluates to a numeric constant then a MOV or MVN - instruction will be used in place of the LDR instruction, if the - constant can be generated by either of these instructions. - Otherwise the constant will be placed into the nearest literal pool - (if it not already there) and a PC relative LDR instruction will be - generated. - -'ADR' - adr <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to a PC relative ADD or - SUB instruction depending upon where the label is located. If the - label is out of range, or if it is not defined in the same file - (and section) as the ADR instruction, then an error will be - generated. This instruction will not make use of the literal pool. - -'ADRL' - adrl <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to one or two PC relative - ADD or SUB instructions depending upon where the label is located. - If a second instruction is not needed a NOP instruction will be - generated in its place, so that this instruction is always 8 bytes - long. - - If the label is out of range, or if it is not defined in the same - file (and section) as the ADRL instruction, then an error will be - generated. This instruction will not make use of the literal pool. - - For information on the ARM or Thumb instruction sets, see 'ARM -Software Development Toolkit Reference Manual', Advanced RISC Machines -Ltd. - -8.6 Mapping Symbols -=================== - -The ARM ELF specification requires that special symbols be inserted into -object files to mark certain features: - -'$a' - At the start of a region of code containing ARM instructions. - -'$t' - At the start of a region of code containing THUMB instructions. - -'$d' - At the start of a region of data. - - The assembler will automatically insert these symbols for you - there -is no need to code them yourself. Support for tagging symbols ($b, $f, -$p and $m) which is also mentioned in the current ARM ELF specification -is not implemented. This is because they have been dropped from the new -EABI and so tools cannot rely upon their presence. - -9 80386 Dependent Features -************************** - -The i386 version 'as' supports both the original Intel 386 architecture -in both 16 and 32-bit mode as well as AMD x86-64 architecture extending -the Intel architecture to 64-bits. - -9.1 Options -=========== - -The i386 version of 'as' has a few machine dependent options: - -'--32 | --64' - Select the word size, either 32 bits or 64 bits. Selecting 32-bit - implies Intel i386 architecture, while 64-bit implies AMD x86-64 - architecture. - - These options are only available with the ELF object file format, - and require that the necessary BFD support has been included (on a - 32-bit platform you have to add -enable-64-bit-bfd to configure - enable 64-bit usage and use x86-64 as target platform). - -'-n' - By default, x86 GAS replaces multiple nop instructions used for - alignment within code sections with multi-byte nop instructions - such as leal 0(%esi,1),%esi. This switch disables the - optimization. - -'--divide' - On SVR4-derived platforms, the character '/' is treated as a - comment character, which means that it cannot be used in - expressions. The '--divide' option turns '/' into a normal - character. This does not disable '/' at the beginning of a line - starting a comment, or affect using '#' for starting a comment. - -'-march=CPU' - This option specifies an instruction set architecture for - generating instructions. The following architectures are - recognized: 'i8086', 'i186', 'i286', 'i386', 'i486', 'i586', - 'i686', 'pentium', 'pentiumpro', 'pentiumii', 'pentiumiii', - 'pentium4', 'prescott', 'nocona', 'core', 'core2', 'k6', 'k6_2', - 'athlon', 'sledgehammer', 'opteron', 'k8', 'generic32' and - 'generic64'. - - This option only affects instructions generated by the assembler. - The '.arch' directive will take precedent. - -'-mtune=CPU' - This option specifies a processor to optimize for. When used in - conjunction with the '-march' option, only instructions of the - processor specified by the '-march' option will be generated. - - Valid CPU values are identical to '-march=CPU'. - -9.2 AT&T Syntax versus Intel Syntax -=================================== - -'as' now supports assembly using Intel assembler syntax. -'.intel_syntax' selects Intel mode, and '.att_syntax' switches back to -the usual AT&T mode for compatibility with the output of 'gcc'. Either -of these directives may have an optional argument, 'prefix', or -'noprefix' specifying whether registers require a '%' prefix. AT&T -System V/386 assembler syntax is quite different from Intel syntax. We -mention these differences because almost all 80386 documents use 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. Note that instructions with more than - one source operand, such as the 'enter' instruction, do _not_ have - reversed order. *note i386-Bugs::. - - * In AT&T syntax the size of memory operands is determined from the - last character of the instruction mnemonic. Mnemonic suffixes of - 'b', 'w', 'l' and 'q' specify byte (8-bit), word (16-bit), long - (32-bit) and quadruple word (64-bit) memory references. Intel - syntax accomplishes this by prefixing memory operands (_not_ the - instruction mnemonics) with 'byte ptr', 'word ptr', 'dword ptr' and - 'qword 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. - -9.3 Instruction Naming -====================== - -Instruction mnemonics are suffixed with one character modifiers which -specify the size of operands. The letters 'b', 'w', 'l' and 'q' specify -byte, word, long and quadruple word operands. If no suffix is specified -by an instruction 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 mnemonic suffix implies -long operand size. (This incompatibility does not affect compiler -output since compilers always explicitly specify the mnemonic suffix.) - - Almost all instructions 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 instruction mnemonic 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 instruction -mnemonic 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), 'wl' (from word to -long), 'bq' (from byte to quadruple word), 'wq' (from word to quadruple -word), and 'lq' (from long to quadruple word). - - 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', - - * 'cdqe' -- sign-extend dword in '%eax' to quad in '%rax' (x86-64 - only), - - * 'cqo' -- sign-extend quad in '%rax' to octuple in '%rdx:%rax' - (x86-64 only), - -are called 'cbtw', 'cwtl', 'cwtd', 'cltd', 'cltq', and 'cqto' 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. - -9.4 Register Naming -=================== - -Register operands are always prefixed 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)'. These registers are overloaded by 8 MMX registers - '%mm0', '%mm1', '%mm2', '%mm3', '%mm4', '%mm5', '%mm6' and '%mm7'. - - * the 8 SSE registers registers '%xmm0', '%xmm1', '%xmm2', '%xmm3', - '%xmm4', '%xmm5', '%xmm6' and '%xmm7'. - - The AMD x86-64 architecture extends the register set by: - - * enhancing the 8 32-bit registers to 64-bit: '%rax' (the - accumulator), '%rbx', '%rcx', '%rdx', '%rdi', '%rsi', '%rbp' (the - frame pointer), '%rsp' (the stack pointer) - - * the 8 extended registers '%r8'-'%r15'. - - * the 8 32-bit low ends of the extended registers: '%r8d'-'%r15d' - - * the 8 16-bit low ends of the extended registers: '%r8w'-'%r15w' - - * the 8 8-bit low ends of the extended registers: '%r8b'-'%r15b' - - * the 4 8-bit registers: '%sil', '%dil', '%bpl', '%spl'. - - * the 8 debug registers: '%db8'-'%db15'. - - * the 8 SSE registers: '%xmm8'-'%xmm15'. - -9.5 Instruction Prefixes -======================== - -Instruction prefixes are used to modify the following instruction. They -are used to repeat string instructions, to provide section overrides, to -perform bus lock operations, and to change operand and address sizes. -(Most instructions that normally operate on 32-bit operands will use -16-bit operands if the instruction has an "operand size" prefix.) -Instruction prefixes are best written on the same line as the -instruction they act upon. For example, the 'scas' (scan string) -instruction is repeated with: - - repne scas %es:(%edi),%al - - You may also place prefixes on the lines immediately preceding the -instruction, but this circumvents checks that 'as' does with prefixes, -and will not work with all prefixes. - - Here is a list of instruction 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, while 'data32' - and 'addr32' change 16-bit ones (in a '.code16' section) into - 32-bit operands/addresses. These prefixes _must_ appear on the - same line of code as the instruction they modify. For example, in - a 16-bit '.code16' section, you might write: - - addr32 jmpl *(%ebx) - - * 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 ('%cx' times if the - current address size is 16-bits). - * The 'rex' family of prefixes is used by x86-64 to encode extensions - to i386 instruction set. The 'rex' prefix has four bits -- an - operand size overwrite ('64') used to change operand size from - 32-bit to 64-bit and X, Y and Z extensions bits used to extend the - register set. - - You may write the 'rex' prefixes directly. The 'rex64xyz' - instruction emits 'rex' prefix with all the bits set. By omitting - the '64', 'x', 'y' or 'z' you may write other prefixes as well. - Normally, there is no need to write the prefixes explicitly, since - gas will automatically generate them based on the instruction - operands. - -9.6 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_ be -preceded by a '%'. If you specify a section override which coincides -with the default section register, 'as' does _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' always chooses PC -relative addressing for jump/call labels. - - Any instruction that has a memory operand, but no register operand, -_must_ specify its size (byte, word, long, or quadruple) with an -instruction mnemonic suffix ('b', 'w', 'l' or 'q', respectively). - - The x86-64 architecture adds an RIP (instruction pointer relative) -addressing. This addressing mode is specified by using 'rip' as a base -register. Only constant offsets are valid. For example: - -AT&T: '1234(%rip)', Intel: '[rip + 1234]' - Points to the address 1234 bytes past the end of the current - instruction. - -AT&T: 'symbol(%rip)', Intel: '[rip + symbol]' - Points to the 'symbol' in RIP relative way, this is shorter than - the default absolute addressing. - - Other addressing modes remain unchanged in x86-64 architecture, -except registers used are 64-bit instead of 32-bit. - -9.7 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 displacement is used. We do not support word -(16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump -instruction with the 'data16' instruction prefix), since the 80386 -insists upon masking '%eip' to 16 bits after the word displacement is -added. (See also *note i386-Arch::) - - Note that the 'jcxz', 'jecxz', 'loop', 'loopz', 'loope', 'loopnz' and -'loopne' instructions only come in byte displacements, so that if you -use these instructions ('gcc' does not use them) you may get an error -message (and 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: - -9.8 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 instruction mnemonic suffix and a constructor associated with it. -Instruction mnemonic suffixes specify the operand's data type. -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 instruction mnemonic suffixes 's', 'l', and 't'. 't' stands for - 80-bit (ten byte) real. The 80387 only supports this format via - the 'fldt' (load 80-bit real to stack top) and 'fstpt' (store - 80-bit 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 - instruction mnemonic suffixes are 's' (single), 'l' (long), and 'q' - (quad). As with the 80-bit 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 should not use instruction mnemonic -suffixes. 'fstl %st, %st(1)' will give a warning, and be assembled as -if you wrote 'fst %st, %st(1)', since all register to register -operations use 80-bit floating point operands. (Contrast this with -'fstl %st, mem', which converts '%st' from 80-bit to 64-bit floating -point format, then stores the result in the 4 byte location 'mem') - -9.9 Intel's MMX and AMD's 3DNow! SIMD Operations -================================================ - -'as' supports Intel's MMX instruction set (SIMD instructions for integer -data), available on Intel's Pentium MMX processors and Pentium II -processors, AMD's K6 and K6-2 processors, Cyrix' M2 processor, and -probably others. It also supports AMD's 3DNow! instruction set (SIMD -instructions for 32-bit floating point data) available on AMD's K6-2 -processor and possibly others in the future. - - Currently, 'as' does not support Intel's floating point SIMD, Katmai -(KNI). - - The eight 64-bit MMX operands, also used by 3DNow!, are called -'%mm0', '%mm1', ... '%mm7'. They contain eight 8-bit integers, four -16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit -floating point values. The MMX registers cannot be used at the same -time as the floating point stack. - - See Intel and AMD documentation, keeping in mind that the operand -order in instructions is reversed from the Intel syntax. - -9.10 Writing 16-bit Code -======================== - -While 'as' normally writes only "pure" 32-bit i386 code or 64-bit x86-64 -code depending on the default configuration, it also supports writing -code to run in real mode or in 16-bit protected mode code segments. To -do this, put a '.code16' or '.code16gcc' directive before the assembly -language instructions to be run in 16-bit mode. You can switch 'as' -back to writing normal 32-bit code with the '.code32' directive. - - '.code16gcc' provides experimental support for generating 16-bit code -from gcc, and differs from '.code16' in that 'call', 'ret', 'enter', -'leave', 'push', 'pop', 'pusha', 'popa', 'pushf', and 'popf' -instructions default to 32-bit size. This is so that the stack pointer -is manipulated in the same way over function calls, allowing access to -function parameters at the same stack offsets as in 32-bit mode. -'.code16gcc' also automatically adds address size prefixes where -necessary to use the 32-bit addressing modes that gcc generates. - - The code which 'as' generates in 16-bit mode will not necessarily run -on a 16-bit pre-80386 processor. To write code that runs on such a -processor, you must refrain from using _any_ 32-bit constructs which -require 'as' to output address or operand size prefixes. - - Note that writing 16-bit code instructions by explicitly specifying a -prefix or an instruction mnemonic suffix within a 32-bit code section -generates different machine instructions than those generated for a -16-bit code segment. In a 32-bit code section, the following code -generates the machine opcode bytes '66 6a 04', which pushes the value -'4' onto the stack, decrementing '%esp' by 2. - - pushw $4 - - The same code in a 16-bit code section would generate the machine -opcode bytes '6a 04' (i.e., without the operand size prefix), which is -correct since the processor default operand size is assumed to be 16 -bits in a 16-bit code section. - -9.11 AT&T Syntax bugs -===================== - -The UnixWare assembler, and probably other AT&T derived ix86 Unix -assemblers, generate floating point instructions with reversed source -and destination registers in certain cases. Unfortunately, gcc and -possibly many other programs use this reversed syntax, so we're stuck -with it. - - For example - - fsub %st,%st(3) -results in '%st(3)' being updated to '%st - %st(3)' rather than the -expected '%st(3) - %st'. This happens with all the non-commutative -arithmetic floating point operations with two register operands where -the source register is '%st' and the destination register is '%st(i)'. - -9.12 Specifying CPU Architecture -================================ - -'as' may be told to assemble for a particular CPU (sub-)architecture -with the '.arch CPU_TYPE' directive. This directive enables a warning -when gas detects an instruction that is not supported on the CPU -specified. The choices for CPU_TYPE are: - -'i8086' 'i186' 'i286' 'i386' -'i486' 'i586' 'i686' 'pentium' -'pentiumpro' 'pentiumii' 'pentiumiii' 'pentium4' -'prescott' 'nocona' 'core' 'core2' -'amdfam10' -'k6' 'athlon' 'sledgehammer' 'k8' -'.mmx' '.sse' '.sse2' '.sse3' -'.ssse3' '.sse4.1' '.sse4.2' '.sse4' -'.sse4a' '.3dnow' '.3dnowa' '.padlock' -'.pacifica' '.svme' '.abm' - - Apart from the warning, there are only two other effects on 'as' -operation; Firstly, if you specify a CPU other than 'i486', then shift -by one instructions such as 'sarl $1, %eax' will automatically use a two -byte opcode sequence. The larger three byte opcode sequence is used on -the 486 (and when no architecture is specified) because it executes -faster on the 486. Note that you can explicitly request the two byte -opcode by writing 'sarl %eax'. Secondly, if you specify 'i8086', -'i186', or 'i286', _and_ '.code16' or '.code16gcc' then byte offset -conditional jumps will be promoted when necessary to a two instruction -sequence consisting of a conditional jump of the opposite sense around -an unconditional jump to the target. - - Following the CPU architecture (but not a sub-architecture, which are -those starting with a dot), you may specify 'jumps' or 'nojumps' to -control automatic promotion of conditional jumps. 'jumps' is the -default, and enables jump promotion; All external jumps will be of the -long variety, and file-local jumps will be promoted as necessary. -(*note i386-Jumps::) 'nojumps' leaves external conditional jumps as byte -offset jumps, and warns about file-local conditional jumps that 'as' -promotes. Unconditional jumps are treated as for 'jumps'. - - For example - - .arch i8086,nojumps - -9.13 Notes -========== - -There is some trickery concerning the 'mul' and 'imul' instructions that -deserves mention. The 16-, 32-, 64- and 128-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'. - -10 IA-64 Dependent Features -*************************** - -10.1 Options -============ - -'-mconstant-gp' - This option instructs the assembler to mark the resulting object - file as using the "constant GP" model. With this model, it is - assumed that the entire program uses a single global pointer (GP) - value. Note that this option does not in any fashion affect the - machine code emitted by the assembler. All it does is turn on the - EF_IA_64_CONS_GP flag in the ELF file header. - -'-mauto-pic' - This option instructs the assembler to mark the resulting object - file as using the "constant GP without function descriptor" data - model. This model is like the "constant GP" model, except that it - additionally does away with function descriptors. What this means - is that the address of a function refers directly to the function's - code entry-point. Normally, such an address would refer to a - function descriptor, which contains both the code entry-point and - the GP-value needed by the function. Note that this option does - not in any fashion affect the machine code emitted by the - assembler. All it does is turn on the EF_IA_64_NOFUNCDESC_CONS_GP - flag in the ELF file header. - -'-milp32' -'-milp64' -'-mlp64' -'-mp64' - These options select the data model. The assembler defaults to - '-mlp64' (LP64 data model). - -'-mle' -'-mbe' - These options select the byte order. The '-mle' option selects - little-endian byte order (default) and '-mbe' selects big-endian - byte order. Note that IA-64 machine code always uses little-endian - byte order. - -'-mtune=itanium1' -'-mtune=itanium2' - Tune for a particular IA-64 CPU, ITANIUM1 or ITANIUM2. The default - is ITANIUM2. - -'-munwind-check=warning' -'-munwind-check=error' - These options control what the assembler will do when performing - consistency checks on unwind directives. '-munwind-check=warning' - will make the assembler issue a warning when an unwind directive - check fails. This is the default. '-munwind-check=error' will - make the assembler issue an error when an unwind directive check - fails. - -'-mhint.b=ok' -'-mhint.b=warning' -'-mhint.b=error' - These options control what the assembler will do when the 'hint.b' - instruction is used. '-mhint.b=ok' will make the assembler accept - 'hint.b'. '-mint.b=warning' will make the assembler issue a - warning when 'hint.b' is used. '-mhint.b=error' will make the - assembler treat 'hint.b' as an error, which is the default. - -'-x' -'-xexplicit' - These options turn on dependency violation checking. - -'-xauto' - This option instructs the assembler to automatically insert stop - bits where necessary to remove dependency violations. This is the - default mode. - -'-xnone' - This option turns off dependency violation checking. - -'-xdebug' - This turns on debug output intended to help tracking down bugs in - the dependency violation checker. - -'-xdebugn' - This is a shortcut for -xnone -xdebug. - -'-xdebugx' - This is a shortcut for -xexplicit -xdebug. - -10.2 Syntax -=========== - -The assembler syntax closely follows the IA-64 Assembly Language -Reference Guide. - -10.2.1 Special Characters -------------------------- - -'//' is the line comment token. - - ';' can be used instead of a newline to separate statements. - -10.2.2 Register Names ---------------------- - -The 128 integer registers are referred to as 'rN'. The 128 -floating-point registers are referred to as 'fN'. The 128 application -registers are referred to as 'arN'. The 128 control registers are -referred to as 'crN'. The 64 one-bit predicate registers are referred -to as 'pN'. The 8 branch registers are referred to as 'bN'. In -addition, the assembler defines a number of aliases: 'gp' ('r1'), 'sp' -('r12'), 'rp' ('b0'), 'ret0' ('r8'), 'ret1' ('r9'), 'ret2' ('r10'), -'ret3' ('r9'), 'fargN' ('f8+N'), and 'fretN' ('f8+N'). - - For convenience, the assembler also defines aliases for all named -application and control registers. For example, 'ar.bsp' refers to the -register backing store pointer ('ar17'). Similarly, 'cr.eoi' refers to -the end-of-interrupt register ('cr67'). - -10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names ------------------------------------------------------- - -The assembler defines bit masks for each of the bits in the IA-64 -processor status register. For example, 'psr.ic' corresponds to a value -of 0x2000. These masks are primarily intended for use with the -'ssm'/'sum' and 'rsm'/'rum' instructions, but they can be used anywhere -else where an integer constant is expected. - -10.3 Opcodes -============ - -For detailed information on the IA-64 machine instruction set, see the -IA-64 Architecture Handbook -(http://developer.intel.com/design/itanium/arch_spec.htm). - -11 MIPS Dependent Features -************************** - -GNU 'as' for MIPS architectures supports several different MIPS -processors, and MIPS ISA levels I through V, MIPS32, and MIPS64. For -information about the MIPS instruction set, see 'MIPS RISC -Architecture', by Kane and Heindrich (Prentice-Hall). For an overview -of MIPS assembly conventions, see "Appendix D: Assembly Language -Programming" in the same work. - -11.1 Assembler options -====================== - -The MIPS configurations of GNU 'as' support these special options: - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format. The default value is 8. - -'-EB' -'-EL' - Any MIPS configuration of 'as' can select big-endian or - little-endian output at run time (unlike the other GNU development - tools, which must be configured for one or the other). Use '-EB' - to select big-endian output, and '-EL' for little-endian. - -'-KPIC' - Generate SVR4-style PIC. This option tells the assembler to - generate SVR4-style position-independent macro expansions. It also - tells the assembler to mark the output file as PIC. - -'-mvxworks-pic' - Generate VxWorks PIC. This option tells the assembler to generate - VxWorks-style position-independent macro expansions. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' corresponds to the R2000 and R3000 processors, - '-mips2' to the R6000 processor, '-mips3' to the R4000 processor, - and '-mips4' to the R8000 and R10000 processors. '-mips5', - '-mips32', '-mips32r2', '-mips64', and '-mips64r2' correspond to - generic MIPS V, MIPS32, MIPS32 RELEASE 2, MIPS64, and MIPS64 - RELEASE 2 ISA processors, respectively. You can also switch - instruction sets during the assembly; see *note Directives to - override the ISA level: MIPS ISA. - -'-mgp32' -'-mfp32' - Some macros have different expansions for 32-bit and 64-bit - registers. The register sizes are normally inferred from the ISA - and ABI, but these flags force a certain group of registers to be - treated as 32 bits wide at all times. '-mgp32' controls the size - of general-purpose registers and '-mfp32' controls the size of - floating-point registers. - - The '.set gp=32' and '.set fp=32' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - - On some MIPS variants there is a 32-bit mode flag; when this flag - is set, 64-bit instructions generate a trap. Also, some 32-bit - OSes only save the 32-bit registers on a context switch, so it is - essential never to use the 64-bit registers. - -'-mgp64' -'-mfp64' - Assume that 64-bit registers are available. This is provided in - the interests of symmetry with '-mgp32' and '-mfp32'. - - The '.set gp=64' and '.set fp=64' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extensions to the MIPS32 instruction set, - which provides a number of new instructions which target smartcard - and cryptographic applications. This is equivalent to putting - '.set smartmips' at the start of the assembly file. - '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-mno-dspr2' - Generate code for the DSP Release 2 Application Specific Extension. - This option implies -mdsp. This tells the assembler to accept DSP - Release 2 instructions. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'-mfix7000' -'-mno-fix7000' - Cause nops to be inserted if the read of the destination register - of an mfhi or mflo instruction occurs in the following two - instructions. - -'-mfix-vr4120' -'-no-mfix-vr4120' - Insert nops to work around certain VR4120 errata. This option is - intended to be used on GCC-generated code: it is not designed to - catch all problems in hand-written assembler code. - -'-mfix-vr4130' -'-no-mfix-vr4130' - Insert nops to work around the VR4130 'mflo'/'mfhi' errata. - -'-m4010' -'-no-m4010' - Generate code for the LSI R4010 chip. This tells the assembler to - accept the R4010 specific instructions ('addciu', 'ffc', etc.), and - to not schedule 'nop' instructions around accesses to the 'HI' and - 'LO' registers. '-no-m4010' turns off this option. - -'-m4650' -'-no-m4650' - Generate code for the MIPS R4650 chip. This tells the assembler to - accept the 'mad' and 'madu' instruction, and to not schedule 'nop' - instructions around accesses to the 'HI' and 'LO' registers. - '-no-m4650' turns off this option. - -'-m3900' -'-no-m3900' -'-m4100' -'-no-m4100' - For each option '-mNNNN', generate code for the MIPS RNNNN chip. - This tells the assembler to accept instructions specific to that - chip, and to schedule for that chip's hazards. - -'-march=CPU' - Generate code for a particular MIPS cpu. It is exactly equivalent - to '-mCPU', except that there are more value of CPU understood. - Valid CPU value are: - - 2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, - vr4181, 4300, 4400, 4600, 4650, 5000, rm5200, rm5230, rm5231, - rm5261, rm5721, vr5400, vr5500, 6000, rm7000, 8000, rm9000, - 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 4kep, 4ksd, - m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, - 34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. Valid CPU values are - identical to '-march=CPU'. - -'-mabi=ABI' - Record which ABI the source code uses. The recognized arguments - are: '32', 'n32', 'o64', '64' and 'eabi'. - -'-msym32' -'-mno-sym32' - Equivalent to adding '.set sym32' or '.set nosym32' to the - beginning of the assembler input. *Note MIPS symbol sizes::. - -'-nocpp' - This option is ignored. It is accepted for command-line - compatibility with other assemblers, which use it to turn off C - style preprocessing. With GNU 'as', there is no need for '-nocpp', - because the GNU assembler itself never runs the C preprocessor. - -'--construct-floats' -'--no-construct-floats' - The '--no-construct-floats' option disables the construction of - double width floating point constants by loading the two halves of - the value into the two single width floating point registers that - make up the double width register. This feature is useful if the - processor support the FR bit in its status register, and this bit - is known (by the programmer) to be set. This bit prevents the - aliasing of the double width register by the single width - registers. - - By default '--construct-floats' is selected, allowing construction - of these floating point constants. - -'--trap' -'--no-break' - 'as' automatically macro expands certain division and - multiplication instructions to check for overflow and division by - zero. This option causes 'as' to generate code to take a trap - exception rather than a break exception when an error is detected. - The trap instructions are only supported at Instruction Set - Architecture level 2 and higher. - -'--break' -'--no-trap' - Generate code to take a break exception rather than a trap - exception when an error is detected. This is the default. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. Off by default on IRIX, on - elsewhere. - -'-mshared' -'-mno-shared' - When generating code using the Unix calling conventions (selected - by '-KPIC' or '-mcall_shared'), gas will normally generate code - which can go into a shared library. The '-mno-shared' option tells - gas to generate code which uses the calling convention, but can not - go into a shared library. The resulting code is slightly more - efficient. This option only affects the handling of the '.cpload' - and '.cpsetup' pseudo-ops. - -11.2 MIPS ECOFF object code -=========================== - -Assembling for a MIPS ECOFF target supports some additional sections -besides the usual '.text', '.data' and '.bss'. The additional sections -are '.rdata', used for read-only data, '.sdata', used for small data, -and '.sbss', used for small common objects. - - When assembling for ECOFF, the assembler uses the '$gp' ('$28') -register to form the address of a "small object". Any object in the -'.sdata' or '.sbss' sections is considered "small" in this sense. For -external objects, or for objects in the '.bss' section, you can use the -'gcc' '-G' option to control the size of objects addressed via '$gp'; -the default value is 8, meaning that a reference to any object eight -bytes or smaller uses '$gp'. Passing '-G 0' to 'as' prevents it from -using the '$gp' register on the basis of object size (but the assembler -uses '$gp' for objects in '.sdata' or 'sbss' in any case). The size of -an object in the '.bss' section is set by the '.comm' or '.lcomm' -directive that defines it. The size of an external object may be set -with the '.extern' directive. For example, '.extern sym,4' declares -that the object at 'sym' is 4 bytes in length, whie leaving 'sym' -otherwise undefined. - - Using small ECOFF objects requires linker support, and assumes that -the '$gp' register is correctly initialized (normally done automatically -by the startup code). MIPS ECOFF assembly code must not modify the -'$gp' register. - -11.3 Directives for debugging information -========================================= - -MIPS ECOFF 'as' supports several directives used for generating -debugging information which are not support by traditional MIPS -assemblers. These are '.def', '.endef', '.dim', '.file', '.scl', -'.size', '.tag', '.type', '.val', '.stabd', '.stabn', and '.stabs'. The -debugging information generated by the three '.stab' directives can only -be read by GDB, not by traditional MIPS debuggers (this enhancement is -required to fully support C++ debugging). These directives are -primarily used by compilers, not assembly language programmers! - -11.4 Directives to override the size of symbols -=============================================== - -The n64 ABI allows symbols to have any 64-bit value. Although this -provides a great deal of flexibility, it means that some macros have -much longer expansions than their 32-bit counterparts. For example, the -non-PIC expansion of 'dla $4,sym' is usually: - - lui $4,%highest(sym) - lui $1,%hi(sym) - daddiu $4,$4,%higher(sym) - daddiu $1,$1,%lo(sym) - dsll32 $4,$4,0 - daddu $4,$4,$1 - - whereas the 32-bit expansion is simply: - - lui $4,%hi(sym) - daddiu $4,$4,%lo(sym) - - n64 code is sometimes constructed in such a way that all symbolic -constants are known to have 32-bit values, and in such cases, it's -preferable to use the 32-bit expansion instead of the 64-bit expansion. - - You can use the '.set sym32' directive to tell the assembler that, -from this point on, all expressions of the form 'SYMBOL' or 'SYMBOL + -OFFSET' have 32-bit values. For example: - - .set sym32 - dla $4,sym - lw $4,sym+16 - sw $4,sym+0x8000($4) - - will cause the assembler to treat 'sym', 'sym+16' and 'sym+0x8000' as -32-bit values. The handling of non-symbolic addresses is not affected. - - The directive '.set nosym32' ends a '.set sym32' block and reverts to -the normal behavior. It is also possible to change the symbol size -using the command-line options '-msym32' and '-mno-sym32'. - - These options and directives are always accepted, but at present, -they have no effect for anything other than n64. - -11.5 Directives to override the ISA level -========================================= - -GNU 'as' supports an additional directive to change the MIPS Instruction -Set Architecture level on the fly: '.set mipsN'. N should be a number -from 0 to 5, or 32, 32r2, 64 or 64r2. The values other than 0 make the -assembler accept instructions for the corresponding ISA level, from that -point on in the assembly. '.set mipsN' affects not only which -instructions are permitted, but also how certain macros are expanded. -'.set mips0' restores the ISA level to its original level: either the -level you selected with command line options, or the default for your -configuration. You can use this feature to permit specific MIPS3 -instructions while assembling in 32 bit mode. Use this directive with -care! - - The '.set arch=CPU' directive provides even finer control. It -changes the effective CPU target and allows the assembler to use -instructions specific to a particular CPU. All CPUs supported by the -'-march' command line option are also selectable by this directive. The -original value is restored by '.set arch=default'. - - The directive '.set mips16' puts the assembler into MIPS 16 mode, in -which it will assemble instructions for the MIPS 16 processor. Use -'.set nomips16' to return to normal 32 bit mode. - - Traditional MIPS assemblers do not support this directive. - -11.6 Directives for extending MIPS 16 bit instructions -====================================================== - -By default, MIPS 16 instructions are automatically extended to 32 bits -when necessary. The directive '.set noautoextend' will turn this off. -When '.set noautoextend' is in effect, any 32 bit instruction must be -explicitly extended with the '.e' modifier (e.g., 'li.e $4,1000'). The -directive '.set autoextend' may be used to once again automatically -extend instructions when necessary. - - This directive is only meaningful when in MIPS 16 mode. Traditional -MIPS assemblers do not support this directive. - -11.7 Directive to mark data as an instruction -============================================= - -The '.insn' directive tells 'as' that the following data is actually -instructions. This makes a difference in MIPS 16 mode: when loading the -address of a label which precedes instructions, 'as' automatically adds -1 to the value, so that jumping to the loaded address will do the right -thing. - -11.8 Directives to save and restore options -=========================================== - -The directives '.set push' and '.set pop' may be used to save and -restore the current settings for all the options which are controlled by -'.set'. The '.set push' directive saves the current settings on a -stack. The '.set pop' directive pops the stack and restores the -settings. - - These directives can be useful inside an macro which must change an -option such as the ISA level or instruction reordering but does not want -to change the state of the code which invoked the macro. - - Traditional MIPS assemblers do not support these directives. - -11.9 Directives to control generation of MIPS ASE instructions -============================================================== - -The directive '.set mips3d' makes the assembler accept instructions from -the MIPS-3D Application Specific Extension from that point on in the -assembly. The '.set nomips3d' directive prevents MIPS-3D instructions -from being accepted. - - The directive '.set smartmips' makes the assembler accept -instructions from the SmartMIPS Application Specific Extension to the -MIPS32 ISA from that point on in the assembly. The '.set nosmartmips' -directive prevents SmartMIPS instructions from being accepted. - - The directive '.set mdmx' makes the assembler accept instructions -from the MDMX Application Specific Extension from that point on in the -assembly. The '.set nomdmx' directive prevents MDMX instructions from -being accepted. - - The directive '.set dsp' makes the assembler accept instructions from -the DSP Release 1 Application Specific Extension from that point on in -the assembly. The '.set nodsp' directive prevents DSP Release 1 -instructions from being accepted. - - The directive '.set dspr2' makes the assembler accept instructions -from the DSP Release 2 Application Specific Extension from that point on -in the assembly. This dirctive implies '.set dsp'. The '.set nodspr2' -directive prevents DSP Release 2 instructions from being accepted. - - The directive '.set mt' makes the assembler accept instructions from -the MT Application Specific Extension from that point on in the -assembly. The '.set nomt' directive prevents MT instructions from being -accepted. - - Traditional MIPS assemblers do not support these directives. - -12 PowerPC Dependent Features -***************************** - -12.1 Options -============ - -The PowerPC chip family includes several successive levels, using the -same core instruction set, but including a few additional instructions -at each level. There are exceptions to this however. For details on -what instructions each variant supports, please see the chip's -architecture reference manual. - - The following table lists all available PowerPC options. - -'-mpwrx | -mpwr2' - Generate code for POWER/2 (RIOS2). - -'-mpwr' - Generate code for POWER (RIOS1) - -'-m601' - Generate code for PowerPC 601. - -'-mppc, -mppc32, -m603, -m604' - Generate code for PowerPC 603/604. - -'-m403, -m405' - Generate code for PowerPC 403/405. - -'-m440' - Generate code for PowerPC 440. BookE and some 405 instructions. - -'-m7400, -m7410, -m7450, -m7455' - Generate code for PowerPC 7400/7410/7450/7455. - -'-mppc64, -m620' - Generate code for PowerPC 620/625/630. - -'-me500, -me500x2' - Generate code for Motorola e500 core complex. - -'-mspe' - Generate code for Motorola SPE instructions. - -'-mppc64bridge' - Generate code for PowerPC 64, including bridge insns. - -'-mbooke64' - Generate code for 64-bit BookE. - -'-mbooke, mbooke32' - Generate code for 32-bit BookE. - -'-me300' - Generate code for PowerPC e300 family. - -'-maltivec' - Generate code for processors with AltiVec instructions. - -'-mpower4' - Generate code for Power4 architecture. - -'-mpower5' - Generate code for Power5 architecture. - -'-mpower6' - Generate code for Power6 architecture. - -'-mcell' - Generate code for Cell Broadband Engine architecture. - -'-mcom' - Generate code Power/PowerPC common instructions. - -'-many' - Generate code for any architecture (PWR/PWRX/PPC). - -'-mregnames' - Allow symbolic names for registers. - -'-mno-regnames' - Do not allow symbolic names for registers. - -'-mrelocatable' - Support for GCC's -mrelocatable option. - -'-mrelocatable-lib' - Support for GCC's -mrelocatable-lib option. - -'-memb' - Set PPC_EMB bit in ELF flags. - -'-mlittle, -mlittle-endian' - Generate code for a little endian machine. - -'-mbig, -mbig-endian' - Generate code for a big endian machine. - -'-msolaris' - Generate code for Solaris. - -'-mno-solaris' - Do not generate code for Solaris. - -12.2 PowerPC Assembler Directives -================================= - -A number of assembler directives are available for PowerPC. The -following table is far from complete. - -'.machine "string"' - This directive allows you to change the machine for which code is - generated. '"string"' may be any of the -m cpu selection options - (without the -m) enclosed in double quotes, '"push"', or '"pop"'. - '.machine "push"' saves the currently selected cpu, which may be - restored with '.machine "pop"'. - -13 SPARC Dependent Features -*************************** - -13.1 Options -============ - -The SPARC chip family includes several successive levels, using the same -core instruction set, but including a few additional instructions at -each level. There are exceptions to this however. For details on what -instructions each variant supports, please see the chip's architecture -reference manual. - - 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. - - If not configured for SPARC v9 ('sparc64-*-*') GAS will not bump -passed sparclite by default, an option must be passed to enable the v9 -instructions. - - GAS treats sparclite as being compatible with v8, unless an -architecture is explicitly requested. SPARC v9 is always incompatible -with sparclite. - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - 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 an incompatible or higher level. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. - - '-Av9' and '-Av9a' select a 64 bit environment and are not - available unless GAS is explicitly configured with 64 bit - environment support. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn whenever it is necessary to switch to another level. If an - architecture level is explicitly requested, GAS will not issue - warnings until that level is reached, and will then bump the level - as required (except between incompatible levels). - -'-32 | -64' - Select the word size, either 32 bits or 64 bits. These options are - only available with the ELF object file format, and require that - the necessary BFD support has been included. - -13.2 Enforcing aligned data -=========================== - -SPARC GAS normally permits data to be misaligned. For example, it -permits the '.long' pseudo-op to be used on a byte boundary. However, -the native SunOS and Solaris assemblers issue an error when they see -misaligned data. - - You can use the '--enforce-aligned-data' option to make SPARC GAS -also issue an error about misaligned data, just as the SunOS and Solaris -assemblers do. - - The '--enforce-aligned-data' option is not the default because gcc -issues misaligned data pseudo-ops when it initializes certain packed -data structures (structures defined using the 'packed' attribute). You -may have to assemble with GAS in order to initialize packed data -structures in your own code. - -13.3 Floating Point -=================== - -The Sparc uses IEEE floating-point numbers. - -13.4 Sparc Machine Directives -============================= - -The Sparc version of 'as' supports the following additional machine -directives: - -'.align' - This must be followed by the desired alignment in bytes. - -'.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'. - -'.nword' - On the Sparc, the '.nword' directive produces native word sized - value, ie. if assembling with -32 it is equivalent to '.word', if - assembling with -64 it is equivalent to '.xword'. - -'.proc' - This directive is ignored. Any text following it on the same line - is also ignored. - -'.register' - This directive declares use of a global application or system - register. It must be followed by a register name %g2, %g3, %g6 or - %g7, comma and the symbol name for that register. If symbol name - is '#scratch', it is a scratch register, if it is '#ignore', it - just suppresses any errors about using undeclared global register, - but does not emit any information about it into the object file. - This can be useful e.g. if you save the register before use and - restore it after. - -'.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. - -'.xword' - On the Sparc V9 processor, the '.xword' directive produces 64 bit - values. - -14 Reporting Bugs -***************** - -Your bug reports play an essential role in making 'as' reliable. - - Reporting a bug may help you by bringing a solution to your problem, -or it may not. But in any case the principal function of a bug report -is to help the entire community by making the next version of 'as' work -better. Bug reports are your contribution to the maintenance of 'as'. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -14.1 Have You Found a Bug? -========================== - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the assembler gets a fatal signal, for any input whatever, that - is a 'as' bug. Reliable assemblers never crash. - - * If 'as' produces an error message for valid input, that is a bug. - - * If 'as' does not produce an error message for invalid input, that - is a bug. However, you should note that your idea of "invalid - input" might be our idea of "an extension" or "support for - traditional practice". - - * If you are an experienced user of assemblers, your suggestions for - improvement of 'as' are welcome in any case. - -14.2 How to Report Bugs -======================= - -A number of companies and individuals offer support for GNU products. -If you obtained 'as' from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. - - The fundamental principle of reporting bugs usefully is this: *report -all the facts*. If you are not sure whether to state a fact or leave it -out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of a symbol you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is -a stray memory reference which happens to fetch from the location where -that name is stored in memory; perhaps, if the name were different, the -contents of that location would fool the assembler into doing the right -thing despite the bug. Play it safe and give a specific, complete -example. That is the easiest thing for you to do, and the most helpful. - - Keep in mind that the purpose of a bug report is to enable us to fix -the bug if it is new to us. Therefore, always write your bug reports on -the assumption that the bug has not been reported previously. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" This cannot help us fix a bug, so it is basically useless. We -respond by asking for enough details to enable us to investigate. You -might as well expedite matters by sending them to begin with. - - To enable us to fix the bug, you should include all these things: - - * The version of 'as'. 'as' announces it if you start it with the - '--version' argument. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of 'as'. - - * Any patches you may have applied to the 'as' source. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile 'as'--e.g. - "'gcc-2.7'". - - * The command arguments you gave the assembler to assemble your - example and observe the bug. To guarantee you will not omit - something important, list them all. A copy of the Makefile (or the - output from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input file that will reproduce the bug. If the bug is - observed when the assembler is invoked via a compiler, send the - assembler source, not the high level language source. Most - compilers will produce the assembler source when run with the '-S' - option. If you are using 'gcc', use the options '-v --save-temps'; - this will save the assembler source in a file with an extension of - '.s', and also show you exactly how 'as' is being run. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that 'as' gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - Even if the problem you experience is a fatal signal, you should - still say so explicitly. Suppose something strange is going on, - such as, your copy of 'as' is out of sync, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the 'as' source, send us context - diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. - Always send diffs from the old file to the new file. If you even - discuss something in the 'as' source, refer to it by context, not - by line number. - - The line numbers in our development sources will not match those in - your sources. Your line numbers would convey no useful information - to us. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - Often people who encounter a bug spend a lot of time investigating - which changes to the input file will make the bug go away and which - changes will not affect it. - - This is often time consuming and not very useful, because the way - we will find the bug is by running a single example under the - debugger with breakpoints, not by pure deduction from a series of - examples. We recommend that you save your time for something else. - - Of course, if you can find a simpler example to report _instead_ of - the original one, that is a convenience for us. Errors in the - output will be easier to spot, running under the debugger will take - less time, and so on. - - However, simplification is not vital; if you do not want to do - this, report the bug anyway and send us the entire test case you - used. - - * A patch for the bug. - - A patch for the bug does help us if it is a good one. But do not - omit the necessary information, such as the test case, on the - assumption that a patch is all we need. We might see problems with - your patch and decide to fix the problem another way, or we might - not understand it at all. - - Sometimes with a program as complicated as 'as' it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify that - the bug is fixed. - - And if we cannot understand what bug you are trying to fix, or why - your patch should be an improvement, we will not install it. A - test case will help us to understand. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - -15 Acknowledgements -******************* - -If you have contributed to GAS 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 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 back -ends (including heavy rewrite, testing, an integration of the coff and -b.out back ends), 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 and cpu32, did 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 Renesas H8/300 processors (tc-z8k, -tc-h8300), 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 -directives. 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 proverbial one-bit fix. - - Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax -for the 68k, completed support for some COFF targets (68k, i386 SVR3, -and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the -initial RS/6000 and PowerPC assembler, and made a few other minor -patches. - - Steve Chamberlain made GAS able to generate listings. - - Hewlett-Packard contributed support for the HP9000/300. - - Jeff Law wrote GAS and BFD support for the native HPPA object format -(SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF -object formats). This work was supported by both the Center for -Software Science at the University of Utah and Cygnus Support. - - 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). - - Linas Vepstas added GAS support for the ESA/390 "IBM 370" -architecture. - - Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote -GAS and BFD support for openVMS/Alpha. - - Timothy Wall, Michael Hayes, and Greg Smart contributed to the -various tic* flavors. - - David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from -Tensilica, Inc. added support for Xtensa processors. - - 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 have 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 are not intentionally leaving anyone out. - -Appendix A GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000, 2003 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. We - recommend this License principally for works whose purpose is - instruction or reference. - - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (For example, if the - Document is in part a textbook of mathematics, a Secondary Section - may not explain any mathematics.) The relationship could be a - matter of historical connection with the subject or with related - matters, or of legal, commercial, philosophical, ethical or - political position regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed to - thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque." - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and standard-conforming - simple HTML designed for human modification. Opaque formats - include PostScript, PDF, proprietary formats that can be read and - edited only by proprietary word processors, SGML or XML for which - the DTD and/or processing tools are not generally available, and - the machine-generated HTML produced by some word processors for - output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow the - conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies of the Document numbering more than - 100, and the Document's license notice requires Cover Texts, you - must enclose the copies in covers that carry, clearly and legibly, - all these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the title - equally prominent and visible. You may add other material on the - covers in addition. Copying with changes limited to the covers, as - long as they preserve the title of the Document and satisfy these - conditions, can be treated as verbatim copying in other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a machine-readable - Transparent copy along with each Opaque copy, or state in or with - each Opaque copy a publicly-accessible computer-network location - containing a complete Transparent copy of the Document, free of - added material, which the general network-using public has access - to download anonymously at no charge using public-standard network - protocols. If you use the latter option, you must take reasonably - prudent steps, when you begin distribution of Opaque copies in - quantity, to ensure that this Transparent copy will remain thus - accessible at the stated location until at least one year after the - last time you distribute an Opaque copy (directly or through your - agents or retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of copies, - to give them a chance to provide you with an updated version of the - Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus licensing - distribution and modification of the Modified Version to whoever - possesses a copy of it. In addition, you must do these things in - the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the History - section of the Document). You may use the same title as a previous - version if the original publisher of that version gives permission. - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in the - Modified Version, together with at least five of the principal - authors of the Document (all of its principal authors, if it has - less than five). - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - D. Preserve all the copyright notices of the Document. - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified Version - under the terms of this License, in the form shown in the Addendum - below. - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements." Such a section may - not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option designate - some or all of these sections as invariant. To do this, add their - titles to the list of Invariant Sections in the Modified Version's - license notice. These titles must be distinct from any other - section titles. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of - a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end of - the list of Cover Texts in the Modified Version. Only one passage - of Front-Cover Text and one of Back-Cover Text may be added by (or - through arrangements made by) any one entity. If the Document - already includes a cover text for the same cover, previously added - by you or by arrangement made by the same entity you are acting on - behalf of, you may not add another; but you may replace the old - one, on explicit permission from the previous publisher that added - the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination all - of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications." You - must delete all sections entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the documents - in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow this - License in all other respects regarding verbatim copying of that - document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation copyright - is claimed for the compilation. Such a compilation is called an - "aggregate", and this License does not apply to the other - self-contained works thus compiled with the Document, on account of - their being thus compiled, if they are not themselves derivative - works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document 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. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation 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. See - http://www.gnu.org/copyleft/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the GNU General Public License, to permit -their use in free software. - - ---------- Footnotes ---------- - - (1) Any more details? - -AS Index -******** - -* Menu: - -* #: Comments. (line 1306) -* #APP: Preprocessing. (line 1268) -* #NO_APP: Preprocessing. (line 1268) -* '$a': ARM Mapping Symbols. - (line 4193) -* '$d': ARM Mapping Symbols. - (line 4199) -* '$t': ARM Mapping Symbols. - (line 4196) -* --: Command Line. (line 760) -* '--32' option, i386: i386-Options. (line 4220) -* '--32' option, x86-64: i386-Options. (line 4220) -* '--64' option, i386: i386-Options. (line 4220) -* '--64' option, x86-64: i386-Options. (line 4220) -* --alternate: alternate. (line 929) -* '--divide' option, i386: i386-Options. (line 4236) -* --enforce-aligned-data: Sparc-Aligned-Data. (line 5460) -* --fatal-warnings: W. (line 1222) -* --hash-size=NUMBER: Overview. (line 459) -* --listing-cont-lines: listing. (line 1015) -* --listing-lhs-width: listing. (line 997) -* --listing-lhs-width2: listing. (line 1002) -* --listing-rhs-width: listing. (line 1009) -* --MD: MD. (line 1149) -* --no-warn: W. (line 1217) -* --statistics: statistics. (line 1188) -* --traditional-format: traditional-format. (line 1196) -* --warn: W. (line 1225) -* -a: a. (line 894) -* -ac: a. (line 894) -* -ad: a. (line 894) -* -ah: a. (line 894) -* -al: a. (line 894) -* -an: a. (line 894) -* -as: a. (line 894) -* -Asparclet: Sparc-Opts. (line 5421) -* -Asparclite: Sparc-Opts. (line 5421) -* -Av6: Sparc-Opts. (line 5421) -* -Av8: Sparc-Opts. (line 5421) -* -Av9: Sparc-Opts. (line 5421) -* -Av9a: Sparc-Opts. (line 5421) -* -construct-floats: MIPS Opts. (line 5056) -* -D: D. (line 934) -* '-eabi=' command line option, ARM: ARM Options. (line 3844) -* '-EB' command line option, ARM: ARM Options. (line 3849) -* '-EB' option (MIPS): MIPS Opts. (line 4879) -* '-EL' command line option, ARM: ARM Options. (line 3853) -* '-EL' option (MIPS): MIPS Opts. (line 4879) -* -f: f. (line 940) -* '-G' option (MIPS): MIPS Opts. (line 4874) -* -I PATH: I. (line 952) -* -K: K. (line 962) -* '-k' command line option, ARM: ARM Options. (line 3857) -* '-KPIC' option, MIPS: MIPS Opts. (line 4887) -* -L: L. (line 972) -* -M: M. (line 1022) -* '-mapcs' command line option, ARM: ARM Options. (line 3817) -* '-mapcs-float' command line option, ARM: ARM Options. (line 3830) -* '-mapcs-reentrant' command line option, ARM: ARM Options. (line 3835) -* '-march=' command line option, ARM: ARM Options. (line 3773) -* '-march=' option, i386: i386-Options. (line 4243) -* '-march=' option, x86-64: i386-Options. (line 4243) -* '-matpcs' command line option, ARM: ARM Options. (line 3822) -* '-mconstant-gp' command line option, IA-64: IA-64 Options. (line 4733) -* '-mcpu=' command line option, ARM: ARM Options. (line 3742) -* '-mfloat-abi=' command line option, ARM: ARM Options. (line 3839) -* '-mfpu=' command line option, ARM: ARM Options. (line 3788) -* -mno-sym32: MIPS Opts. (line 5045) -* -msym32: MIPS Opts. (line 5045) -* '-mthumb' command line option, ARM: ARM Options. (line 3808) -* '-mthumb-interwork' command line option, ARM: ARM Options. (line 3813) -* '-mtune=' option, i386: i386-Options. (line 4255) -* '-mtune=' option, x86-64: i386-Options. (line 4255) -* '-mvxworks-pic' option, MIPS: MIPS Opts. (line 4892) -* -no-construct-floats: MIPS Opts. (line 5056) -* '-nocpp' ignored (MIPS): MIPS Opts. (line 5048) -* -o: o. (line 1160) -* -R: R. (line 1170) -* -v: v. (line 1206) -* -version: v. (line 1206) -* -W: W. (line 1217) -* '.' (symbol): Dot. (line 1898) -* '.arch' directive, ARM: ARM Directives. (line 4118) -* '.cantunwind' directive, ARM: ARM Directives. (line 4022) -* '.cpu' directive, ARM: ARM Directives. (line 4114) -* '.eabi_attribute' directive, ARM: ARM Directives. (line 4132) -* '.fnend' directive, ARM: ARM Directives. (line 4014) -* '.fnstart' directive, ARM: ARM Directives. (line 4011) -* '.fpu' directive, ARM: ARM Directives. (line 4128) -* '.handlerdata' directive, ARM: ARM Directives. (line 4033) -* '.insn': MIPS insn. (line 5223) -* '.ltorg' directive, ARM: ARM Directives. (line 3994) -* '.movsp' directive, ARM: ARM Directives. (line 4088) -* .o: Object. (line 827) -* '.object_arch' directive, ARM: ARM Directives. (line 4122) -* '.pad' directive, ARM: ARM Directives. (line 4083) -* '.personality' directive, ARM: ARM Directives. (line 4026) -* '.personalityindex' directive, ARM: ARM Directives. (line 4029) -* '.pool' directive, ARM: ARM Directives. (line 4008) -* '.save' directive, ARM: ARM Directives. (line 4042) -* '.set arch=CPU': MIPS ISA. (line 5195) -* '.set autoextend': MIPS autoextend. (line 5210) -* '.set dsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set dspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set mdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set mips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set mipsN': MIPS ISA. (line 5183) -* '.set mt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set noautoextend': MIPS autoextend. (line 5210) -* '.set nodsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set nodspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set nomdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set nomips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set nomt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set nosmartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set nosym32': MIPS symbol sizes. (line 5140) -* '.set pop': MIPS option stack. (line 5232) -* '.set push': MIPS option stack. (line 5232) -* '.set smartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set sym32': MIPS symbol sizes. (line 5140) -* '.setfp' directive, ARM: ARM Directives. (line 4093) -* '.unwind_raw' directive, ARM: ARM Directives. (line 4107) -* '.vsave' directive, ARM: ARM Directives. (line 4066) -* 16-bit code, i386: i386-16bit. (line 4615) -* 3DNow!, i386: i386-SIMD. (line 4593) -* 3DNow!, x86-64: i386-SIMD. (line 4593) -* ':' (label): Statements. (line 1355) -* '\"' (doublequote character): Strings. (line 1423) -* '\b' (backspace character): Strings. (line 1395) -* '\DDD' (octal character code): Strings. (line 1410) -* '\f' (formfeed character): Strings. (line 1398) -* '\n' (newline character): Strings. (line 1401) -* '\r' (carriage return character): Strings. (line 1404) -* '\t' (tab): Strings. (line 1407) -* '\XD...' (hex character code): Strings. (line 1416) -* '\\' ('\' character): Strings. (line 1420) -* a.out: Object. (line 827) -* 'abort' directive: Abort. (line 2114) -* absolute section: Ld Sections. (line 1632) -* addition, permitted arguments: Infix Ops. (line 2055) -* addresses: Expressions. (line 1946) -* addresses, format of: Secs Background. (line 1573) -* 'ADR reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4159) -* 'ADRL reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4169) -* advancing location counter: Org. (line 3101) -* 'align' directive: Align. (line 2123) -* 'align' directive, ARM: ARM Directives. (line 3915) -* 'align' directive, SPARC: Sparc-Directives. (line 5481) -* arch directive, i386: i386-Arch. (line 4670) -* arch directive, x86-64: i386-Arch. (line 4670) -* architectures, PowerPC: PowerPC-Opts. (line 5285) -* architectures, SPARC: Sparc-Opts. (line 5402) -* arguments for addition: Infix Ops. (line 2055) -* arguments for subtraction: Infix Ops. (line 2060) -* arguments in expressions: Arguments. (line 1973) -* arithmetic functions: Operators. (line 1998) -* arithmetic operands: Arguments. (line 1973) -* ARM data relocations: ARM-Relocations. (line 3886) -* 'arm' directive, ARM: ARM Directives. (line 3969) -* ARM floating point (IEEE): ARM Floating Point. (line 3910) -* ARM identifiers: ARM-Chars. (line 3876) -* ARM immediate character: ARM-Chars. (line 3874) -* ARM line comment character: ARM-Chars. (line 3867) -* ARM line separator: ARM-Chars. (line 3871) -* ARM machine directives: ARM Directives. (line 3915) -* ARM opcodes: ARM Opcodes. (line 4140) -* ARM options (none): ARM Options. (line 3742) -* ARM register names: ARM-Regs. (line 3881) -* ARM support: Machine Dependencies. - (line 3739) -* 'ascii' directive: Ascii. (line 2165) -* 'asciz' directive: Asciz. (line 2172) -* assembler bugs, reporting: Bug Reporting. (line 5566) -* assembler crash: Bug Criteria. (line 5550) -* assembler internal logic error: As Sections. (line 1674) -* assembler version: v. (line 1206) -* assembler, and linker: Secs Background. (line 1535) -* assembly listings, enabling: a. (line 894) -* assigning values to symbols: Setting Symbols. (line 1772) -* assigning values to symbols <1>: Equ. (line 2471) -* attributes, symbol: Symbol Attributes. (line 1907) -* att_syntax pseudo op, i386: i386-Syntax. (line 4265) -* att_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* Av7: Sparc-Opts. (line 5421) -* backslash ('\\'): Strings. (line 1420) -* backspace ('\b'): Strings. (line 1395) -* 'balign' directive: Balign. (line 2178) -* 'balignl' directive: Balign. (line 2199) -* 'balignw' directive: Balign. (line 2199) -* big endian output, MIPS: Overview. (line 560) -* big-endian output, MIPS: MIPS Opts. (line 4879) -* bignums: Bignums. (line 1485) -* binary files, including: Incbin. (line 2707) -* binary integers: Integers. (line 1466) -* bit names, IA-64: IA-64-Bits. (line 4846) -* bss section: Ld Sections. (line 1623) -* bss section <1>: bss. (line 1739) -* bug criteria: Bug Criteria. (line 5547) -* bug reports: Bug Reporting. (line 5566) -* bugs in assembler: Reporting Bugs. (line 5534) -* bus lock prefixes, i386: i386-Prefixes. (line 4444) -* 'byte' directive: Byte. (line 2211) -* call instructions, i386: i386-Mnemonics. (line 4353) -* call instructions, x86-64: i386-Mnemonics. (line 4353) -* carriage return ('\r'): Strings. (line 1404) -* 'cfi_endproc' directive: CFI directives. (line 2249) -* 'cfi_startproc' directive: CFI directives. (line 2239) -* character constants: Characters. (line 1377) -* character escape codes: Strings. (line 1395) -* character, single: Chars. (line 1443) -* characters used in symbols: Symbol Intro. (line 1325) -* 'code' directive, ARM: ARM Directives. (line 3962) -* 'code16' directive, i386: i386-16bit. (line 4615) -* 'code16gcc' directive, i386: i386-16bit. (line 4615) -* 'code32' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, x86-64: i386-16bit. (line 4615) -* COMDAT: Linkonce. (line 2831) -* 'comm' directive: Comm. (line 2217) -* command line conventions: Command Line. (line 756) -* comments: Comments. (line 1288) -* comments, removed by preprocessor: Preprocessing. (line 1253) -* 'common' directive, SPARC: Sparc-Directives. (line 5484) -* common sections: Linkonce. (line 2831) -* common variable storage: bss. (line 1739) -* comparison expressions: Infix Ops. (line 2066) -* conditional assembly: If. (line 2629) -* constant, single character: Chars. (line 1443) -* constants: Constants. (line 1366) -* constants, bignum: Bignums. (line 1485) -* constants, character: Characters. (line 1377) -* constants, converted by preprocessor: Preprocessing. (line 1256) -* constants, floating point: Flonums. (line 1493) -* constants, integer: Integers. (line 1466) -* constants, number: Numbers. (line 1457) -* constants, string: Strings. (line 1386) -* conversion instructions, i386: i386-Mnemonics. (line 4334) -* conversion instructions, x86-64: i386-Mnemonics. (line 4334) -* coprocessor wait, i386: i386-Prefixes. (line 4448) -* crash of assembler: Bug Criteria. (line 5550) -* current address: Dot. (line 1898) -* current address, advancing: Org. (line 3101) -* data alignment on SPARC: Sparc-Aligned-Data. (line 5455) -* data and text sections, joining: R. (line 1170) -* 'data' directive: Data. (line 2421) -* data relocations, ARM: ARM-Relocations. (line 3886) -* debuggers, and symbol order: Symbols. (line 1757) -* decimal integers: Integers. (line 1472) -* dependency tracking: MD. (line 1149) -* deprecated directives: Deprecated. (line 3731) -* directives and instructions: Statements. (line 1347) -* directives for PowerPC: PowerPC-Pseudo. (line 5386) -* directives, machine independent: Pseudo Ops. (line 2105) -* 'dn' and 'qn' directives, ARM: ARM Directives. (line 3938) -* dollar local symbols: Symbol Names. (line 1879) -* dot (symbol): Dot. (line 1898) -* 'double' directive: Double. (line 2428) -* 'double' directive, i386: i386-Float. (line 4569) -* 'double' directive, x86-64: i386-Float. (line 4569) -* doublequote ('\"'): Strings. (line 1423) -* ECOFF sections: MIPS Object. (line 5100) -* eight-byte integer: Quad. (line 3245) -* 'eject' directive: Eject. (line 2434) -* ELF symbol type: Type. (line 3620) -* 'else' directive: Else. (line 2439) -* 'elseif' directive: Elseif. (line 2446) -* empty expressions: Empty Exprs. (line 1959) -* emulation: Overview. (line 663) -* 'end' directive: End. (line 2453) -* 'endfunc' directive: Endfunc. (line 2459) -* endianness, MIPS: Overview. (line 560) -* 'endif' directive: Endif. (line 2464) -* 'endm' directive: Macro. (line 3025) -* EOF, newline must precede: Statements. (line 1341) -* 'equ' directive: Equ. (line 2471) -* 'equiv' directive: Equiv. (line 2477) -* 'eqv' directive: Eqv. (line 2493) -* 'err' directive: Err. (line 2501) -* error directive: Error. (line 2509) -* error messages: Errors. (line 844) -* error on valid input: Bug Criteria. (line 5553) -* errors, caused by warnings: W. (line 1222) -* errors, continuing after: Z. (line 1231) -* escape codes, character: Strings. (line 1395) -* 'exitm' directive: Macro. (line 3028) -* expr (internal section): As Sections. (line 1678) -* expression arguments: Arguments. (line 1973) -* expressions: Expressions. (line 1946) -* expressions, comparison: Infix Ops. (line 2066) -* expressions, empty: Empty Exprs. (line 1959) -* expressions, integer: Integer Exprs. (line 1967) -* 'extern' directive: Extern. (line 2524) -* 'fail' directive: Fail. (line 2531) -* faster processing ('-f'): f. (line 940) -* fatal signal: Bug Criteria. (line 5550) -* 'file' directive: LNS directives. (line 2369) -* 'file' directive <1>: File. (line 2540) -* file name, logical: File. (line 2540) -* files, including: Include. (line 2721) -* files, input: Input Files. (line 780) -* 'fill' directive: Fill. (line 2550) -* filling memory: Skip. (line 3452) -* filling memory <1>: Space. (line 3459) -* 'float' directive: Float. (line 2568) -* 'float' directive, i386: i386-Float. (line 4569) -* 'float' directive, x86-64: i386-Float. (line 4569) -* floating point numbers: Flonums. (line 1493) -* floating point numbers (double): Double. (line 2428) -* floating point numbers (single): Float. (line 2568) -* floating point numbers (single) <1>: Single. (line 3425) -* floating point, ARM (IEEE): ARM Floating Point. (line 3910) -* floating point, i386: i386-Float. (line 4561) -* floating point, SPARC (IEEE): Sparc-Float. (line 5473) -* floating point, x86-64: i386-Float. (line 4561) -* flonums: Flonums. (line 1493) -* 'force_thumb' directive, ARM: ARM Directives. (line 3972) -* format of error messages: Errors. (line 861) -* format of warning messages: Errors. (line 850) -* formfeed ('\f'): Strings. (line 1398) -* 'func' directive: Func. (line 2574) -* functions, in expressions: Operators. (line 1998) -* 'global' directive: Global. (line 2585) -* 'gp' register, MIPS: MIPS Object. (line 5105) -* grouping data: Sub-Sections. (line 1686) -* 'half' directive, SPARC: Sparc-Directives. (line 5489) -* hex character code ('\XD...'): Strings. (line 1416) -* hexadecimal integers: Integers. (line 1475) -* 'hidden' directive: Hidden. (line 2597) -* 'hword' directive: hword. (line 2610) -* i386 16-bit code: i386-16bit. (line 4615) -* i386 arch directive: i386-Arch. (line 4670) -* i386 att_syntax pseudo op: i386-Syntax. (line 4265) -* i386 conversion instructions: i386-Mnemonics. (line 4334) -* i386 floating point: i386-Float. (line 4561) -* i386 immediate operands: i386-Syntax. (line 4274) -* i386 instruction naming: i386-Mnemonics. (line 4309) -* i386 instruction prefixes: i386-Prefixes. (line 4414) -* i386 intel_syntax pseudo op: i386-Syntax. (line 4265) -* i386 jump optimization: i386-Jumps. (line 4538) -* i386 jump, call, return: i386-Syntax. (line 4296) -* i386 jump/call operands: i386-Syntax. (line 4274) -* i386 memory references: i386-Memory. (line 4471) -* i386 'mul', 'imul' instructions: i386-Notes. (line 4714) -* i386 options: i386-Options. (line 4218) -* i386 register operands: i386-Syntax. (line 4274) -* i386 registers: i386-Regs. (line 4359) -* i386 sections: i386-Syntax. (line 4302) -* i386 size suffixes: i386-Syntax. (line 4287) -* i386 source, destination operands: i386-Syntax. (line 4280) -* i386 support: . (line 4211) -* i386 syntax compatibility: i386-Syntax. (line 4265) -* i80306 support: . (line 4211) -* IA-64 line comment character: IA-64-Chars. (line 4822) -* IA-64 line separator: IA-64-Chars. (line 4824) -* IA-64 options: IA-64 Options. (line 4733) -* IA-64 Processor-status-Register bit names: IA-64-Bits. (line 4846) -* IA-64 registers: IA-64-Regs. (line 4829) -* IA-64 support: . (line 4730) -* IA-64 Syntax: IA-64 Options. (line 4812) -* 'ident' directive: Ident. (line 2618) -* identifiers, ARM: ARM-Chars. (line 3876) -* 'if' directive: If. (line 2629) -* 'ifb' directive: If. (line 2644) -* 'ifc' directive: If. (line 2648) -* 'ifdef' directive: If. (line 2639) -* 'ifeq' directive: If. (line 2656) -* 'ifeqs' directive: If. (line 2659) -* 'ifge' directive: If. (line 2663) -* 'ifgt' directive: If. (line 2667) -* 'ifle' directive: If. (line 2671) -* 'iflt' directive: If. (line 2675) -* 'ifnb' directive: If. (line 2679) -* 'ifnc' directive: If. (line 2684) -* 'ifndef' directive: If. (line 2688) -* 'ifne' directive: If. (line 2695) -* 'ifnes' directive: If. (line 2699) -* 'ifnotdef' directive: If. (line 2688) -* immediate character, ARM: ARM-Chars. (line 3874) -* immediate operands, i386: i386-Syntax. (line 4274) -* immediate operands, x86-64: i386-Syntax. (line 4274) -* 'imul' instruction, i386: i386-Notes. (line 4714) -* 'imul' instruction, x86-64: i386-Notes. (line 4714) -* 'incbin' directive: Incbin. (line 2707) -* 'include' directive: Include. (line 2721) -* 'include' directive search path: I. (line 952) -* infix operators: Infix Ops. (line 2016) -* inhibiting interrupts, i386: i386-Prefixes. (line 4444) -* input: Input Files. (line 780) -* input file linenumbers: Input Files. (line 809) -* instruction naming, i386: i386-Mnemonics. (line 4309) -* instruction naming, x86-64: i386-Mnemonics. (line 4309) -* instruction prefixes, i386: i386-Prefixes. (line 4414) -* instructions and directives: Statements. (line 1347) -* 'int' directive: Int. (line 2732) -* 'int' directive, i386: i386-Float. (line 4576) -* 'int' directive, x86-64: i386-Float. (line 4576) -* integer expressions: Integer Exprs. (line 1967) -* integer, 16-byte: Octa. (line 3092) -* integer, 8-byte: Quad. (line 3245) -* integers: Integers. (line 1466) -* integers, 16-bit: hword. (line 2610) -* integers, 32-bit: Int. (line 2732) -* integers, binary: Integers. (line 1466) -* integers, decimal: Integers. (line 1472) -* integers, hexadecimal: Integers. (line 1475) -* integers, octal: Integers. (line 1469) -* integers, one byte: Byte. (line 2211) -* intel_syntax pseudo op, i386: i386-Syntax. (line 4265) -* intel_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* internal assembler sections: As Sections. (line 1667) -* 'internal' directive: Internal. (line 2740) -* invalid input: Bug Criteria. (line 5555) -* invocation summary: Overview. (line 249) -* 'irp' directive: Irp. (line 2754) -* 'irpc' directive: Irpc. (line 2779) -* joining text and data sections: R. (line 1170) -* jump instructions, i386: i386-Mnemonics. (line 4353) -* jump instructions, x86-64: i386-Mnemonics. (line 4353) -* jump optimization, i386: i386-Jumps. (line 4538) -* jump optimization, x86-64: i386-Jumps. (line 4538) -* jump/call operands, i386: i386-Syntax. (line 4274) -* jump/call operands, x86-64: i386-Syntax. (line 4274) -* label (':'): Statements. (line 1355) -* labels: Labels. (line 1763) -* 'lcomm' directive: Lcomm. (line 2805) -* ld: Object. (line 836) -* 'LDR reg,=<label>' pseudo op, ARM: ARM Opcodes. (line 4149) -* length of symbols: Symbol Intro. (line 1331) -* 'lflags' directive (ignored): Lflags. (line 2814) -* line comment character: Comments. (line 1301) -* line comment character, ARM: ARM-Chars. (line 3867) -* line comment character, IA-64: IA-64-Chars. (line 4822) -* 'line' directive: Line. (line 2820) -* line numbers, in input files: Input Files. (line 809) -* line numbers, in warnings/errors: Errors. (line 854) -* line separator character: Statements. (line 1336) -* line separator, ARM: ARM-Chars. (line 3871) -* line separator, IA-64: IA-64-Chars. (line 4824) -* lines starting with '#': Comments. (line 1306) -* linker: Object. (line 836) -* linker, and assembler: Secs Background. (line 1535) -* 'linkonce' directive: Linkonce. (line 2831) -* 'list' directive: List. (line 2876) -* listing control, turning off: Nolist. (line 3083) -* listing control, turning on: List. (line 2876) -* listing control: new page: Eject. (line 2434) -* listing control: paper size: Psize. (line 3208) -* listing control: subtitle: Sbttl. (line 3284) -* listing control: title line: Title. (line 3609) -* listings, enabling: a. (line 894) -* little endian output, MIPS: Overview. (line 563) -* little-endian output, MIPS: MIPS Opts. (line 4879) -* 'ln' directive: Ln. (line 2863) -* 'loc' directive: LNS directives. (line 2382) -* local common symbols: Lcomm. (line 2805) -* local labels: Symbol Names. (line 1810) -* local symbol names: Symbol Names. (line 1797) -* local symbols, retaining in output: L. (line 972) -* location counter: Dot. (line 1898) -* location counter, advancing: Org. (line 3101) -* 'loc_mark_blocks' directive: LNS directives. (line 2412) -* logical file name: File. (line 2540) -* logical line number: Line. (line 2820) -* logical line numbers: Comments. (line 1306) -* 'long' directive: Long. (line 2889) -* 'long' directive, i386: i386-Float. (line 4576) -* 'long' directive, x86-64: i386-Float. (line 4576) -* machine directives, ARM: ARM Directives. (line 3915) -* machine directives, SPARC: Sparc-Directives. (line 5478) -* machine independent directives: Pseudo Ops. (line 2105) -* machine instructions (not covered): Manual. (line 716) -* machine-independent syntax: Syntax. (line 1241) -* 'macro' directive: Macro. (line 2916) -* macros: Macro. (line 2894) -* macros, count executed: Macro. (line 3030) -* make rules: MD. (line 1149) -* manual, structure and purpose: Manual. (line 708) -* Maximum number of continuation lines: listing. (line 1015) -* memory references, i386: i386-Memory. (line 4471) -* memory references, x86-64: i386-Memory. (line 4471) -* merging text and data sections: R. (line 1170) -* messages from assembler: Errors. (line 844) -* minus, permitted arguments: Infix Ops. (line 2060) -* MIPS architecture options: MIPS Opts. (line 4895) -* MIPS big-endian output: MIPS Opts. (line 4879) -* MIPS CPU override: MIPS ISA. (line 5195) -* MIPS debugging directives: MIPS Stabs. (line 5128) -* MIPS DSP Release 1 instruction generation override: MIPS ASE instruction generation overrides. - (line 5262) -* MIPS DSP Release 2 instruction generation override: MIPS ASE instruction generation overrides. - (line 5267) -* MIPS ECOFF sections: MIPS Object. (line 5100) -* MIPS endianness: Overview. (line 560) -* MIPS ISA: Overview. (line 566) -* MIPS ISA override: MIPS ISA. (line 5183) -* MIPS little-endian output: MIPS Opts. (line 4879) -* MIPS MDMX instruction generation override: MIPS ASE instruction generation overrides. - (line 5257) -* MIPS MIPS-3D instruction generation override: MIPS ASE instruction generation overrides. - (line 5247) -* MIPS MT instruction generation override: MIPS ASE instruction generation overrides. - (line 5272) -* MIPS option stack: MIPS option stack. (line 5232) -* MIPS processor: . (line 4862) -* MMX, i386: i386-SIMD. (line 4593) -* MMX, x86-64: i386-SIMD. (line 4593) -* mnemonic suffixes, i386: i386-Syntax. (line 4287) -* mnemonic suffixes, x86-64: i386-Syntax. (line 4287) -* MOVW and MOVT relocations, ARM: ARM-Relocations. (line 3900) -* MRI compatibility mode: M. (line 1022) -* 'mri' directive: MRI. (line 2868) -* MRI mode, temporarily: MRI. (line 2868) -* 'mul' instruction, i386: i386-Notes. (line 4714) -* 'mul' instruction, x86-64: i386-Notes. (line 4714) -* named section: Section. (line 3293) -* named sections: Ld Sections. (line 1613) -* names, symbol: Symbol Names. (line 1781) -* naming object file: o. (line 1160) -* new page, in listings: Eject. (line 2434) -* newline ('\n'): Strings. (line 1401) -* newline, required at file end: Statements. (line 1341) -* 'nolist' directive: Nolist. (line 3083) -* 'NOP' pseudo op, ARM: ARM Opcodes. (line 4143) -* null-terminated strings: Asciz. (line 2172) -* number constants: Numbers. (line 1457) -* number of macros executed: Macro. (line 3030) -* numbered subsections: Sub-Sections. (line 1686) -* numbers, 16-bit: hword. (line 2610) -* numeric values: Expressions. (line 1946) -* 'nword' directive, SPARC: Sparc-Directives. (line 5492) -* object file: Object. (line 827) -* object file format: Object Formats. (line 746) -* object file name: o. (line 1160) -* object file, after errors: Z. (line 1231) -* obsolescent directives: Deprecated. (line 3731) -* 'octa' directive: Octa. (line 3092) -* octal character code ('\DDD'): Strings. (line 1410) -* octal integers: Integers. (line 1469) -* opcodes for ARM: ARM Opcodes. (line 4140) -* operand delimiters, i386: i386-Syntax. (line 4274) -* operand delimiters, x86-64: i386-Syntax. (line 4274) -* operands in expressions: Arguments. (line 1973) -* operator precedence: Infix Ops. (line 2021) -* operators, in expressions: Operators. (line 1998) -* operators, permitted arguments: Infix Ops. (line 2016) -* option summary: Overview. (line 249) -* options for ARM (none): ARM Options. (line 3742) -* options for i386: i386-Options. (line 4218) -* options for IA-64: IA-64 Options. (line 4733) -* options for PowerPC: PowerPC-Opts. (line 5285) -* options for SPARC: Sparc-Opts. (line 5402) -* options for x86-64: i386-Options. (line 4218) -* options, all versions of assembler: Invoking. (line 870) -* options, command line: Command Line. (line 763) -* 'org' directive: Org. (line 3101) -* output file: Object. (line 827) -* 'p2align' directive: P2align. (line 3127) -* 'p2alignl' directive: P2align. (line 3149) -* 'p2alignw' directive: P2align. (line 3149) -* padding the location counter: Align. (line 2123) -* padding the location counter given a power of two: P2align. - (line 3127) -* padding the location counter given number of bytes: Balign. - (line 2178) -* page, in listings: Eject. (line 2434) -* paper size, for listings: Psize. (line 3208) -* paths for '.include': I. (line 952) -* patterns, writing in memory: Fill. (line 2550) -* PIC code generation for ARM: ARM Options. (line 3857) -* PIC selection, MIPS: MIPS Opts. (line 4887) -* plus, permitted arguments: Infix Ops. (line 2055) -* 'popsection' directive: PopSection. (line 3177) -* PowerPC architectures: PowerPC-Opts. (line 5285) -* PowerPC directives: PowerPC-Pseudo. (line 5386) -* PowerPC options: PowerPC-Opts. (line 5285) -* PowerPC support: . (line 5282) -* precedence of operators: Infix Ops. (line 2021) -* precision, floating point: Flonums. (line 1493) -* prefix operators: Prefix Ops. (line 2005) -* prefixes, i386: i386-Prefixes. (line 4414) -* preprocessing: Preprocessing. (line 1248) -* preprocessing, turning on and off: Preprocessing. (line 1268) -* 'previous' directive: Previous. (line 3161) -* 'print' directive: Print. (line 3189) -* 'proc' directive, SPARC: Sparc-Directives. (line 5497) -* 'protected' directive: Protected. (line 3195) -* pseudo-ops, machine independent: Pseudo Ops. (line 2105) -* 'psize' directive: Psize. (line 3208) -* PSR bits: IA-64-Bits. (line 4846) -* 'purgem' directive: Purgem. (line 3224) -* purpose of GNU assembler: GNU Assembler. (line 734) -* 'pushsection' directive: PushSection. (line 3230) -* 'quad' directive: Quad. (line 3242) -* 'quad' directive, i386: i386-Float. (line 4576) -* 'quad' directive, x86-64: i386-Float. (line 4576) -* real-mode code, i386: i386-16bit. (line 4615) -* 'register' directive, SPARC: Sparc-Directives. (line 5501) -* register names, ARM: ARM-Regs. (line 3881) -* register names, IA-64: IA-64-Regs. (line 4829) -* register operands, i386: i386-Syntax. (line 4274) -* register operands, x86-64: i386-Syntax. (line 4274) -* registers, i386: i386-Regs. (line 4359) -* registers, x86-64: i386-Regs. (line 4359) -* 'reloc' directive: Reloc. (line 3253) -* relocation: Sections. (line 1528) -* relocation example: Ld Sections. (line 1643) -* repeat prefixes, i386: i386-Prefixes. (line 4452) -* reporting bugs in assembler: Reporting Bugs. (line 5534) -* 'rept' directive: Rept. (line 3266) -* 'req' directive, ARM: ARM Directives. (line 3922) -* 'reserve' directive, SPARC: Sparc-Directives. (line 5511) -* return instructions, i386: i386-Syntax. (line 4296) -* return instructions, x86-64: i386-Syntax. (line 4296) -* REX prefixes, i386: i386-Prefixes. (line 4454) -* 'sbttl' directive: Sbttl. (line 3284) -* search path for '.include': I. (line 952) -* 'section' directive (ELF version): Section. (line 3305) -* section override prefixes, i386: i386-Prefixes. (line 4431) -* Section Stack: Previous. (line 3161) -* Section Stack <1>: PopSection. (line 3177) -* Section Stack <2>: PushSection. (line 3230) -* Section Stack <3>: Section. (line 3300) -* Section Stack <4>: SubSection. (line 3545) -* section-relative addressing: Secs Background. (line 1573) -* sections: Sections. (line 1528) -* sections in messages, internal: As Sections. (line 1667) -* sections, i386: i386-Syntax. (line 4302) -* sections, named: Ld Sections. (line 1613) -* sections, x86-64: i386-Syntax. (line 4302) -* 'seg' directive, SPARC: Sparc-Directives. (line 5516) -* 'set' directive: Set. (line 3407) -* 'short' directive: Short. (line 3419) -* SIMD, i386: i386-SIMD. (line 4593) -* SIMD, x86-64: i386-SIMD. (line 4593) -* single character constant: Chars. (line 1443) -* 'single' directive: Single. (line 3425) -* 'single' directive, i386: i386-Float. (line 4569) -* 'single' directive, x86-64: i386-Float. (line 4569) -* sixteen bit integers: hword. (line 2610) -* sixteen byte integer: Octa. (line 3092) -* 'size' directive (ELF version): Size. (line 3433) -* size prefixes, i386: i386-Prefixes. (line 4435) -* sizes operands, i386: i386-Syntax. (line 4287) -* sizes operands, x86-64: i386-Syntax. (line 4287) -* 'skip' directive: Skip. (line 3452) -* 'skip' directive, SPARC: Sparc-Directives. (line 5520) -* 'sleb128' directive: Sleb128. (line 3445) -* small objects, MIPS ECOFF: MIPS Object. (line 5105) -* SmartMIPS instruction generation override: MIPS ASE instruction generation overrides. - (line 5252) -* source program: Input Files. (line 780) -* source, destination operands; i386: i386-Syntax. (line 4280) -* source, destination operands; x86-64: i386-Syntax. (line 4280) -* 'space' directive: Space. (line 3459) -* space used, maximum for assembly: statistics. (line 1188) -* SPARC architectures: Sparc-Opts. (line 5402) -* SPARC data alignment: Sparc-Aligned-Data. (line 5455) -* SPARC floating point (IEEE): Sparc-Float. (line 5473) -* SPARC machine directives: Sparc-Directives. (line 5478) -* SPARC options: Sparc-Opts. (line 5402) -* SPARC support: . (line 5399) -* 'stabd' directive: Stab. (line 3498) -* 'stabn' directive: Stab. (line 3509) -* 'stabs' directive: Stab. (line 3512) -* 'stabX' directives: Stab. (line 3466) -* standard assembler sections: Secs Background. (line 1550) -* standard input, as input file: Command Line. (line 760) -* statement separator character: Statements. (line 1336) -* statement separator, ARM: ARM-Chars. (line 3871) -* statement separator, IA-64: IA-64-Chars. (line 4824) -* statements, structure of: Statements. (line 1336) -* statistics, about assembly: statistics. (line 1188) -* stopping the assembly: Abort. (line 2114) -* string constants: Strings. (line 1386) -* 'string' directive: String. (line 3518) -* string literals: Ascii. (line 2165) -* string, copying to object file: String. (line 3518) -* 'struct' directive: Struct. (line 3527) -* subexpressions: Arguments. (line 1991) -* 'subsection' directive: SubSection. (line 3545) -* subtitles for listings: Sbttl. (line 3284) -* subtraction, permitted arguments: Infix Ops. (line 2060) -* summary of options: Overview. (line 249) -* supporting files, including: Include. (line 2721) -* suppressing warnings: W. (line 1217) -* symbol attributes: Symbol Attributes. (line 1907) -* symbol names: Symbol Names. (line 1781) -* symbol names, local: Symbol Names. (line 1797) -* symbol names, temporary: Symbol Names. (line 1810) -* symbol type: Symbol Type. (line 1938) -* symbol type, ELF: Type. (line 3620) -* symbol value: Symbol Value. (line 1918) -* symbol value, setting: Set. (line 3407) -* symbol values, assigning: Setting Symbols. (line 1772) -* symbol versioning: Symver. (line 3557) -* symbol, common: Comm. (line 2217) -* symbol, making visible to linker: Global. (line 2585) -* symbolic debuggers, information for: Stab. (line 3466) -* symbols: Symbols. (line 1753) -* symbols, assigning values to: Equ. (line 2471) -* symbols, local common: Lcomm. (line 2805) -* 'symver' directive: Symver. (line 3557) -* syntax compatibility, i386: i386-Syntax. (line 4265) -* syntax compatibility, x86-64: i386-Syntax. (line 4265) -* syntax, machine-independent: Syntax. (line 1241) -* tab ('\t'): Strings. (line 1407) -* temporary symbol names: Symbol Names. (line 1810) -* text and data sections, joining: R. (line 1170) -* 'text' directive: Text. (line 3602) -* 'tfloat' directive, i386: i386-Float. (line 4569) -* 'tfloat' directive, x86-64: i386-Float. (line 4569) -* 'thumb' directive, ARM: ARM Directives. (line 3966) -* Thumb support: Machine Dependencies. - (line 3739) -* 'thumb_func' directive, ARM: ARM Directives. (line 3976) -* 'thumb_set' directive, ARM: ARM Directives. (line 3987) -* time, total for assembly: statistics. (line 1188) -* 'title' directive: Title. (line 3609) -* trusted compiler: f. (line 940) -* turning preprocessing on and off: Preprocessing. (line 1268) -* 'type' directive (ELF version): Type. (line 3620) -* type of a symbol: Symbol Type. (line 1938) -* 'uleb128' directive: Uleb128. (line 3656) -* undefined section: Ld Sections. (line 1639) -* 'unreq' directive, ARM: ARM Directives. (line 3927) -* value of a symbol: Symbol Value. (line 1918) -* 'version' directive: Version. (line 3663) -* version of assembler: v. (line 1206) -* versions of symbols: Symver. (line 3557) -* visibility: Hidden. (line 2597) -* visibility <1>: Internal. (line 2740) -* visibility <2>: Protected. (line 3195) -* 'vtable_entry' directive: VTableEntry. (line 3669) -* 'vtable_inherit' directive: VTableInherit. (line 3675) -* warning directive: Warning. (line 3683) -* warning messages: Errors. (line 844) -* warnings, causing error: W. (line 1222) -* warnings, suppressing: W. (line 1217) -* warnings, switching on: W. (line 1225) -* 'weak' directive: Weak. (line 3689) -* 'weakref' directive: Weakref. (line 3705) -* whitespace: Whitespace. (line 1280) -* whitespace, removed by preprocessor: Preprocessing. (line 1249) -* Width of continuation lines of disassembly output: listing. - (line 1002) -* Width of first line disassembly output: listing. (line 997) -* Width of source line output: listing. (line 1009) -* 'word' directive: Word. (line 3725) -* 'word' directive, i386: i386-Float. (line 4576) -* 'word' directive, SPARC: Sparc-Directives. (line 5523) -* 'word' directive, x86-64: i386-Float. (line 4576) -* writing patterns in memory: Fill. (line 2550) -* x86-64 arch directive: i386-Arch. (line 4670) -* x86-64 att_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 conversion instructions: i386-Mnemonics. (line 4334) -* x86-64 floating point: i386-Float. (line 4561) -* x86-64 immediate operands: i386-Syntax. (line 4274) -* x86-64 instruction naming: i386-Mnemonics. (line 4309) -* x86-64 intel_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 jump optimization: i386-Jumps. (line 4538) -* x86-64 jump, call, return: i386-Syntax. (line 4296) -* x86-64 jump/call operands: i386-Syntax. (line 4274) -* x86-64 memory references: i386-Memory. (line 4471) -* x86-64 options: i386-Options. (line 4218) -* x86-64 register operands: i386-Syntax. (line 4274) -* x86-64 registers: i386-Regs. (line 4359) -* x86-64 sections: i386-Syntax. (line 4302) -* x86-64 size suffixes: i386-Syntax. (line 4287) -* x86-64 source, destination operands: i386-Syntax. (line 4280) -* x86-64 support: . (line 4211) -* x86-64 syntax compatibility: i386-Syntax. (line 4265) -* 'xword' directive, SPARC: Sparc-Directives. (line 5527) -* zero-terminated strings: Asciz. (line 2172) - diff --git a/contrib/binutils/ld/ld.7 b/contrib/binutils/ld/ld.7 new file mode 100644 index 000000000000..8ac5573b75c2 --- /dev/null +++ b/contrib/binutils/ld/ld.7 @@ -0,0 +1,7819 @@ +.Dd 2015-03-02 +.Dt LD 7 +.Os +.Sh NAME +.Nm ld +.Nd The GNU Linker +.Sh LD +This file documents the GNU linker ld version "2.17.50 [FreeBSD] 2007-07-03". +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled \(lqGNU Free +Documentation License\(rq. +.Pp +.Sh Overview +.Xr 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 +.Xr ld . +.Pp +.Xr 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. +.Pp +This version of +.Xr ld +uses the general purpose BFD libraries to operate on object files. This allows +.Xr ld +to read, combine, and write object files in many different formats---for example, +COFF or +.Li a.out . +Different formats may be linked together to produce any available kind of +object file.See Section +.Dq BFD , +for more information. +.Pp +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, +.Xr ld +continues executing, allowing you to identify other errors (or, in some cases, +to get an output file in spite of the error). +.Pp +.Sh Invocation +The GNU linker +.Xr 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. +.Pp +.Ss Command Line Options +The linker supports a plethora of command-line options, but in actual practice +few of them are used in any particular context. For instance, a frequent use +of +.Xr ld +is to link standard Unix object files on a standard, supported Unix system. +On such a system, to link a file +.Li hello.o : +.Pp +.Bd -literal -offset indent +ld -o output /lib/crt0.o hello.o -lc +.Ed +.Pp +This tells +.Xr ld +to produce a file called +.Va output +as the result of linking the file +.Li /lib/crt0.o +with +.Li hello.o +and the library +.Li libc.a , +which will come from the standard search directories. (See the discussion +of the +.Li -l +option below.) +.Pp +Some of the command-line options to +.Xr ld +may be specified at any point in the command line. However, options which +refer to files, such as +.Li -l +or +.Li -T , +cause the file to be read at the point at which the option appears in the +command line, relative to the object files and other file options. Repeating +non-file 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. Options which may be meaningfully specified more than once +are noted in the descriptions below. +.Pp +Non-option arguments are object files or archives which are to be linked together. +They may follow, precede, or be mixed in with command-line options, except +that an object file argument may not be placed between an option and its argument. +.Pp +Usually the linker is invoked with at least one object file, but you can specify +other forms of binary input files using +.Li -l , +.Li -R , +and the script command language. If +.Em no +binary input files at all are specified, the linker does not produce any output, +and issues the message +.Li No input files . +.Pp +If the linker cannot recognize the format of an object file, it will assume +that it is a linker script. A script specified in this way augments the main +linker script used for the link (either the default linker script or the one +specified by using +.Li -T ) . +This feature permits the linker to link against a file which appears to be +an object or an archive, but actually merely defines some symbol values, or +uses +.Li INPUT +or +.Li GROUP +to load other objects. Note that specifying a script in this way merely augments +the main linker script; use the +.Li -T +option to replace the default linker script entirely.See Section +.Dq Scripts . +.Pp +For options whose names are a single letter, option arguments must either +follow the option letter without intervening whitespace, or be given as separate +arguments immediately following the option that requires them. +.Pp +For options whose names are multiple letters, either one dash or two can precede +the option name; for example, +.Li -trace-symbol +and +.Li --trace-symbol +are equivalent. Note---there is one exception to this rule. Multiple letter +options that start with a lower case 'o' can only be preceded by two dashes. +This is to reduce confusion with the +.Li -o +option. So for example +.Li -omagic +sets the output file name to +.Li magic +whereas +.Li --omagic +sets the NMAGIC flag on the output. +.Pp +Arguments to multiple-letter options must either be separated from the option +name by an equals sign, or be given as separate arguments immediately following +the option that requires them. For example, +.Li --trace-symbol foo +and +.Li --trace-symbol=foo +are equivalent. Unique abbreviations of the names of multiple-letter options +are accepted. +.Pp +Note---if the linker is being invoked indirectly, via a compiler driver (e.g. +.Li gcc ) +then all the linker command line options should be prefixed by +.Li -Wl, +(or whatever is appropriate for the particular compiler driver) like this: +.Pp +.Bd -literal -offset indent + gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup +.Ed +.Pp +This is important, because otherwise the compiler driver program may silently +drop the linker options, resulting in a bad link. +.Pp +Here is a table of the generic command line switches accepted by the GNU linker: +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +are separated by whitespace. A whitespace character may be included in an +option by surrounding the entire option in either single or double quotes. +Any character (including a backslash) may be included by prefixing the character +to be included with a backslash. The +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It -a Va keyword +This option is supported for HP/UX compatibility. The +.Va keyword +argument must be one of the strings +.Li archive , +.Li shared , +or +.Li default . +.Li -aarchive +is functionally equivalent to +.Li -Bstatic , +and the other two keywords are functionally equivalent to +.Li -Bdynamic . +This option may be used any number of times. +.Pp +.It -A Va architecture +.It --architecture= Va architecture +In the current release of +.Xr ld , +this option is useful only for the Intel 960 family of architectures. In that +.Xr ld +configuration, the +.Va architecture +argument identifies the particular architecture in the 960 family, enabling +some safeguards and modifying the archive-library search path.See Section +.Dq i960 , +for details. +.Pp +Future releases of +.Xr ld +may support similar functionality for other architecture families. +.Pp +.It -b Va input-format +.It --format= Va input-format +.Xr ld +may be configured to support more than one kind of object file. If your +.Xr ld +is configured this way, you can use the +.Li -b +option to specify the binary format for input object files that follow this +option on the command line. Even when +.Xr ld +is configured to support alternative object formats, you don't usually need +to specify this, as +.Xr ld +should be configured to expect as a default input format the most usual format +on each machine. +.Va 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 +.Li objdump -i . ) +See Section.Dq BFD . +.Pp +You may want to use this option if you are linking files with an unusual binary +format. You can also use +.Li -b +to switch formats explicitly (when linking object files of different formats), +by including +.Li -b Va input-format +before each group of object files in a particular format. +.Pp +The default format is taken from the environment variable +.Li GNUTARGET . +See Section.Dq Environment . +You can also define the input format from a script, using the command +.Li TARGET ; +see Format Commands. +.Pp +.It -c Va MRI-commandfile +.It --mri-script= Va MRI-commandfile +For compatibility with linkers produced by MRI, +.Xr ld +accepts script files written in an alternate, restricted command language, +described in MRI,,MRI Compatible Script Files. Introduce MRI script files +with the option +.Li -c ; +use the +.Li -T +option to run linker scripts written in the general-purpose +.Xr ld +scripting language. If +.Va MRI-cmdfile +does not exist, +.Xr ld +looks for it in the directories specified by any +.Li -L +options. +.Pp +.It -d +.It -dc +.It -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 +.Li -r ) . +The script command +.Li FORCE_COMMON_ALLOCATION +has the same effect.See Section +.Dq Miscellaneous Commands . +.Pp +.It -e Va entry +.It --entry= Va entry +Use +.Va entry +as the explicit symbol for beginning execution of your program, rather than +the default entry point. If there is no symbol named +.Va entry , +the linker will try to parse +.Va entry +as a number, and use that as the entry address (the number will be interpreted +in base 10; you may use a leading +.Li 0x +for base 16, or a leading +.Li 0 +for base 8).See Section +.Dq Entry Point , +for a discussion of defaults and other ways of specifying the entry point. +.Pp +.It --exclude-libs Va lib, Va lib,... +Specifies a list of archive libraries from which symbols should not be automatically +exported. The library names may be delimited by commas or colons. Specifying +.Li --exclude-libs ALL +excludes symbols in all archive libraries from automatic export. This option +is available only for the i386 PE targeted port of the linker and for ELF +targeted ports. For i386 PE, symbols explicitly listed in a .def file are +still exported, regardless of this option. For ELF targeted ports, symbols +affected by this option will be treated as hidden. +.Pp +.It -E +.It --export-dynamic +When creating a dynamically linked executable, add all symbols to the dynamic +symbol table. The dynamic symbol table is the set of symbols which are visible +from dynamic objects at run time. +.Pp +If you do not use this option, the dynamic symbol table will normally contain +only those symbols which are referenced by some dynamic object mentioned in +the link. +.Pp +If you use +.Li dlopen +to load a dynamic object which needs to refer back to the symbols defined +by the program, rather than some other dynamic object, then you will probably +need to use this option when linking the program itself. +.Pp +You can also use the dynamic list to control what symbols should be added +to the dynamic symbol table if the output format supports it. See the description +of +.Li --dynamic-list . +.Pp +.It -EB +Link big-endian objects. This affects the default output format. +.Pp +.It -EL +Link little-endian objects. This affects the default output format. +.Pp +.It -f +.It --auxiliary Va name +When creating an ELF shared object, set the internal DT_AUXILIARY field to +the specified name. This tells the dynamic linker that the symbol table of +the shared object should be used as an auxiliary filter on the symbol table +of the shared object +.Va name . +.Pp +If you later link a program against this filter object, then, when you run +the program, the dynamic linker will see the DT_AUXILIARY field. If the dynamic +linker resolves any symbols from the filter object, it will first check whether +there is a definition in the shared object +.Va name . +If there is one, it will be used instead of the definition in the filter object. +The shared object +.Va name +need not exist. Thus the shared object +.Va name +may be used to provide an alternative implementation of certain functions, +perhaps for debugging or for machine specific performance. +.Pp +This option may be specified more than once. The DT_AUXILIARY entries will +be created in the order in which they appear on the command line. +.Pp +.It -F Va name +.It --filter Va name +When creating an ELF shared object, set the internal DT_FILTER field to the +specified name. This tells the dynamic linker that the symbol table of the +shared object which is being created should be used as a filter on the symbol +table of the shared object +.Va name . +.Pp +If you later link a program against this filter object, then, when you run +the program, the dynamic linker will see the DT_FILTER field. The dynamic +linker will resolve symbols according to the symbol table of the filter object +as usual, but it will actually link to the definitions found in the shared +object +.Va name . +Thus the filter object can be used to select a subset of the symbols provided +by the object +.Va name . +.Pp +Some older linkers used the +.Op -F +option throughout a compilation toolchain for specifying object-file format +for both input and output object files. The GNU linker uses other mechanisms +for this purpose: the +.Op -b , +.Op --format , +.Op --oformat +options, the +.Li TARGET +command in linker scripts, and the +.Li GNUTARGET +environment variable. The GNU linker will ignore the +.Op -F +option when not creating an ELF shared object. +.Pp +.It -fini Va name +When creating an ELF executable or shared object, call NAME when the executable +or shared object is unloaded, by setting DT_FINI to the address of the function. +By default, the linker uses +.Li _fini +as the function to call. +.Pp +.It -g +Ignored. Provided for compatibility with other tools. +.Pp +.It -G Va value +.It --gpsize= Va value +Set the maximum size of objects to be optimized using the GP register to +.Va size . +This is only meaningful for object file formats such as MIPS ECOFF which supports +putting large and small objects into different sections. This is ignored for +other object file formats. +.Pp +.It -h Va name +.It -soname= Va name +When creating an ELF shared object, set the internal DT_SONAME field to the +specified name. When an executable is linked with a shared object which has +a DT_SONAME field, then when the executable is run the dynamic linker will +attempt to load the shared object specified by the DT_SONAME field rather +than the using the file name given to the linker. +.Pp +.It -i +Perform an incremental link (same as option +.Li -r ) . +.Pp +.It -init Va name +When creating an ELF executable or shared object, call NAME when the executable +or shared object is loaded, by setting DT_INIT to the address of the function. +By default, the linker uses +.Li _init +as the function to call. +.Pp +.It -l Va namespec +.It --library= Va namespec +Add the archive or object file specified by +.Va namespec +to the list of files to link. This option may be used any number of times. +If +.Va namespec +is of the form +.Pa : Va filename , +.Xr ld +will search the library path for a file called +.Va filename , +otherise it will search the library path for a file called +.Pa lib Va namespec.a . +.Pp +On systems which support shared libraries, +.Xr ld +may also search for files other than +.Pa lib Va namespec.a . +Specifically, on ELF and SunOS systems, +.Xr ld +will search a directory for a library called +.Pa lib Va namespec.so +before searching for one called +.Pa lib Va namespec.a . +(By convention, a +.Li .so +extension indicates a shared library.) Note that this behavior does not apply +to +.Pa : Va filename , +which always specifies a file called +.Va filename . +.Pp +The linker will search an archive only once, at the location where it is specified +on the command line. If the archive defines a symbol which was undefined in +some object which appeared before the archive on the command line, the linker +will include the appropriate file(s) from the archive. However, an undefined +symbol in an object appearing later on the command line will not cause the +linker to search the archive again. +.Pp +See the +.Op -( +option for a way to force the linker to search archives multiple times. +.Pp +You may list the same archive multiple times on the command line. +.Pp +This type of archive searching is standard for Unix linkers. However, if you +are using +.Xr ld +on AIX, note that it is different from the behaviour of the AIX linker. +.Pp +.It -L Va searchdir +.It --library-path= Va searchdir +Add path +.Va searchdir +to the list of paths that +.Xr ld +will search for archive libraries and +.Xr ld +control scripts. You may use this option any number of times. The directories +are searched in the order in which they are specified on the command line. +Directories specified on the command line are searched before the default +directories. All +.Op -L +options apply to all +.Op -l +options, regardless of the order in which the options appear. +.Pp +If +.Va searchdir +begins with +.Li = , +then the +.Li = +will be replaced by the +.Em sysroot prefix , +a path specified when the linker is configured. +.Pp +The default set of paths searched (without being specified with +.Li -L ) +depends on which emulation mode +.Xr ld +is using, and in some cases also on how it was configured.See Section +.Dq Environment . +.Pp +The paths can also be specified in a link script with the +.Li SEARCH_DIR +command. Directories specified this way are searched at the point in which +the linker script appears in the command line. +.Pp +.It -m Va emulation +Emulate the +.Va emulation +linker. You can list the available emulations with the +.Li --verbose +or +.Li -V +options. +.Pp +If the +.Li -m +option is not used, the emulation is taken from the +.Li LDEMULATION +environment variable, if that is defined. +.Pp +Otherwise, the default emulation depends upon how the linker was configured. +.Pp +.It -M +.It --print-map +Print a link map to the standard output. A link map provides information about +the link, including the following: +.Pp +.Bl -bullet +.It +Where object files are mapped into memory. +.It +How common symbols are allocated. +.It +All archive members included in the link, with a mention of the symbol which +caused the archive member to be brought in. +.It +The values assigned to symbols. +.Pp +Note - symbols whose values are computed by an expression which involves a +reference to a previous value of the same symbol may not have correct result +displayed in the link map. This is because the linker discards intermediate +results and only retains the final value of an expression. Under such circumstances +the linker will display the final value enclosed by square brackets. Thus +for example a linker script containing: +.Pp +.Bd -literal -offset indent + foo = 1 + foo = foo * 4 + foo = foo + 8 +.Ed +.Pp +will produce the following output in the link map if the +.Op -M +option is used: +.Pp +.Bd -literal -offset indent + 0x00000001 foo = 0x1 + [0x0000000c] foo = (foo * 0x4) + [0x0000000c] foo = (foo + 0x8) +.Ed +.Pp +See Expressions for more information about expressions in linker scripts. +.El +.Pp +.It -n +.It --nmagic +Turn off page alignment of sections, and mark the output as +.Li NMAGIC +if possible. +.Pp +.It -N +.It --omagic +Set the text and data sections to be readable and writable. Also, do not page-align +the data segment, and disable linking against shared libraries. If the output +format supports Unix style magic numbers, mark the output as +.Li OMAGIC . +Note: Although a writable text section is allowed for PE-COFF targets, it +does not conform to the format specification published by Microsoft. +.Pp +.It --no-omagic +This option negates most of the effects of the +.Op -N +option. It sets the text section to be read-only, and forces the data segment +to be page-aligned. Note - this option does not enable linking against shared +libraries. Use +.Op -Bdynamic +for this. +.Pp +.It -o Va output +.It --output= Va output +Use +.Va output +as the name for the program produced by +.Xr ld ; +if this option is not specified, the name +.Pa a.out +is used by default. The script command +.Li OUTPUT +can also specify the output file name. +.Pp +.It -O Va level +If +.Va level +is a numeric values greater than zero +.Xr ld +optimizes the output. This might take significantly longer and therefore probably +should only be enabled for the final binary. +.Pp +.It -q +.It --emit-relocs +Leave relocation sections and contents in fully linked executables. Post link +analysis and optimization tools may need this information in order to perform +correct modifications of executables. This results in larger executables. +.Pp +This option is currently only supported on ELF platforms. +.Pp +.It --force-dynamic +Force the output file to have dynamic sections. This option is specific to +VxWorks targets. +.Pp +.It -r +.It --relocatable +Generate relocatable output---i.e., generate an output file that can in turn +serve as input to +.Xr ld . +This is often called +.Em 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 +.Li OMAGIC . +If this option is not specified, an absolute file is produced. When linking +C++ programs, this option +.Em will not +resolve references to constructors; to do that, use +.Li -Ur . +.Pp +When an input file does not have the same format as the output file, partial +linking is only supported if that input file does not contain any relocations. +Different output formats can have further restrictions; for example some +.Li a.out +-based formats do not support partial linking with input files in other formats +at all. +.Pp +This option does the same thing as +.Li -i . +.Pp +.It -R Va filename +.It --just-symbols= Va filename +Read symbol names and their addresses from +.Va 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. You may use this option more than once. +.Pp +For compatibility with other ELF linkers, if the +.Op -R +option is followed by a directory name, rather than a file name, it is treated +as the +.Op -rpath +option. +.Pp +.It -s +.It --strip-all +Omit all symbol information from the output file. +.Pp +.It -S +.It --strip-debug +Omit debugger symbol information (but not all symbols) from the output file. +.Pp +.It -t +.It --trace +Print the names of the input files as +.Xr ld +processes them. +.Pp +.It -T Va scriptfile +.It --script= Va scriptfile +Use +.Va scriptfile +as the linker script. This script replaces +.Xr ld +\&'s default linker script (rather than adding to it), so +.Va commandfile +must specify everything necessary to describe the output file.See Section +.Dq Scripts . +If +.Va scriptfile +does not exist in the current directory, +.Li ld +looks for it in the directories specified by any preceding +.Li -L +options. Multiple +.Li -T +options accumulate. +.Pp +.It -dT Va scriptfile +.It --default-script= Va scriptfile +Use +.Va scriptfile +as the default linker script.See Section +.Dq Scripts . +.Pp +This option is similar to the +.Op --script +option except that processing of the script is delayed until after the rest +of the command line has been processed. This allows options placed after the +.Op --default-script +option on the command line to affect the behaviour of the linker script, which +can be important when the linker command line cannot be directly controlled +by the user. (eg because the command line is being constructed by another +tool, such as +.Li gcc ) . +.Pp +.It -u Va symbol +.It --undefined= Va symbol +Force +.Va 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. +.Li -u +may be repeated with different option arguments to enter additional undefined +symbols. This option is equivalent to the +.Li EXTERN +linker script command. +.Pp +.It -Ur +For anything other than C++ programs, this option is equivalent to +.Li -r : +it generates relocatable output---i.e., an output file that can in turn serve +as input to +.Xr ld . +When linking C++ programs, +.Li -Ur +.Em does +resolve references to constructors, unlike +.Li -r . +It does not work to use +.Li -Ur +on files that were themselves linked with +.Li -Ur ; +once the constructor table has been built, it cannot be added to. Use +.Li -Ur +only for the last partial link, and +.Li -r +for the others. +.Pp +.It --unique[= Va SECTION] +Creates a separate output section for every input section matching +.Va SECTION , +or if the optional wildcard +.Va SECTION +argument is missing, for every orphan input section. An orphan section is +one not specifically mentioned in a linker script. You may use this option +multiple times on the command line; It prevents the normal merging of input +sections with the same name, overriding output section assignments in a linker +script. +.Pp +.It -v +.It --version +.It -V +Display the version number for +.Xr ld . +The +.Op -V +option also lists the supported emulations. +.Pp +.It -x +.It --discard-all +Delete all local symbols. +.Pp +.It -X +.It --discard-locals +Delete all temporary local symbols. (These symbols start with system-specific +local label prefixes, typically +.Li .L +for ELF systems or +.Li L +for traditional a.out systems.) +.Pp +.It -y Va symbol +.It --trace-symbol= Va symbol +Print the name of each linked file in which +.Va symbol +appears. This option may be given any number of times. On many systems it +is necessary to prepend an underscore. +.Pp +This option is useful when you have an undefined symbol in your link but don't +know where the reference is coming from. +.Pp +.It -Y Va path +Add +.Va path +to the default library search path. This option exists for Solaris compatibility. +.Pp +.It -z Va keyword +The recognized keywords are: +.Bl -tag -width Ds +.It combreloc +Combines multiple reloc sections and sorts them to make dynamic symbol lookup +caching possible. +.Pp +.It defs +Disallows undefined symbols in object files. Undefined symbols in shared libraries +are still allowed. +.Pp +.It execstack +Marks the object as requiring executable stack. +.Pp +.It initfirst +This option is only meaningful when building a shared object. It marks the +object so that its runtime initialization will occur before the runtime initialization +of any other objects brought into the process at the same time. Similarly +the runtime finalization of the object will occur after the runtime finalization +of any other objects. +.Pp +.It interpose +Marks the object that its symbol table interposes before all symbols but the +primary executable. +.Pp +.It lazy +When generating an executable or shared library, mark it to tell the dynamic +linker to defer function call resolution to the point when the function is +called (lazy binding), rather than at load time. Lazy binding is the default. +.Pp +.It loadfltr +Marks the object that its filters be processed immediately at runtime. +.Pp +.It muldefs +Allows multiple definitions. +.Pp +.It nocombreloc +Disables multiple reloc sections combining. +.Pp +.It nocopyreloc +Disables production of copy relocs. +.Pp +.It nodefaultlib +Marks the object that the search for dependencies of this object will ignore +any default library search paths. +.Pp +.It nodelete +Marks the object shouldn't be unloaded at runtime. +.Pp +.It nodlopen +Marks the object not available to +.Li dlopen . +.Pp +.It nodump +Marks the object can not be dumped by +.Li dldump . +.Pp +.It noexecstack +Marks the object as not requiring executable stack. +.Pp +.It norelro +Don't create an ELF +.Li PT_GNU_RELRO +segment header in the object. +.Pp +.It now +When generating an executable or shared library, mark it to tell the dynamic +linker to resolve all symbols when the program is started, or when the shared +library is linked to using dlopen, instead of deferring function call resolution +to the point when the function is first called. +.Pp +.It origin +Marks the object may contain $ORIGIN. +.Pp +.It relro +Create an ELF +.Li PT_GNU_RELRO +segment header in the object. +.Pp +.It max-page-size= Va value +Set the emulation maximum page size to +.Va value . +.Pp +.It common-page-size= Va value +Set the emulation common page size to +.Va value . +.Pp +.El +Other keywords are ignored for Solaris compatibility. +.Pp +.It -( Va archives -) +.It --start-group Va archives --end-group +The +.Va archives +should be a list of archive files. They may be either explicit file names, +or +.Li -l +options. +.Pp +The specified archives are searched repeatedly until no new undefined references +are created. Normally, an archive is searched only once in the order that +it is specified on the command line. If a symbol in that archive is needed +to resolve an undefined symbol referred to by an object in an archive that +appears later on the command line, the linker would not be able to resolve +that reference. By grouping the archives, they all be searched repeatedly +until all possible references are resolved. +.Pp +Using this option has a significant performance cost. It is best to use it +only when there are unavoidable circular references between two or more archives. +.Pp +.It --accept-unknown-input-arch +.It --no-accept-unknown-input-arch +Tells the linker to accept input files whose architecture cannot be recognised. +The assumption is that the user knows what they are doing and deliberately +wants to link in these unknown input files. This was the default behaviour +of the linker, before release 2.14. The default behaviour from release 2.14 +onwards is to reject such input files, and so the +.Li --accept-unknown-input-arch +option has been added to restore the old behaviour. +.Pp +.It --as-needed +.It --no-as-needed +This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on +the command line after the +.Op --as-needed +option. Normally, the linker will add a DT_NEEDED tag for each dynamic library +mentioned on the command line, regardless of whether the library is actually +needed. +.Op --as-needed +causes DT_NEEDED tags to only be emitted for libraries that satisfy some symbol +reference from regular objects which is undefined at the point that the library +was linked. +.Op --no-as-needed +restores the default behaviour. +.Pp +.It --add-needed +.It --no-add-needed +This option affects the treatment of dynamic libraries from ELF DT_NEEDED +tags in dynamic libraries mentioned on the command line after the +.Op --no-add-needed +option. Normally, the linker will add a DT_NEEDED tag for each dynamic library +from DT_NEEDED tags. +.Op --no-add-needed +causes DT_NEEDED tags will never be emitted for those libraries from DT_NEEDED +tags. +.Op --add-needed +restores the default behaviour. +.Pp +.It -assert Va keyword +This option is ignored for SunOS compatibility. +.Pp +.It -Bdynamic +.It -dy +.It -call_shared +Link against dynamic libraries. This is only meaningful on platforms for which +shared libraries are supported. This option is normally the default on such +platforms. The different variants of this option are for compatibility with +various systems. You may use this option multiple times on the command line: +it affects library searching for +.Op -l +options which follow it. +.Pp +.It -Bgroup +Set the +.Li DF_1_GROUP +flag in the +.Li DT_FLAGS_1 +entry in the dynamic section. This causes the runtime linker to handle lookups +in this object and its dependencies to be performed only inside the group. +.Op --unresolved-symbols=report-all +is implied. This option is only meaningful on ELF platforms which support +shared libraries. +.Pp +.It -Bstatic +.It -dn +.It -non_shared +.It -static +Do not link against shared libraries. This is only meaningful on platforms +for which shared libraries are supported. The different variants of this option +are for compatibility with various systems. You may use this option multiple +times on the command line: it affects library searching for +.Op -l +options which follow it. This option also implies +.Op --unresolved-symbols=report-all . +This option can be used with +.Op -shared . +Doing so means that a shared library is being created but that all of the +library's external references must be resolved by pulling in entries from +static libraries. +.Pp +.It -Bsymbolic +When creating a shared library, bind references to global symbols to the definition +within the shared library, if any. Normally, it is possible for a program +linked against a shared library to override the definition within the shared +library. This option is only meaningful on ELF platforms which support shared +libraries. +.Pp +.It -Bsymbolic-functions +When creating a shared library, bind references to global function symbols +to the definition within the shared library, if any. This option is only meaningful +on ELF platforms which support shared libraries. +.Pp +.It --dynamic-list= Va dynamic-list-file +Specify the name of a dynamic list file to the linker. This is typically used +when creating shared libraries to specify a list of global symbols whose references +shouldn't be bound to the definition within the shared library, or creating +dynamically linked executables to specify a list of symbols which should be +added to the symbol table in the executable. This option is only meaningful +on ELF platforms which support shared libraries. +.Pp +The format of the dynamic list is the same as the version node without scope +and node name. See VERSION for more information. +.Pp +.It --dynamic-list-data +Include all global data symbols to the dynamic list. +.Pp +.It --dynamic-list-cpp-new +Provide the builtin dynamic list for C++ operator new and delete. It is mainly +useful for building shared libstdc++. +.Pp +.It --dynamic-list-cpp-typeinfo +Provide the builtin dynamic list for C++ runtime type identification. +.Pp +.It --check-sections +.It --no-check-sections +Asks the linker +.Em not +to check section addresses after they have been assigned to see if there are +any overlaps. Normally the linker will perform this check, and if it finds +any overlaps it will produce suitable error messages. The linker does know +about, and does make allowances for sections in overlays. The default behaviour +can be restored by using the command line switch +.Op --check-sections . +.Pp +.It --cref +Output a cross reference table. If a linker map file is being generated, the +cross reference table is printed to the map file. Otherwise, it is printed +on the standard output. +.Pp +The format of the table is intentionally simple, so that it may be easily +processed by a script if necessary. The symbols are printed out, sorted by +name. For each symbol, a list of file names is given. If the symbol is defined, +the first file listed is the location of the definition. The remaining files +contain references to the symbol. +.Pp +.It --no-define-common +This option inhibits the assignment of addresses to common symbols. The script +command +.Li INHIBIT_COMMON_ALLOCATION +has the same effect.See Section +.Dq Miscellaneous Commands . +.Pp +The +.Li --no-define-common +option allows decoupling the decision to assign addresses to Common symbols +from the choice of the output file type; otherwise a non-Relocatable output +type forces assigning addresses to Common symbols. Using +.Li --no-define-common +allows Common symbols that are referenced from a shared library to be assigned +addresses only in the main program. This eliminates the unused duplicate space +in the shared library, and also prevents any possible confusion over resolving +to the wrong duplicate when there are many dynamic modules with specialized +search paths for runtime symbol resolution. +.Pp +.It --defsym Va symbol= Va expression +Create a global symbol in the output file, containing the absolute address +given by +.Va 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 +.Va expression +in this context: you may give a hexadecimal constant or the name of an existing +symbol, or use +.Li + +and +.Li - +to add or subtract hexadecimal constants or symbols. If you need more elaborate +expressions, consider using the linker command language from a script (see Section +.Dq Assignments ) . +.Em Note: +there should be no white space between +.Va symbol , +the equals sign (\(lq=\(rq), and +.Va expression . +.Pp +.It --demangle[= Va style] +.It --no-demangle +These options control whether to demangle symbol names in error messages and +other output. When the linker is told to demangle, it tries to present symbol +names in a readable fashion: it strips leading underscores if they are used +by the object file format, and converts C++ mangled symbol names into user +readable names. Different compilers have different mangling styles. The optional +demangling style argument can be used to choose an appropriate demangling +style for your compiler. The linker will demangle by default unless the environment +variable +.Li COLLECT_NO_DEMANGLE +is set. These options may be used to override the default. +.Pp +.It --dynamic-linker Va file +Set the name of the dynamic linker. This is only meaningful when generating +dynamically linked ELF executables. The default dynamic linker is normally +correct; don't use this unless you know what you are doing. +.Pp +.It --fatal-warnings +Treat all warnings as errors. +.Pp +.It --force-exe-suffix +Make sure that an output file has a .exe suffix. +.Pp +If a successfully built fully linked output file does not have a +.Li .exe +or +.Li .dll +suffix, this option forces the linker to copy the output file to one of the +same name with a +.Li .exe +suffix. This option is useful when using unmodified Unix makefiles on a Microsoft +Windows host, since some versions of Windows won't run an image unless it +ends in a +.Li .exe +suffix. +.Pp +.It --gc-sections +.It --no-gc-sections +Enable garbage collection of unused input sections. It is ignored on targets +that do not support this option. This option is not compatible with +.Li -r +or +.Li --emit-relocs . +The default behaviour (of not performing this garbage collection) can be restored +by specifying +.Li --no-gc-sections +on the command line. +.Pp +.It --print-gc-sections +.It --no-print-gc-sections +List all sections removed by garbage collection. The listing is printed on +stderr. This option is only effective if garbage collection has been enabled +via the +.Li --gc-sections ) +option. The default behaviour (of not listing the sections that are removed) +can be restored by specifying +.Li --no-print-gc-sections +on the command line. +.Pp +.It --help +Print a summary of the command-line options on the standard output and exit. +.Pp +.It --target-help +Print a summary of all target specific options on the standard output and +exit. +.Pp +.It -Map Va mapfile +Print a link map to the file +.Va mapfile . +See the description of the +.Op -M +option, above. +.Pp +.It --no-keep-memory +.Xr ld +normally optimizes for speed over memory usage by caching the symbol tables +of input files in memory. This option tells +.Xr ld +to instead optimize for memory usage, by rereading the symbol tables as necessary. +This may be required if +.Xr ld +runs out of memory space while linking a large executable. +.Pp +.It --no-undefined +.It -z defs +Report unresolved symbol references from regular object files. This is done +even if the linker is creating a non-symbolic shared library. The switch +.Op --[no-]allow-shlib-undefined +controls the behaviour for reporting unresolved references found in shared +libraries being linked in. +.Pp +.It --allow-multiple-definition +.It -z muldefs +Normally when a symbol is defined multiple times, the linker will report a +fatal error. These options allow multiple definitions and the first definition +will be used. +.Pp +.It --allow-shlib-undefined +.It --no-allow-shlib-undefined +Allows (the default) or disallows undefined symbols in shared libraries. This +switch is similar to +.Op --no-undefined +except that it determines the behaviour when the undefined symbols are in +a shared library rather than a regular object file. It does not affect how +undefined symbols in regular object files are handled. +.Pp +The reason that +.Op --allow-shlib-undefined +is the default is that the shared library being specified at link time may +not be the same as the one that is available at load time, so the symbols +might actually be resolvable at load time. Plus there are some systems, (eg +BeOS) where undefined symbols in shared libraries is normal. (The kernel patches +them at load time to select which function is most appropriate for the current +architecture. This is used for example to dynamically select an appropriate +memset function). Apparently it is also normal for HPPA shared libraries to +have undefined symbols. +.Pp +.It --no-undefined-version +Normally when a symbol has an undefined version, the linker will ignore it. +This option disallows symbols with undefined version and a fatal error will +be issued instead. +.Pp +.It --default-symver +Create and use a default symbol version (the soname) for unversioned exported +symbols. +.Pp +.It --default-imported-symver +Create and use a default symbol version (the soname) for unversioned imported +symbols. +.Pp +.It --no-warn-mismatch +Normally +.Xr ld +will give an error if you try to link together input files that are mismatched +for some reason, perhaps because they have been compiled for different processors +or for different endiannesses. This option tells +.Xr ld +that it should silently permit such possible errors. This option should only +be used with care, in cases when you have taken some special action that ensures +that the linker errors are inappropriate. +.Pp +.It --no-warn-search-mismatch +Normally +.Xr ld +will give a warning if it finds an incompatible library during a library search. +This option silences the warning. +.Pp +.It --no-whole-archive +Turn off the effect of the +.Op --whole-archive +option for subsequent archive files. +.Pp +.It --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. +.Pp +.It -nostdlib +Only search library directories explicitly specified on the command line. +Library directories specified in linker scripts (including linker scripts +specified on the command line) are ignored. +.Pp +.It --oformat Va output-format +.Xr ld +may be configured to support more than one kind of object file. If your +.Xr ld +is configured this way, you can use the +.Li --oformat +option to specify the binary format for the output object file. Even when +.Xr ld +is configured to support alternative object formats, you don't usually need +to specify this, as +.Xr ld +should be configured to produce as a default output format the most usual +format on each machine. +.Va 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 +.Li objdump -i . ) +The script command +.Li OUTPUT_FORMAT +can also specify the output format, but this option overrides it.See Section +.Dq BFD . +.Pp +.It -pie +.It --pic-executable +Create a position independent executable. This is currently only supported +on ELF platforms. Position independent executables are similar to shared libraries +in that they are relocated by the dynamic linker to the virtual address the +OS chooses for them (which can vary between invocations). Like normal dynamically +linked executables they can be executed and symbols defined in the executable +cannot be overridden by shared libraries. +.Pp +.It -qmagic +This option is ignored for Linux compatibility. +.Pp +.It -Qy +This option is ignored for SVR4 compatibility. +.Pp +.It --relax +An option with machine dependent effects. This option is only supported on +a few targets.See Section +.Dq H8/300 . +See Section.Dq i960 . +See Section.Dq Xtensa . +See Section.Dq M68HC11/68HC12 . +See Section.Dq PowerPC ELF32 . +.Pp +On some platforms, the +.Li --relax +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. +.Pp +On some platforms these link time global optimizations may make symbolic debugging +of the resulting executable impossible. This is known to be the case for the +Matsushita MN10200 and MN10300 family of processors. +.Pp +On platforms where this is not supported, +.Li --relax +is accepted, but ignored. +.Pp +.It --retain-symbols-file Va filename +Retain +.Em only +the symbols listed in the file +.Va filename , +discarding all others. +.Va filename +is simply a flat file, with one symbol name per line. This option is especially +useful in environments (such as VxWorks) where a large global symbol table +is accumulated gradually, to conserve run-time memory. +.Pp +.Li --retain-symbols-file +does +.Em not +discard undefined symbols, or symbols needed for relocations. +.Pp +You may only specify +.Li --retain-symbols-file +once in the command line. It overrides +.Li -s +and +.Li -S . +.Pp +.It -rpath Va dir +Add a directory to the runtime library search path. This is used when linking +an ELF executable with shared objects. All +.Op -rpath +arguments are concatenated and passed to the runtime linker, which uses them +to locate shared objects at runtime. The +.Op -rpath +option is also used when locating shared objects which are needed by shared +objects explicitly included in the link; see the description of the +.Op -rpath-link +option. If +.Op -rpath +is not used when linking an ELF executable, the contents of the environment +variable +.Li LD_RUN_PATH +will be used if it is defined. +.Pp +The +.Op -rpath +option may also be used on SunOS. By default, on SunOS, the linker will form +a runtime search patch out of all the +.Op -L +options it is given. If a +.Op -rpath +option is used, the runtime search path will be formed exclusively using the +.Op -rpath +options, ignoring the +.Op -L +options. This can be useful when using gcc, which adds many +.Op -L +options which may be on NFS mounted file systems. +.Pp +For compatibility with other ELF linkers, if the +.Op -R +option is followed by a directory name, rather than a file name, it is treated +as the +.Op -rpath +option. +.Pp +.It -rpath-link Va DIR +When using ELF or SunOS, one shared library may require another. This happens +when an +.Li ld -shared +link includes a shared library as one of the input files. +.Pp +When the linker encounters such a dependency when doing a non-shared, non-relocatable +link, it will automatically try to locate the required shared library and +include it in the link, if it is not included explicitly. In such a case, +the +.Op -rpath-link +option specifies the first set of directories to search. The +.Op -rpath-link +option may specify a sequence of directory names either by specifying a list +of names separated by colons, or by appearing multiple times. +.Pp +This option should be used with caution as it overrides the search path that +may have been hard compiled into a shared library. In such a case it is possible +to use unintentionally a different search path than the runtime linker would +do. +.Pp +The linker uses the following search paths to locate required shared libraries: +.Bl -enum +.It +Any directories specified by +.Op -rpath-link +options. +.It +Any directories specified by +.Op -rpath +options. The difference between +.Op -rpath +and +.Op -rpath-link +is that directories specified by +.Op -rpath +options are included in the executable and used at runtime, whereas the +.Op -rpath-link +option is only effective at link time. Searching +.Op -rpath +in this way is only supported by native linkers and cross linkers which have +been configured with the +.Op --with-sysroot +option. +.It +On an ELF system, if the +.Op -rpath +and +.Li rpath-link +options were not used, search the contents of the environment variable +.Li LD_RUN_PATH . +It is for the native linker only. +.It +On SunOS, if the +.Op -rpath +option was not used, search any directories specified using +.Op -L +options. +.It +For a native linker, the contents of the environment variable +.Li LD_LIBRARY_PATH . +.It +For a native ELF linker, the directories in +.Li DT_RUNPATH +or +.Li DT_RPATH +of a shared library are searched for shared libraries needed by it. The +.Li DT_RPATH +entries are ignored if +.Li DT_RUNPATH +entries exist. +.It +The default directories, normally +.Pa /lib +and +.Pa /usr/lib . +.It +For a native linker on an ELF system, if the file +.Pa /etc/ld.so.conf +exists, the list of directories found in that file. +.El +.Pp +If the required shared library is not found, the linker will issue a warning +and continue with the link. +.Pp +.It -shared +.It -Bshareable +Create a shared library. This is currently only supported on ELF, XCOFF and +SunOS platforms. On SunOS, the linker will automatically create a shared library +if the +.Op -e +option is not used and there are undefined symbols in the link. +.Pp +.It --sort-common +This option tells +.Xr ld +to sort the common symbols by size when it places them in the appropriate +output sections. First come all the one byte symbols, then all the two byte, +then all the four byte, and then everything else. This is to prevent gaps +between symbols due to alignment constraints. +.Pp +.It --sort-section name +This option will apply +.Li SORT_BY_NAME +to all wildcard section patterns in the linker script. +.Pp +.It --sort-section alignment +This option will apply +.Li SORT_BY_ALIGNMENT +to all wildcard section patterns in the linker script. +.Pp +.It --split-by-file [ Va size] +Similar to +.Op --split-by-reloc +but creates a new output section for each input file when +.Va size +is reached. +.Va size +defaults to a size of 1 if not given. +.Pp +.It --split-by-reloc [ Va count] +Tries to creates extra sections in the output file so that no single output +section in the file contains more than +.Va count +relocations. This is useful when generating huge relocatable files for downloading +into certain real time kernels with the COFF object file format; since COFF +cannot represent more than 65535 relocations in a single section. Note that +this will fail to work with object file formats which do not support arbitrary +sections. The linker will not split up individual input sections for redistribution, +so if a single input section contains more than +.Va count +relocations one output section will contain that many relocations. +.Va count +defaults to a value of 32768. +.Pp +.It --stats +Compute and display statistics about the operation of the linker, such as +execution time and memory usage. +.Pp +.It --sysroot= Va directory +Use +.Va directory +as the location of the sysroot, overriding the configure-time default. This +option is only supported by linkers that were configured using +.Op --with-sysroot . +.Pp +.It --traditional-format +For some targets, the output of +.Xr ld +is different in some ways from the output of some existing linker. This switch +requests +.Xr ld +to use the traditional format instead. +.Pp +For example, on SunOS, +.Xr ld +combines duplicate entries in the symbol string table. This can reduce the +size of an output file with full debugging information by over 30 percent. +Unfortunately, the SunOS +.Li dbx +program can not read the resulting program ( +.Li gdb +has no trouble). The +.Li --traditional-format +switch tells +.Xr ld +to not combine duplicate entries. +.Pp +.It --section-start Va sectionname= Va org +Locate a section in the output file at the absolute address given by +.Va org . +You may use this option as many times as necessary to locate multiple sections +in the command line. +.Va org +must be a single hexadecimal integer; for compatibility with other linkers, +you may omit the leading +.Li 0x +usually associated with hexadecimal values. +.Em Note: +there should be no white space between +.Va sectionname , +the equals sign (\(lq=\(rq), and +.Va org . +.Pp +.It -Tbss Va org +.It -Tdata Va org +.It -Ttext Va org +Same as --section-start, with +.Li .bss , +.Li .data +or +.Li .text +as the +.Va sectionname . +.Pp +.It --unresolved-symbols= Va method +Determine how to handle unresolved symbols. There are four possible values +for +.Li method : +.Pp +.Bl -tag -width Ds +.It ignore-all +Do not report any unresolved symbols. +.Pp +.It report-all +Report all unresolved symbols. This is the default. +.Pp +.It ignore-in-object-files +Report unresolved symbols that are contained in shared libraries, but ignore +them if they come from regular object files. +.Pp +.It ignore-in-shared-libs +Report unresolved symbols that come from regular object files, but ignore +them if they come from shared libraries. This can be useful when creating +a dynamic binary and it is known that all the shared libraries that it should +be referencing are included on the linker's command line. +.El +.Pp +The behaviour for shared libraries on their own can also be controlled by +the +.Op --[no-]allow-shlib-undefined +option. +.Pp +Normally the linker will generate an error message for each reported unresolved +symbol but the option +.Op --warn-unresolved-symbols +can change this to a warning. +.Pp +.It --dll-verbose +.It --verbose +Display the version number for +.Xr ld +and list the linker emulations supported. Display which input files can and +cannot be opened. Display the linker script being used by the linker. +.Pp +.It --version-script= Va version-scriptfile +Specify the name of a version script to the linker. This is typically used +when creating shared libraries to specify additional information about the +version hierarchy for the library being created. This option is only meaningful +on ELF platforms which support shared libraries.See Section +.Dq VERSION . +.Pp +.It --warn-common +Warn when a common symbol is combined with another common symbol or with a +symbol definition. Unix linkers allow this somewhat sloppy practise, 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 practise, so you may get some warnings about symbols in the libraries +as well as in your programs. +.Pp +There are three kinds of global symbols, illustrated here by C examples: +.Pp +.Bl -tag -width Ds +.It int i = 1; +A definition, which goes in the initialized data section of the output file. +.Pp +.It 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. +.Pp +.It 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. +.El +.Pp +The +.Li --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. +.Pp +.Bl -enum +.It +Turning a common symbol into a reference, because there is already a definition +for the symbol. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overridden by definition +file(section): warning: defined here +.Ed +.Pp +.It +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. +.Bd -literal -offset indent +file(section): warning: definition of `symbol' + overriding common +file(section): warning: common is here +.Ed +.Pp +.It +Merging a common symbol with a previous same-sized common symbol. +.Bd -literal -offset indent +file(section): warning: multiple common + of `symbol' +file(section): warning: previous common is here +.Ed +.Pp +.It +Merging a common symbol with a previous larger common symbol. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overridden by larger common +file(section): warning: larger common is here +.Ed +.Pp +.It +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. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overriding smaller common +file(section): warning: smaller common is here +.Ed +.El +.Pp +.It --warn-constructors +Warn if any global constructors are used. This is only useful for a few object +file formats. For formats like COFF or ELF, the linker can not detect the +use of global constructors. +.Pp +.It --warn-multiple-gp +Warn if multiple global pointer values are required in the output file. This +is only meaningful for certain processors, such as the Alpha. Specifically, +some processors put large-valued constants in a special section. A special +register (the global pointer) points into the middle of this section, so that +constants can be loaded efficiently via a base-register relative addressing +mode. Since the offset in base-register relative mode is fixed and relatively +small (e.g., 16 bits), this limits the maximum size of the constant pool. +Thus, in large programs, it is often necessary to use multiple global pointer +values in order to be able to address all possible constants. This option +causes a warning to be issued whenever this case occurs. +.Pp +.It --warn-once +Only warn once for each undefined symbol, rather than once per module which +refers to it. +.Pp +.It --warn-section-align +Warn if the address of an output section is changed because of alignment. +Typically, the alignment will be set by an input section. The address will +only be changed if it not explicitly specified; that is, if the +.Li SECTIONS +command does not specify a start address for the section (see Section +.Dq SECTIONS ) . +.Pp +.It --warn-shared-textrel +Warn if the linker adds a DT_TEXTREL to a shared object. +.Pp +.It --warn-unresolved-symbols +If the linker is going to report an unresolved symbol (see the option +.Op --unresolved-symbols ) +it will normally generate an error. This option makes it generate a warning +instead. +.Pp +.It --error-unresolved-symbols +This restores the linker's default behaviour of generating errors when it +is reporting unresolved symbols. +.Pp +.It --whole-archive +For each archive mentioned on the command line after the +.Op --whole-archive +option, include every object file in the archive in the link, rather than +searching the archive for the required object files. This is normally used +to turn an archive file into a shared library, forcing every object to be +included in the resulting shared library. This option may be used more than +once. +.Pp +Two notes when using this option from gcc: First, gcc doesn't know about this +option, so you have to use +.Op -Wl,-whole-archive . +Second, don't forget to use +.Op -Wl,-no-whole-archive +after your list of archives, because gcc will add its own list of archives +to your link and you may not want this flag to affect those as well. +.Pp +.It --wrap Va symbol +Use a wrapper function for +.Va symbol . +Any undefined reference to +.Va symbol +will be resolved to +.Li __wrap_ Va symbol . +Any undefined reference to +.Li __real_ Va symbol +will be resolved to +.Va symbol . +.Pp +This can be used to provide a wrapper for a system function. The wrapper function +should be called +.Li __wrap_ Va symbol . +If it wishes to call the system function, it should call +.Li __real_ Va symbol . +.Pp +Here is a trivial example: +.Pp +.Bd -literal -offset indent +void * +__wrap_malloc (size_t c) +{ + printf ("malloc called with %zu\en", c); + return __real_malloc (c); +} +.Ed +.Pp +If you link other code with this file using +.Op --wrap malloc , +then all calls to +.Li malloc +will call the function +.Li __wrap_malloc +instead. The call to +.Li __real_malloc +in +.Li __wrap_malloc +will call the real +.Li malloc +function. +.Pp +You may wish to provide a +.Li __real_malloc +function as well, so that links without the +.Op --wrap +option will succeed. If you do this, you should not put the definition of +.Li __real_malloc +in the same file as +.Li __wrap_malloc ; +if you do, the assembler may resolve the call before the linker has a chance +to wrap it to +.Li malloc . +.Pp +.It --eh-frame-hdr +Request creation of +.Li .eh_frame_hdr +section and ELF +.Li PT_GNU_EH_FRAME +segment header. +.Pp +.It --enable-new-dtags +.It --disable-new-dtags +This linker can create the new dynamic tags in ELF. But the older ELF systems +may not understand them. If you specify +.Op --enable-new-dtags , +the dynamic tags will be created as needed. If you specify +.Op --disable-new-dtags , +no new dynamic tags will be created. By default, the new dynamic tags are +not created. Note that those options are only available for ELF systems. +.Pp +.It --hash-size= Va number +Set the default size of the linker's hash tables to a prime number close to +.Va number . +Increasing this value can reduce the length of time it takes the linker to +perform its tasks, at the expense of increasing the linker's memory requirements. +Similarly reducing this value can reduce the memory requirements at the expense +of speed. +.Pp +.It --hash-style= Va style +Set the type of linker's hash table(s). +.Va style +can be either +.Li sysv +for classic ELF +.Li .hash +section, +.Li GNU +for new style GNU +.Li .GNU.hash +section or +.Li both +for both the classic ELF +.Li .hash +and new style GNU +.Li .GNU.hash +hash tables. The default is +.Li sysv . +.Pp +.It --reduce-memory-overheads +This option reduces memory requirements at ld runtime, at the expense of linking +speed. This was introduced to select the old O(n^2) algorithm for link map +file generation, rather than the new O(n) algorithm which uses about 40% more +memory for symbol storage. +.Pp +Another effect of the switch is to set the default hash table size to 1021, +which again saves memory at the cost of lengthening the linker's run time. +This is not done however if the +.Op --hash-size +switch has been used. +.Pp +The +.Op --reduce-memory-overheads +switch may be also be used to enable other tradeoffs in future versions of +the linker. +.Pp +.El +.Em Options Specific to i386 PE Targets +.Pp +The i386 PE linker supports the +.Op -shared +option, which causes the output to be a dynamically linked library (DLL) instead +of a normal executable. You should name the output +.Li *.dll +when you use this option. In addition, the linker fully supports the standard +.Li *.def +files, which may be specified on the linker command line like an object file +(in fact, it should precede archives it exports symbols from, to ensure that +they get linked in, just like a normal object file). +.Pp +In addition to the options common to all targets, the i386 PE linker support +additional command line options that are specific to the i386 PE target. Options +that take values may be separated from their values by either a space or an +equals sign. +.Pp +.Bl -tag -width Ds +.It --add-stdcall-alias +If given, symbols with a stdcall suffix (@ +.Va nn ) +will be exported as-is and also with the suffix stripped. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --base-file Va file +Use +.Va file +as the name of a file in which to save the base addresses of all the relocations +needed for generating DLLs with +.Pa dlltool . +[This is an i386 PE specific option] +.Pp +.It --dll +Create a DLL instead of a regular executable. You may also use +.Op -shared +or specify a +.Li LIBRARY +in a given +.Li .def +file. [This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --enable-stdcall-fixup +.It --disable-stdcall-fixup +If the link finds a symbol that it cannot resolve, it will attempt to do \(lqfuzzy +linking\(rq by looking for another defined symbol that differs only in the format +of the symbol name (cdecl vs stdcall) and will resolve that symbol by linking +to the match. For example, the undefined symbol +.Li _foo +might be linked to the function +.Li _foo@12 , +or the undefined symbol +.Li _bar@16 +might be linked to the function +.Li _bar . +When the linker does this, it prints a warning, since it normally should have +failed to link, but sometimes import libraries generated from third-party +dlls may need this feature to be usable. If you specify +.Op --enable-stdcall-fixup , +this feature is fully enabled and warnings are not printed. If you specify +.Op --disable-stdcall-fixup , +this feature is disabled and such mismatches are considered to be errors. +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --export-all-symbols +If given, all global symbols in the objects used to build a DLL will be exported +by the DLL. Note that this is the default if there otherwise wouldn't be any +exported symbols. When symbols are explicitly exported via DEF files or implicitly +exported via function attributes, the default is to not export anything else +unless this option is given. Note that the symbols +.Li DllMain@12 , +.Li DllEntryPoint@0 , +.Li DllMainCRTStartup@12 , +and +.Li impure_ptr +will not be automatically exported. Also, symbols imported from other DLLs +will not be re-exported, nor will symbols specifying the DLL's internal layout +such as those beginning with +.Li _head_ +or ending with +.Li _iname . +In addition, no symbols from +.Li libgcc , +.Li libstd++ , +.Li libmingw32 , +or +.Li crtX.o +will be exported. Symbols whose names begin with +.Li __rtti_ +or +.Li __builtin_ +will not be exported, to help with C++ DLLs. Finally, there is an extensive +list of cygwin-private symbols that are not exported (obviously, this applies +on when building DLLs for cygwin targets). These cygwin-excludes are: +.Li _cygwin_dll_entry@12 , +.Li _cygwin_crt0_common@8 , +.Li _cygwin_noncygwin_dll_entry@12 , +.Li _fmode , +.Li _impure_ptr , +.Li cygwin_attach_dll , +.Li cygwin_premain0 , +.Li cygwin_premain1 , +.Li cygwin_premain2 , +.Li cygwin_premain3 , +and +.Li environ . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --exclude-symbols Va symbol, Va symbol,... +Specifies a list of symbols which should not be automatically exported. The +symbol names may be delimited by commas or colons. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --file-alignment +Specify the file alignment. Sections in the file will always begin at file +offsets which are multiples of this number. This defaults to 512. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --heap Va reserve +.It --heap Va reserve, Va commit +Specify the amount of memory to reserve (and optionally commit) to be used +as heap for this program. The default is 1Mb reserved, 4K committed. [This +option is specific to the i386 PE targeted port of the linker] +.Pp +.It --image-base Va value +Use +.Va value +as the base address of your program or dll. This is the lowest memory location +that will be used when your program or dll is loaded. To reduce the need to +relocate and improve performance of your dlls, each should have a unique base +address and not overlap any other dlls. The default is 0x400000 for executables, +and 0x10000000 for dlls. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --kill-at +If given, the stdcall suffixes (@ +.Va nn ) +will be stripped from symbols before they are exported. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --large-address-aware +If given, the appropriate bit in the \(lqCharacteristics\(rq field of the COFF header +is set to indicate that this executable supports virtual addresses greater +than 2 gigabytes. This should be used in conjunction with the /3GB or /USERVA= +.Va value +megabytes switch in the \(lq[operating systems]\(rq section of the BOOT.INI. Otherwise, +this bit has no effect. [This option is specific to PE targeted ports of the +linker] +.Pp +.It --major-image-version Va value +Sets the major number of the \(lqimage version\(rq. Defaults to 1. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --major-os-version Va value +Sets the major number of the \(lqos version\(rq. Defaults to 4. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --major-subsystem-version Va value +Sets the major number of the \(lqsubsystem version\(rq. Defaults to 4. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --minor-image-version Va value +Sets the minor number of the \(lqimage version\(rq. Defaults to 0. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --minor-os-version Va value +Sets the minor number of the \(lqos version\(rq. Defaults to 0. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --minor-subsystem-version Va value +Sets the minor number of the \(lqsubsystem version\(rq. Defaults to 0. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --output-def Va file +The linker will create the file +.Va file +which will contain a DEF file corresponding to the DLL the linker is generating. +This DEF file (which should be called +.Li *.def ) +may be used to create an import library with +.Li dlltool +or may be used as a reference to automatically or implicitly exported symbols. +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --out-implib Va file +The linker will create the file +.Va file +which will contain an import lib corresponding to the DLL the linker is generating. +This import lib (which should be called +.Li *.dll.a +or +.Li *.a +may be used to link clients against the generated DLL; this behaviour makes +it possible to skip a separate +.Li dlltool +import library creation step. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --enable-auto-image-base +Automatically choose the image base for DLLs, unless one is specified using +the +.Li --image-base +argument. By using a hash generated from the dllname to create unique image +bases for each DLL, in-memory collisions and relocations which can delay program +execution are avoided. [This option is specific to the i386 PE targeted port +of the linker] +.Pp +.It --disable-auto-image-base +Do not automatically generate a unique image base. If there is no user-specified +image base ( +.Li --image-base ) +then use the platform default. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --dll-search-prefix Va string +When linking dynamically to a dll without an import library, search for +.Li <string><basename>.dll +in preference to +.Li lib<basename>.dll . +This behaviour allows easy distinction between DLLs built for the various +"subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically +use +.Li --dll-search-prefix=cyg . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --enable-auto-import +Do sophisticated linking of +.Li _symbol +to +.Li __imp__symbol +for DATA imports from DLLs, and create the necessary thunking symbols when +building the import libraries with those DATA exports. Note: Use of the 'auto-import' +extension will cause the text section of the image file to be made writable. +This does not conform to the PE-COFF format specification published by Microsoft. +.Pp +Using 'auto-import' generally will 'just work' -- but sometimes you may see +this message: +.Pp +"variable '<var>' can't be auto-imported. Please read the documentation for +ld's +.Li --enable-auto-import +for details." +.Pp +This message occurs when some (sub)expression accesses an address ultimately +given by the sum of two constants (Win32 import tables only allow one). Instances +where this may occur include accesses to member fields of struct variables +imported from a DLL, as well as using a constant index into an array variable +imported from a DLL. Any multiword variable (arrays, structs, long long, etc) +may trigger this error condition. However, regardless of the exact data type +of the offending exported variable, ld will always detect it, issue the warning, +and exit. +.Pp +There are several ways to address this difficulty, regardless of the data +type of the exported variable: +.Pp +One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task +of adjusting references in your client code for runtime environment, so this +method works only when runtime environment supports this feature. +.Pp +A second solution is to force one of the 'constants' to be a variable -- that +is, unknown and un-optimizable at compile time. For arrays, there are two +possibilities: a) make the indexee (the array's address) a variable, or b) +make the 'constant' index a variable. Thus: +.Pp +.Bd -literal -offset indent +extern type extern_array[]; +extern_array[1] --> + { volatile type *t=extern_array; t[1] } +.Ed +.Pp +or +.Pp +.Bd -literal -offset indent +extern type extern_array[]; +extern_array[1] --> + { volatile int t=1; extern_array[t] } +.Ed +.Pp +For structs (and most other multiword data types) the only option is to make +the struct itself (or the long long, or the ...) variable: +.Pp +.Bd -literal -offset indent +extern struct s extern_struct; +extern_struct.field --> + { volatile struct s *t=&extern_struct; t->field } +.Ed +.Pp +or +.Pp +.Bd -literal -offset indent +extern long long extern_ll; +extern_ll --> + { volatile long long * local_ll=&extern_ll; *local_ll } +.Ed +.Pp +A third method of dealing with this difficulty is to abandon 'auto-import' +for the offending symbol and mark it with +.Li __declspec(dllimport) . +However, in practise that requires using compile-time #defines to indicate +whether you are building a DLL, building client code that will link to the +DLL, or merely building/linking to a static library. In making the choice +between the various methods of resolving the 'direct address with constant +offset' problem, you should consider typical real-world usage: +.Pp +Original: +.Bd -literal -offset indent +--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + printf("%d\en",arr[1]); +} +.Ed +.Pp +Solution 1: +.Bd -literal -offset indent +--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + /* This workaround is for win32 and cygwin; do not "optimize" */ + volatile int *parr = arr; + printf("%d\en",parr[1]); +} +.Ed +.Pp +Solution 2: +.Bd -literal -offset indent +--foo.h +/* Note: auto-export is assumed (no __declspec(dllexport)) */ +#if (defined(_WIN32) || defined(__CYGWIN__)) && \e + !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) +#define FOO_IMPORT __declspec(dllimport) +#else +#define FOO_IMPORT +#endif +extern FOO_IMPORT int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + printf("%d\en",arr[1]); +} +.Ed +.Pp +A fourth way to avoid this problem is to re-code your library to use a functional +interface rather than a data interface for the offending variables (e.g. set_foo() +and get_foo() accessor functions). [This option is specific to the i386 PE +targeted port of the linker] +.Pp +.It --disable-auto-import +Do not attempt to do sophisticated linking of +.Li _symbol +to +.Li __imp__symbol +for DATA imports from DLLs. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --enable-runtime-pseudo-reloc +If your code contains expressions described in --enable-auto-import section, +that is, DATA imports from DLL with non-zero offset, this switch will create +a vector of 'runtime pseudo relocations' which can be used by runtime environment +to adjust references to such data in your client code. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --disable-runtime-pseudo-reloc +Do not create pseudo relocations for non-zero offset DATA imports from DLLs. +This is the default. [This option is specific to the i386 PE targeted port +of the linker] +.Pp +.It --enable-extra-pe-debug +Show additional debug info related to auto-import symbol thunking. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --section-alignment +Sets the section alignment. Sections in memory will always begin at addresses +which are a multiple of this number. Defaults to 0x1000. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --stack Va reserve +.It --stack Va reserve, Va commit +Specify the amount of memory to reserve (and optionally commit) to be used +as stack for this program. The default is 2Mb reserved, 4K committed. [This +option is specific to the i386 PE targeted port of the linker] +.Pp +.It --subsystem Va which +.It --subsystem Va which: Va major +.It --subsystem Va which: Va major. Va minor +Specifies the subsystem under which your program will execute. The legal values +for +.Va which +are +.Li native , +.Li windows , +.Li console , +.Li posix , +and +.Li xbox . +You may optionally set the subsystem version also. Numeric values are also +accepted for +.Va which . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.El +.Em Options specific to Motorola 68HC11 and 68HC12 targets +.Pp +The 68HC11 and 68HC12 linkers support specific options to control the memory +bank switching mapping and trampoline code generation. +.Pp +.Bl -tag -width Ds +.It --no-trampoline +This option disables the generation of trampoline. By default a trampoline +is generated for each far function which is called using a +.Li jsr +instruction (this happens when a pointer to a far function is taken). +.Pp +.It --bank-window Va name +This option indicates to the linker the name of the memory region in the +.Li MEMORY +specification that describes the memory bank window. The definition of such +region is then used by the linker to compute paging and addresses within the +memory window. +.Pp +.El +.Ss Environment Variables +You can change the behaviour of +.Xr ld +with the environment variables +.Li GNUTARGET , +.Li LDEMULATION +and +.Li COLLECT_NO_DEMANGLE . +.Pp +.Li GNUTARGET +determines the input-file object format if you don't use +.Li -b +(or its synonym +.Li --format ) . +Its value should be one of the BFD names for an input format (see Section +.Dq BFD ) . +If there is no +.Li GNUTARGET +in the environment, +.Xr ld +uses the natural format of the target. If +.Li GNUTARGET +is set to +.Li 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. +.Pp +.Li LDEMULATION +determines the default emulation if you don't use the +.Li -m +option. The emulation can affect various aspects of linker behaviour, particularly +the default linker script. You can list the available emulations with the +.Li --verbose +or +.Li -V +options. If the +.Li -m +option is not used, and the +.Li LDEMULATION +environment variable is not defined, the default emulation depends upon how +the linker was configured. +.Pp +Normally, the linker will default to demangling symbols. However, if +.Li COLLECT_NO_DEMANGLE +is set in the environment, then it will default to not demangling symbols. +This environment variable is used in a similar fashion by the +.Li gcc +linker wrapper program. The default may be overridden by the +.Li --demangle +and +.Li --no-demangle +options. +.Pp +.Sh Linker Scripts +Every link is controlled by a +.Em linker script . +This script is written in the linker command language. +.Pp +The main purpose of the linker script is to describe how the sections in the +input files should be mapped into the output file, and to control the memory +layout of the output file. Most linker scripts do nothing more than this. +However, when necessary, the linker script can also direct the linker to perform +many other operations, using the commands described below. +.Pp +The linker always uses a linker script. If you do not supply one yourself, +the linker will use a default script that is compiled into the linker executable. +You can use the +.Li --verbose +command line option to display the default linker script. Certain command +line options, such as +.Li -r +or +.Li -N , +will affect the default linker script. +.Pp +You may supply your own linker script by using the +.Li -T +command line option. When you do this, your linker script will replace the +default linker script. +.Pp +You may also use linker scripts implicitly by naming them as input files to +the linker, as though they were files to be linked.See Section +.Dq Implicit Linker Scripts . +.Pp +.Ss Basic Linker Script Concepts +We need to define some basic concepts and vocabulary in order to describe +the linker script language. +.Pp +The linker combines input files into a single output file. The output file +and each input file are in a special data format known as an +.Em object file format . +Each file is called an +.Em object file . +The output file is often called an +.Em executable , +but for our purposes we will also call it an object file. Each object file +has, among other things, a list of +.Em sections . +We sometimes refer to a section in an input file as an +.Em input section ; +similarly, a section in the output file is an +.Em output section . +.Pp +Each section in an object file has a name and a size. Most sections also have +an associated block of data, known as the +.Em section contents . +A section may be marked as +.Em loadable , +which mean that the contents should be loaded into memory when the output +file is run. A section with no contents may be +.Em allocatable , +which means that an area in memory should be set aside, but nothing in particular +should be loaded there (in some cases this memory must be zeroed out). A section +which is neither loadable nor allocatable typically contains some sort of +debugging information. +.Pp +Every loadable or allocatable output section has two addresses. The first +is the +.Em VMA , +or virtual memory address. This is the address the section will have when +the output file is run. The second is the +.Em LMA , +or load memory address. This is the address at which the section will be loaded. +In most cases the two addresses will be the same. An example of when they +might be different is when a data section is loaded into ROM, and then copied +into RAM when the program starts up (this technique is often used to initialize +global variables in a ROM based system). In this case the ROM address would +be the LMA, and the RAM address would be the VMA. +.Pp +You can see the sections in an object file by using the +.Li objdump +program with the +.Li -h +option. +.Pp +Every object file also has a list of +.Em symbols , +known as the +.Em symbol table . +A symbol may be defined or undefined. Each symbol has a name, and each defined +symbol has an address, among other information. If you compile a C or C++ +program into an object file, you will get a defined symbol for every defined +function and global or static variable. Every undefined function or global +variable which is referenced in the input file will become an undefined symbol. +.Pp +You can see the symbols in an object file by using the +.Li nm +program, or by using the +.Li objdump +program with the +.Li -t +option. +.Pp +.Ss Linker Script Format +Linker scripts are text files. +.Pp +You write a linker script as a series of commands. Each command is either +a keyword, possibly followed by arguments, or an assignment to a symbol. You +may separate commands using semicolons. Whitespace is generally ignored. +.Pp +Strings such as file or format names can normally be entered directly. If +the file name contains a character such as a comma which would otherwise serve +to separate file names, you may put the file name in double quotes. There +is no way to use a double quote character in a file name. +.Pp +You may include comments in linker scripts just as in C, delimited by +.Li /* +and +.Li */ . +As in C, comments are syntactically equivalent to whitespace. +.Pp +.Ss Simple Linker Script Example +Many linker scripts are fairly simple. +.Pp +The simplest possible linker script has just one command: +.Li SECTIONS . +You use the +.Li SECTIONS +command to describe the memory layout of the output file. +.Pp +The +.Li SECTIONS +command is a powerful command. Here we will describe a simple use of it. Let's +assume your program consists only of code, initialized data, and uninitialized +data. These will be in the +.Li .text , +.Li .data , +and +.Li .bss +sections, respectively. Let's assume further that these are the only sections +which appear in your input files. +.Pp +For this example, let's say that the code should be loaded at address 0x10000, +and that the data should start at address 0x8000000. Here is a linker script +which will do that: +.Bd -literal -offset indent +SECTIONS +{ + . = 0x10000; + .text : { *(.text) } + . = 0x8000000; + .data : { *(.data) } + .bss : { *(.bss) } +} +.Ed +.Pp +You write the +.Li SECTIONS +command as the keyword +.Li SECTIONS , +followed by a series of symbol assignments and output section descriptions +enclosed in curly braces. +.Pp +The first line inside the +.Li SECTIONS +command of the above example sets the value of the special symbol +.Li . , +which is the location counter. If you do not specify the address of an output +section in some other way (other ways are described later), the address is +set from the current value of the location counter. The location counter is +then incremented by the size of the output section. At the start of the +.Li SECTIONS +command, the location counter has the value +.Li 0 . +.Pp +The second line defines an output section, +.Li .text . +The colon is required syntax which may be ignored for now. Within the curly +braces after the output section name, you list the names of the input sections +which should be placed into this output section. The +.Li * +is a wildcard which matches any file name. The expression +.Li *(.text) +means all +.Li .text +input sections in all input files. +.Pp +Since the location counter is +.Li 0x10000 +when the output section +.Li .text +is defined, the linker will set the address of the +.Li .text +section in the output file to be +.Li 0x10000 . +.Pp +The remaining lines define the +.Li .data +and +.Li .bss +sections in the output file. The linker will place the +.Li .data +output section at address +.Li 0x8000000 . +After the linker places the +.Li .data +output section, the value of the location counter will be +.Li 0x8000000 +plus the size of the +.Li .data +output section. The effect is that the linker will place the +.Li .bss +output section immediately after the +.Li .data +output section in memory. +.Pp +The linker will ensure that each output section has the required alignment, +by increasing the location counter if necessary. In this example, the specified +addresses for the +.Li .text +and +.Li .data +sections will probably satisfy any alignment constraints, but the linker may +have to create a small gap between the +.Li .data +and +.Li .bss +sections. +.Pp +That's it! That's a simple and complete linker script. +.Pp +.Ss Simple Linker Script Commands +In this section we describe the simple linker script commands. +.Pp +.Em Setting the Entry Point +.Pp +The first instruction to execute in a program is called the +.Em entry point . +You can use the +.Li ENTRY +linker script command to set the entry point. The argument is a symbol name: +.Bd -literal -offset indent +ENTRY(symbol) +.Ed +.Pp +There are several ways to set the entry point. The linker will set the entry +point by trying each of the following methods in order, and stopping when +one of them succeeds: +.Bl -bullet +.It +the +.Li -e +.Va entry +command-line option; +.It +the +.Li ENTRY( Va symbol) +command in a linker script; +.It +the value of the symbol +.Li start , +if defined; +.It +the address of the first byte of the +.Li .text +section, if present; +.It +The address +.Li 0 . +.El +.Pp +.Em Commands Dealing with Files +.Pp +Several linker script commands deal with files. +.Pp +.Bl -tag -width Ds +.It INCLUDE Va filename +Include the linker script +.Va filename +at this point. The file will be searched for in the current directory, and +in any directory specified with the +.Op -L +option. You can nest calls to +.Li INCLUDE +up to 10 levels deep. +.Pp +.It INPUT( Va file, Va file, ...) +.It INPUT( Va file Va file ...) +The +.Li INPUT +command directs the linker to include the named files in the link, as though +they were named on the command line. +.Pp +For example, if you always want to include +.Pa subr.o +any time you do a link, but you can't be bothered to put it on every link +command line, then you can put +.Li INPUT (subr.o) +in your linker script. +.Pp +In fact, if you like, you can list all of your input files in the linker script, +and then invoke the linker with nothing but a +.Li -T +option. +.Pp +In case a +.Em sysroot prefix +is configured, and the filename starts with the +.Li / +character, and the script being processed was located inside the +.Em sysroot prefix , +the filename will be looked for in the +.Em sysroot prefix . +Otherwise, the linker will try to open the file in the current directory. +If it is not found, the linker will search through the archive library search +path. See the description of +.Li -L +in Options,,Command Line Options. +.Pp +If you use +.Li INPUT (-l Va file) , +.Xr ld +will transform the name to +.Li lib Va file.a , +as with the command line argument +.Li -l . +.Pp +When you use the +.Li INPUT +command in an implicit linker script, the files will be included in the link +at the point at which the linker script file is included. This can affect +archive searching. +.Pp +.It GROUP( Va file, Va file, ...) +.It GROUP( Va file Va file ...) +The +.Li GROUP +command is like +.Li INPUT , +except that the named files should all be archives, and they are searched +repeatedly until no new undefined references are created. See the description +of +.Li -( +in Options,,Command Line Options. +.Pp +.It AS_NEEDED( Va file, Va file, ...) +.It AS_NEEDED( Va file Va file ...) +This construct can appear only inside of the +.Li INPUT +or +.Li GROUP +commands, among other filenames. The files listed will be handled as if they +appear directly in the +.Li INPUT +or +.Li GROUP +commands, with the exception of ELF shared libraries, that will be added only +when they are actually needed. This construct essentially enables +.Op --as-needed +option for all the files listed inside of it and restores previous +.Op --as-needed +resp. +.Op --no-as-needed +setting afterwards. +.Pp +.It OUTPUT( Va filename) +The +.Li OUTPUT +command names the output file. Using +.Li OUTPUT( Va filename) +in the linker script is exactly like using +.Li -o Va filename +on the command line (see Section +.Dq Options ) . +If both are used, the command line option takes precedence. +.Pp +You can use the +.Li OUTPUT +command to define a default name for the output file other than the usual +default of +.Pa a.out . +.Pp +.It SEARCH_DIR( Va path) +The +.Li SEARCH_DIR +command adds +.Va path +to the list of paths where +.Xr ld +looks for archive libraries. Using +.Li SEARCH_DIR( Va path) +is exactly like using +.Li -L Va path +on the command line (see Section +.Dq Options ) . +If both are used, then the linker will search both paths. Paths specified +using the command line option are searched first. +.Pp +.It STARTUP( Va filename) +The +.Li STARTUP +command is just like the +.Li INPUT +command, except that +.Va filename +will become the first input file to be linked, as though it were specified +first on the command line. This may be useful when using a system in which +the entry point is always the start of the first file. +.El +.Pp +.Em Commands Dealing with Object File Formats +.Pp +A couple of linker script commands deal with object file formats. +.Pp +.Bl -tag -width Ds +.It OUTPUT_FORMAT( Va bfdname) +.It OUTPUT_FORMAT( Va default, Va big, Va little) +The +.Li OUTPUT_FORMAT +command names the BFD format to use for the output file (see Section +.Dq BFD ) . +Using +.Li OUTPUT_FORMAT( Va bfdname) +is exactly like using +.Li --oformat Va bfdname +on the command line (see Section +.Dq Options ) . +If both are used, the command line option takes precedence. +.Pp +You can use +.Li OUTPUT_FORMAT +with three arguments to use different formats based on the +.Li -EB +and +.Li -EL +command line options. This permits the linker script to set the output format +based on the desired endianness. +.Pp +If neither +.Li -EB +nor +.Li -EL +are used, then the output format will be the first argument, +.Va default . +If +.Li -EB +is used, the output format will be the second argument, +.Va big . +If +.Li -EL +is used, the output format will be the third argument, +.Va little . +.Pp +For example, the default linker script for the MIPS ELF target uses this command: +.Bd -literal -offset indent +OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) +.Ed +This says that the default format for the output file is +.Li elf32-bigmips , +but if the user uses the +.Li -EL +command line option, the output file will be created in the +.Li elf32-littlemips +format. +.Pp +.It TARGET( Va bfdname) +The +.Li TARGET +command names the BFD format to use when reading input files. It affects subsequent +.Li INPUT +and +.Li GROUP +commands. This command is like using +.Li -b Va bfdname +on the command line (see Section +.Dq Options ) . +If the +.Li TARGET +command is used but +.Li OUTPUT_FORMAT +is not, then the last +.Li TARGET +command is also used to set the format for the output file.See Section +.Dq BFD . +.El +.Pp +.Em Other Linker Script Commands +.Pp +There are a few other linker scripts commands. +.Pp +.Bl -tag -width Ds +.It ASSERT( Va exp, Va message) +Ensure that +.Va exp +is non-zero. If it is zero, then exit the linker with an error code, and print +.Va message . +.Pp +.It EXTERN( Va symbol Va symbol ...) +Force +.Va 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. You +may list several +.Va symbol +s for each +.Li EXTERN , +and you may use +.Li EXTERN +multiple times. This command has the same effect as the +.Li -u +command-line option. +.Pp +.It FORCE_COMMON_ALLOCATION +This command has the same effect as the +.Li -d +command-line option: to make +.Xr ld +assign space to common symbols even if a relocatable output file is specified +( +.Li -r ) . +.Pp +.It INHIBIT_COMMON_ALLOCATION +This command has the same effect as the +.Li --no-define-common +command-line option: to make +.Li ld +omit the assignment of addresses to common symbols even for a non-relocatable +output file. +.Pp +.It NOCROSSREFS( Va section Va section ...) +This command may be used to tell +.Xr ld +to issue an error about any references among certain output sections. +.Pp +In certain types of programs, particularly on embedded systems when using +overlays, when one section is loaded into memory, another section will not +be. Any direct references between the two sections would be errors. For example, +it would be an error if code in one section called a function defined in the +other section. +.Pp +The +.Li NOCROSSREFS +command takes a list of output section names. If +.Xr ld +detects any cross references between the sections, it reports an error and +returns a non-zero exit status. Note that the +.Li NOCROSSREFS +command uses output section names, not input section names. +.Pp +.It OUTPUT_ARCH( Va bfdarch) +Specify a particular output machine architecture. The argument is one of the +names used by the BFD library (see Section +.Dq BFD ) . +You can see the architecture of an object file by using the +.Li objdump +program with the +.Li -f +option. +.El +.Pp +.Ss Assigning Values to Symbols +You may assign a value to a symbol in a linker script. This will define the +symbol and place it into the symbol table with a global scope. +.Pp +.Em Simple Assignments +.Pp +You may assign to a symbol using any of the C assignment operators: +.Pp +.Bl -tag -width Ds +.It Va symbol = Va expression ; +.It Va symbol += Va expression ; +.It Va symbol -= Va expression ; +.It Va symbol *= Va expression ; +.It Va symbol /= Va expression ; +.It Va symbol <<= Va expression ; +.It Va symbol >>= Va expression ; +.It Va symbol &= Va expression ; +.It Va symbol |= Va expression ; +.El +.Pp +The first case will define +.Va symbol +to the value of +.Va expression . +In the other cases, +.Va symbol +must already be defined, and the value will be adjusted accordingly. +.Pp +The special symbol name +.Li . +indicates the location counter. You may only use this within a +.Li SECTIONS +command.See Section +.Dq Location Counter . +.Pp +The semicolon after +.Va expression +is required. +.Pp +Expressions are defined below; see Expressions. +.Pp +You may write symbol assignments as commands in their own right, or as statements +within a +.Li SECTIONS +command, or as part of an output section description in a +.Li SECTIONS +command. +.Pp +The section of the symbol will be set from the section of the expression; +for more information, see Expression Section. +.Pp +Here is an example showing the three different places that symbol assignments +may be used: +.Pp +.Bd -literal -offset indent +floating_point = 0; +SECTIONS +{ + .text : + { + *(.text) + _etext = .; + } + _bdata = (. + 3) & ~ 3; + .data : { *(.data) } +} +.Ed +In this example, the symbol +.Li floating_point +will be defined as zero. The symbol +.Li _etext +will be defined as the address following the last +.Li .text +input section. The symbol +.Li _bdata +will be defined as the address following the +.Li .text +output section aligned upward to a 4 byte boundary. +.Pp +.Em PROVIDE +.Pp +In some cases, it is desirable for a linker script to define a symbol only +if it is referenced and is not defined by any object included in the link. +For example, traditional linkers defined the symbol +.Li etext . +However, ANSI C requires that the user be able to use +.Li etext +as a function name without encountering an error. The +.Li PROVIDE +keyword may be used to define a symbol, such as +.Li etext , +only if it is referenced but not defined. The syntax is +.Li PROVIDE( Va symbol = Va expression) . +.Pp +Here is an example of using +.Li PROVIDE +to define +.Li etext : +.Bd -literal -offset indent +SECTIONS +{ + .text : + { + *(.text) + _etext = .; + PROVIDE(etext = .); + } +} +.Ed +.Pp +In this example, if the program defines +.Li _etext +(with a leading underscore), the linker will give a multiple definition error. +If, on the other hand, the program defines +.Li etext +(with no leading underscore), the linker will silently use the definition +in the program. If the program references +.Li etext +but does not define it, the linker will use the definition in the linker script. +.Pp +.Em PROVIDE_HIDDEN +.Pp +Similar to +.Li PROVIDE . +For ELF targeted ports, the symbol will be hidden and won't be exported. +.Pp +.Em Source Code Reference +.Pp +Accessing a linker script defined variable from source code is not intuitive. +In particular a linker script symbol is not equivalent to a variable declaration +in a high level language, it is instead a symbol that does not have a value. +.Pp +Before going further, it is important to note that compilers often transform +names in the source code into different names when they are stored in the +symbol table. For example, Fortran compilers commonly prepend or append an +underscore, and C++ performs extensive +.Li name mangling . +Therefore there might be a discrepancy between the name of a variable as it +is used in source code and the name of the same variable as it is defined +in a linker script. For example in C a linker script variable might be referred +to as: +.Pp +.Bd -literal -offset indent + extern int foo; +.Ed +.Pp +But in the linker script it might be defined as: +.Pp +.Bd -literal -offset indent + _foo = 1000; +.Ed +.Pp +In the remaining examples however it is assumed that no name transformation +has taken place. +.Pp +When a symbol is declared in a high level language such as C, two things happen. +The first is that the compiler reserves enough space in the program's memory +to hold the +.Em value +of the symbol. The second is that the compiler creates an entry in the program's +symbol table which holds the symbol's +.Em address . +ie the symbol table contains the address of the block of memory holding the +symbol's value. So for example the following C declaration, at file scope: +.Pp +.Bd -literal -offset indent + int foo = 1000; +.Ed +.Pp +creates a entry called +.Li foo +in the symbol table. This entry holds the address of an +.Li int +sized block of memory where the number 1000 is initially stored. +.Pp +When a program references a symbol the compiler generates code that first +accesses the symbol table to find the address of the symbol's memory block +and then code to read the value from that memory block. So: +.Pp +.Bd -literal -offset indent + foo = 1; +.Ed +.Pp +looks up the symbol +.Li foo +in the symbol table, gets the address associated with this symbol and then +writes the value 1 into that address. Whereas: +.Pp +.Bd -literal -offset indent + int * a = & foo; +.Ed +.Pp +looks up the symbol +.Li foo +in the symbol table, gets it address and then copies this address into the +block of memory associated with the variable +.Li a . +.Pp +Linker scripts symbol declarations, by contrast, create an entry in the symbol +table but do not assign any memory to them. Thus they are an address without +a value. So for example the linker script definition: +.Pp +.Bd -literal -offset indent + foo = 1000; +.Ed +.Pp +creates an entry in the symbol table called +.Li foo +which holds the address of memory location 1000, but nothing special is stored +at address 1000. This means that you cannot access the +.Em value +of a linker script defined symbol - it has no value - all you can do is access +the +.Em address +of a linker script defined symbol. +.Pp +Hence when you are using a linker script defined symbol in source code you +should always take the address of the symbol, and never attempt to use its +value. For example suppose you want to copy the contents of a section of memory +called .ROM into a section called .FLASH and the linker script contains these +declarations: +.Pp +.Bd -literal -offset indent + + start_of_ROM = .ROM; + end_of_ROM = .ROM + sizeof (.ROM) - 1; + start_of_FLASH = .FLASH; + +.Ed +.Pp +Then the C source code to perform the copy would be: +.Pp +.Bd -literal -offset indent + + extern char start_of_ROM, end_of_ROM, start_of_FLASH; + + memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); + +.Ed +.Pp +Note the use of the +.Li & +operators. These are correct. +.Pp +.Ss SECTIONS Command +The +.Li SECTIONS +command tells the linker how to map input sections into output sections, and +how to place the output sections in memory. +.Pp +The format of the +.Li SECTIONS +command is: +.Bd -literal -offset indent +SECTIONS +{ + sections-command + sections-command + ... +} +.Ed +.Pp +Each +.Va sections-command +may of be one of the following: +.Pp +.Bl -bullet +.It +an +.Li ENTRY +command (see Section +.Dq Entry Point ) +.It +a symbol assignment (see Section +.Dq Assignments ) +.It +an output section description +.It +an overlay description +.El +.Pp +The +.Li ENTRY +command and symbol assignments are permitted inside the +.Li SECTIONS +command for convenience in using the location counter in those commands. This +can also make the linker script easier to understand because you can use those +commands at meaningful points in the layout of the output file. +.Pp +Output section descriptions and overlay descriptions are described below. +.Pp +If you do not use a +.Li SECTIONS +command in your linker script, the linker will place 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. The first section will be at address zero. +.Pp +.Em Output Section Description +.Pp +The full description of an output section looks like this: +.Bd -literal -offset indent + +section [address] [(type)] : + [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] + { + output-section-command + output-section-command + ... + } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] + +.Ed +.Pp +Most output sections do not use most of the optional section attributes. +.Pp +The whitespace around +.Va section +is required, so that the section name is unambiguous. The colon and the curly +braces are also required. The line breaks and other white space are optional. +.Pp +Each +.Va output-section-command +may be one of the following: +.Pp +.Bl -bullet +.It +a symbol assignment (see Section +.Dq Assignments ) +.It +an input section description (see Section +.Dq Input Section ) +.It +data values to include directly (see Section +.Dq Output Section Data ) +.It +a special output section keyword (see Section +.Dq Output Section Keywords ) +.El +.Pp +.Em Output Section Name +.Pp +The name of the output section is +.Va section . +.Va section +must meet the constraints of your output format. In formats which only support +a limited number of sections, such as +.Li a.out , +the name must be one of the names supported by the format ( +.Li a.out , +for example, allows only +.Li .text , +.Li .data +or +.Li .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 a name which contains any unusual characters such as commas must be quoted. +.Pp +The output section name +.Li /DISCARD/ +is special; Output Section Discarding. +.Pp +.Em Output Section Address +.Pp +The +.Va address +is an expression for the VMA (the virtual memory address) of the output section. +If you do not provide +.Va address , +the linker will set it based on +.Va region +if present, or otherwise based on the current value of the location counter. +.Pp +If you provide +.Va address , +the address of the output section will be set to precisely that. If you provide +neither +.Va address +nor +.Va region , +then the address of the output section will be set to the current value of +the location counter aligned to the alignment requirements of the output section. +The alignment requirement of the output section is the strictest alignment +of any input section contained within the output section. +.Pp +For example, +.Bd -literal -offset indent +\&.text . : { *(.text) } +.Ed +and +.Bd -literal -offset indent +\&.text : { *(.text) } +.Ed +are subtly different. The first will set the address of the +.Li .text +output section to the current value of the location counter. The second will +set it to the current value of the location counter aligned to the strictest +alignment of a +.Li .text +input section. +.Pp +The +.Va address +may be an arbitrary expression; Expressions. For example, if you want to align +the section on a 0x10 byte boundary, so that the lowest four bits of the section +address are zero, you could do something like this: +.Bd -literal -offset indent +\&.text ALIGN(0x10) : { *(.text) } +.Ed +This works because +.Li ALIGN +returns the current location counter aligned upward to the specified value. +.Pp +Specifying +.Va address +for a section will change the value of the location counter. +.Pp +.Em Input Section Description +.Pp +The most common output section command is an input section description. +.Pp +The input section description is the most basic linker script operation. You +use output sections to tell the linker how to lay out your program in memory. +You use input section descriptions to tell the linker how to map the input +files into your memory layout. +.Pp +.No Input Section Basics +.Pp +An input section description consists of a file name optionally followed by +a list of section names in parentheses. +.Pp +The file name and the section name may be wildcard patterns, which we describe +further below (see Section +.Dq Input Section Wildcards ) . +.Pp +The most common input section description is to include all input sections +with a particular name in the output section. For example, to include all +input +.Li .text +sections, you would write: +.Bd -literal -offset indent +*(.text) +.Ed +Here the +.Li * +is a wildcard which matches any file name. To exclude a list of files from +matching the file name wildcard, EXCLUDE_FILE may be used to match all files +except the ones specified in the EXCLUDE_FILE list. For example: +.Bd -literal -offset indent +(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)) +.Ed +will cause all .ctors sections from all files except +.Pa crtend.o +and +.Pa otherfile.o +to be included. +.Pp +There are two ways to include more than one section: +.Bd -literal -offset indent +*(.text .rdata) +*(.text) *(.rdata) +.Ed +The difference between these is the order in which the +.Li .text +and +.Li .rdata +input sections will appear in the output section. In the first example, they +will be intermingled, appearing in the same order as they are found in the +linker input. In the second example, all +.Li .text +input sections will appear first, followed by all +.Li .rdata +input sections. +.Pp +You can specify a file name to include sections from a particular file. You +would do this if one or more of your files contain special data that needs +to be at a particular location in memory. For example: +.Bd -literal -offset indent +data.o(.data) +.Ed +.Pp +If you use a file name without a list of sections, then all sections in the +input file will be included in the output section. This is not commonly done, +but it may by useful on occasion. For example: +.Bd -literal -offset indent +data.o +.Ed +.Pp +When you use a file name which does not contain any wild card characters, +the linker will first see if you also specified the file name on the linker +command line or in an +.Li INPUT +command. If you did not, the linker will attempt to open the file as an input +file, as though it appeared on the command line. Note that this differs from +an +.Li INPUT +command, because the linker will not search for the file in the archive search +path. +.Pp +.No Input Section Wildcard Patterns +.Pp +In an input section description, either the file name or the section name +or both may be wildcard patterns. +.Pp +The file name of +.Li * +seen in many examples is a simple wildcard pattern for the file name. +.Pp +The wildcard patterns are like those used by the Unix shell. +.Pp +.Bl -tag -width Ds +.It * +matches any number of characters +.It ? +matches any single character +.It [ Va chars] +matches a single instance of any of the +.Va chars ; +the +.Li - +character may be used to specify a range of characters, as in +.Li [a-z] +to match any lower case letter +.It \e +quotes the following character +.El +.Pp +When a file name is matched with a wildcard, the wildcard characters will +not match a +.Li / +character (used to separate directory names on Unix). A pattern consisting +of a single +.Li * +character is an exception; it will always match any file name, whether it +contains a +.Li / +or not. In a section name, the wildcard characters will match a +.Li / +character. +.Pp +File name wildcard patterns only match files which are explicitly specified +on the command line or in an +.Li INPUT +command. The linker does not search directories to expand wildcards. +.Pp +If a file name matches more than one wildcard pattern, or if a file name appears +explicitly and is also matched by a wildcard pattern, the linker will use +the first match in the linker script. For example, this sequence of input +section descriptions is probably in error, because the +.Pa data.o +rule will not be used: +.Bd -literal -offset indent +\&.data : { *(.data) } +\&.data1 : { data.o(.data) } +.Ed +.Pp +Normally, the linker will place files and sections matched by wildcards in +the order in which they are seen during the link. You can change this by using +the +.Li SORT_BY_NAME +keyword, which appears before a wildcard pattern in parentheses (e.g., +.Li SORT_BY_NAME(.text*) ) . +When the +.Li SORT_BY_NAME +keyword is used, the linker will sort the files or sections into ascending +order by name before placing them in the output file. +.Pp +.Li SORT_BY_ALIGNMENT +is very similar to +.Li SORT_BY_NAME . +The difference is +.Li SORT_BY_ALIGNMENT +will sort sections into ascending order by alignment before placing them in +the output file. +.Pp +.Li SORT +is an alias for +.Li SORT_BY_NAME . +.Pp +When there are nested section sorting commands in linker script, there can +be at most 1 level of nesting for section sorting commands. +.Pp +.Bl -enum +.It +.Li SORT_BY_NAME +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)). It will sort the input sections by name first, +then by alignment if 2 sections have the same name. +.It +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_NAME +(wildcard section pattern)). It will sort the input sections by alignment +first, then by name if 2 sections have the same alignment. +.It +.Li SORT_BY_NAME +( +.Li SORT_BY_NAME +(wildcard section pattern)) is treated the same as +.Li SORT_BY_NAME +(wildcard section pattern). +.It +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)) is treated the same as +.Li SORT_BY_ALIGNMENT +(wildcard section pattern). +.It +All other nested section sorting commands are invalid. +.El +.Pp +When both command line section sorting option and linker script section sorting +command are used, section sorting command always takes precedence over the +command line option. +.Pp +If the section sorting command in linker script isn't nested, the command +line option will make the section sorting command to be treated as nested +sorting command. +.Pp +.Bl -enum +.It +.Li SORT_BY_NAME +(wildcard section pattern ) with +.Op --sort-sections alignment +is equivalent to +.Li SORT_BY_NAME +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)). +.It +.Li SORT_BY_ALIGNMENT +(wildcard section pattern) with +.Op --sort-section name +is equivalent to +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_NAME +(wildcard section pattern)). +.El +.Pp +If the section sorting command in linker script is nested, the command line +option will be ignored. +.Pp +If you ever get confused about where input sections are going, use the +.Li -M +linker option to generate a map file. The map file shows precisely how input +sections are mapped to output sections. +.Pp +This example shows how wildcard patterns might be used to partition files. +This linker script directs the linker to place all +.Li .text +sections in +.Li .text +and all +.Li .bss +sections in +.Li .bss . +The linker will place the +.Li .data +section from all files beginning with an upper case character in +.Li .DATA ; +for all other files, the linker will place the +.Li .data +section in +.Li .data . +.Bd -literal -offset indent + +SECTIONS { + .text : { *(.text) } + .DATA : { [A-Z]*(.data) } + .data : { *(.data) } + .bss : { *(.bss) } +} + +.Ed +.Pp +.No Input Section for Common Symbols +.Pp +A special notation is needed for common symbols, because in many object file +formats common symbols do not have a particular input section. The linker +treats common symbols as though they are in an input section named +.Li COMMON . +.Pp +You may use file names with the +.Li COMMON +section just as with any other input sections. You can use this to place common +symbols from a particular input file in one section while common symbols from +other input files are placed in another section. +.Pp +In most cases, common symbols in input files will be placed in the +.Li .bss +section in the output file. For example: +.Bd -literal -offset indent +\&.bss { *(.bss) *(COMMON) } +.Ed +.Pp +Some object file formats have more than one type of common symbol. For example, +the MIPS ELF object file format distinguishes standard common symbols and +small common symbols. In this case, the linker will use a different special +section name for other types of common symbols. In the case of MIPS ELF, the +linker uses +.Li COMMON +for standard common symbols and +.Li .scommon +for small common symbols. This permits you to map the different types of common +symbols into memory at different locations. +.Pp +You will sometimes see +.Li [COMMON] +in old linker scripts. This notation is now considered obsolete. It is equivalent +to +.Li *(COMMON) . +.Pp +.No Input Section and Garbage Collection +.Pp +When link-time garbage collection is in use ( +.Li --gc-sections ) , +it is often useful to mark sections that should not be eliminated. This is +accomplished by surrounding an input section's wildcard entry with +.Li KEEP() , +as in +.Li KEEP(*(.init)) +or +.Li KEEP(SORT_BY_NAME(*)(.ctors)) . +.Pp +.No Input Section Example +.Pp +The following example is a complete linker script. It tells the linker to +read all of the sections from file +.Pa all.o +and place them at the start of output section +.Li outputa +which starts at location +.Li 0x10000 . +All of section +.Li .input1 +from file +.Pa foo.o +follows immediately, in the same output section. All of section +.Li .input2 +from +.Pa foo.o +goes into output section +.Li outputb , +followed by section +.Li .input1 +from +.Pa foo1.o . +All of the remaining +.Li .input1 +and +.Li .input2 +sections from any files are written to output section +.Li outputc . +.Pp +.Bd -literal -offset indent + +SECTIONS { + outputa 0x10000 : + { + all.o + foo.o (.input1) + } + + + outputb : + { + foo.o (.input2) + foo1.o (.input1) + } + + + outputc : + { + *(.input1) + *(.input2) + } +} + +.Ed +.Pp +.Em Output Section Data +.Pp +You can include explicit bytes of data in an output section by using +.Li BYTE , +.Li SHORT , +.Li LONG , +.Li QUAD , +or +.Li SQUAD +as an output section command. Each keyword is followed by an expression in +parentheses providing the value to store (see Section +.Dq Expressions ) . +The value of the expression is stored at the current value of the location +counter. +.Pp +The +.Li BYTE , +.Li SHORT , +.Li LONG , +and +.Li QUAD +commands store one, two, four, and eight bytes (respectively). After storing +the bytes, the location counter is incremented by the number of bytes stored. +.Pp +For example, this will store the byte 1 followed by the four byte value of +the symbol +.Li addr : +.Bd -literal -offset indent +BYTE(1) +LONG(addr) +.Ed +.Pp +When using a 64 bit host or target, +.Li QUAD +and +.Li SQUAD +are the same; they both store an 8 byte, or 64 bit, value. When both host +and target are 32 bits, an expression is computed as 32 bits. In this case +.Li QUAD +stores a 32 bit value zero extended to 64 bits, and +.Li SQUAD +stores a 32 bit value sign extended to 64 bits. +.Pp +If the object file format of the output file has an explicit endianness, which +is the normal case, the value will be stored in that endianness. When the +object file format does not have an explicit endianness, as is true of, for +example, S-records, the value will be stored in the endianness of the first +input object file. +.Pp +Note---these commands only work inside a section description and not between +them, so the following will produce an error from the linker: +.Bd -literal -offset indent +SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } +.Ed +whereas this will work: +.Bd -literal -offset indent +SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } +.Ed +.Pp +You may use the +.Li FILL +command to set the fill pattern for the current section. It is followed by +an expression in parentheses. Any otherwise unspecified regions of memory +within the section (for example, gaps left due to the required alignment of +input sections) are filled with the value of the expression, repeated as necessary. +A +.Li FILL +statement covers memory locations after the point at which it occurs in the +section definition; by including more than one +.Li FILL +statement, you can have different fill patterns in different parts of an output +section. +.Pp +This example shows how to fill unspecified regions of memory with the value +.Li 0x90 : +.Bd -literal -offset indent +FILL(0x90909090) +.Ed +.Pp +The +.Li FILL +command is similar to the +.Li = Va fillexp +output section attribute, but it only affects the part of the section following +the +.Li FILL +command, rather than the entire section. If both are used, the +.Li FILL +command takes precedence.See Section +.Dq Output Section Fill , +for details on the fill expression. +.Pp +.Em Output Section Keywords +.Pp +There are a couple of keywords which can appear as output section commands. +.Pp +.Bl -tag -width Ds +.It CREATE_OBJECT_SYMBOLS +The command tells the linker to create a symbol for each input file. The name +of each symbol will be the name of the corresponding input file. The section +of each symbol will be the output section in which the +.Li CREATE_OBJECT_SYMBOLS +command appears. +.Pp +This is conventional for the a.out object file format. It is not normally +used for any other object file format. +.Pp +.It CONSTRUCTORS +When linking using the a.out object file format, the linker uses an unusual +set construct to support C++ global constructors and destructors. When linking +object file formats which do not support arbitrary sections, such as ECOFF +and XCOFF, the linker will automatically recognize C++ global constructors +and destructors by name. For these object file formats, the +.Li CONSTRUCTORS +command tells the linker to place constructor information in the output section +where the +.Li CONSTRUCTORS +command appears. The +.Li CONSTRUCTORS +command is ignored for other object file formats. +.Pp +The symbol +.Li __CTOR_LIST__ +marks the start of the global constructors, and the symbol +.Li __CTOR_END__ +marks the end. Similarly, +.Li __DTOR_LIST__ +and +.Li __DTOR_END__ +mark the start and end of the global destructors. The first word in the list +is the number of entries, followed by the address of each constructor or destructor, +followed by a zero word. The compiler must arrange to actually run the code. +For these object file formats GNU C++ normally calls constructors from a subroutine +.Li __main ; +a call to +.Li __main +is automatically inserted into the startup code for +.Li main . +GNU C++ normally runs destructors either by using +.Li atexit , +or directly from the function +.Li exit . +.Pp +For object file formats such as +.Li COFF +or +.Li ELF +which support arbitrary section names, GNU C++ will normally arrange to put +the addresses of global constructors and destructors into the +.Li .ctors +and +.Li .dtors +sections. Placing the following sequence into your linker script will build +the sort of table which the GNU C++ runtime code expects to see. +.Pp +.Bd -literal -offset indent + __CTOR_LIST__ = .; + LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) + *(.ctors) + LONG(0) + __CTOR_END__ = .; + __DTOR_LIST__ = .; + LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) + *(.dtors) + LONG(0) + __DTOR_END__ = .; +.Ed +.Pp +If you are using the GNU C++ support for initialization priority, which provides +some control over the order in which global constructors are run, you must +sort the constructors at link time to ensure that they are executed in the +correct order. When using the +.Li CONSTRUCTORS +command, use +.Li SORT_BY_NAME(CONSTRUCTORS) +instead. When using the +.Li .ctors +and +.Li .dtors +sections, use +.Li *(SORT_BY_NAME(.ctors)) +and +.Li *(SORT_BY_NAME(.dtors)) +instead of just +.Li *(.ctors) +and +.Li *(.dtors) . +.Pp +Normally the compiler and linker will handle these issues automatically, and +you will not need to concern yourself with them. However, you may need to +consider this if you are using C++ and writing your own linker scripts. +.Pp +.El +.Em Output Section Discarding +.Pp +The linker will not create output sections with no contents. This is for convenience +when referring to input sections that may or may not be present in any of +the input files. For example: +.Bd -literal -offset indent +\&.foo : { *(.foo) } +.Ed +will only create a +.Li .foo +section in the output file if there is a +.Li .foo +section in at least one input file, and if the input sections are not all +empty. Other link script directives that allocate space in an output section +will also create the output section. +.Pp +The linker will ignore address assignments (see Section +.Dq Output Section Address ) +on discarded output sections, except when the linker script defines symbols +in the output section. In that case the linker will obey the address assignments, +possibly advancing dot even though the section is discarded. +.Pp +The special output section name +.Li /DISCARD/ +may be used to discard input sections. Any input sections which are assigned +to an output section named +.Li /DISCARD/ +are not included in the output file. +.Pp +.Em Output Section Attributes +.Pp +We showed above that the full description of an output section looked like +this: +.Bd -literal -offset indent + +section [address] [(type)] : + [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] + { + output-section-command + output-section-command + ... + } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] + +.Ed +We've already described +.Va section , +.Va address , +and +.Va output-section-command . +In this section we will describe the remaining section attributes. +.Pp +.No Output Section Type +.Pp +Each output section may have a type. The type is a keyword in parentheses. +The following types are defined: +.Pp +.Bl -tag -width Ds +.It NOLOAD +The section should be marked as not loadable, so that it will not be loaded +into memory when the program is run. +.It DSECT +.It COPY +.It INFO +.It OVERLAY +These type names are supported for backward compatibility, and are rarely +used. They all have the same effect: the section should be marked as not allocatable, +so that no memory is allocated for the section when the program is run. +.El +.Pp +The linker normally sets the attributes of an output section based on the +input sections which map into it. You can override this by using the section +type. For example, in the script sample below, the +.Li ROM +section is addressed at memory location +.Li 0 +and does not need to be loaded when the program is run. The contents of the +.Li ROM +section will appear in the linker output file as usual. +.Bd -literal -offset indent + +SECTIONS { + ROM 0 (NOLOAD) : { ... } + ... +} + +.Ed +.Pp +.No Output Section LMA +.Pp +Every section has a virtual address (VMA) and a load address (LMA); see Basic +Script Concepts. The address expression which may appear in an output section +description sets the VMA (see Section +.Dq Output Section Address ) . +.Pp +The expression +.Va lma +that follows the +.Li AT +keyword specifies the load address of the section. +.Pp +Alternatively, with +.Li AT> Va lma_region +expression, you may specify a memory region for the section's load address.See Section +.Dq MEMORY . +Note that if the section has not had a VMA assigned to it then the linker +will use the +.Va lma_region +as the VMA region as well. +.Pp +If neither +.Li AT +nor +.Li AT> +is specified for an allocatable section, the linker will set the LMA such +that the difference between VMA and LMA for the section is the same as the +preceding output section in the same region. If there is no preceding output +section or the section is not allocatable, the linker will set the LMA equal +to the VMA.See Section +.Dq Output Section Region . +.Pp +This feature is designed to make it easy to build a ROM image. For example, +the following linker script creates three output sections: one called +.Li .text , +which starts at +.Li 0x1000 , +one called +.Li .mdata , +which is loaded at the end of the +.Li .text +section even though its VMA is +.Li 0x2000 , +and one called +.Li .bss +to hold uninitialized data at address +.Li 0x3000 . +The symbol +.Li _data +is defined with the value +.Li 0x2000 , +which shows that the location counter holds the VMA value, not the LMA value. +.Pp +.Bd -literal -offset indent + +SECTIONS + { + .text 0x1000 : { *(.text) _etext = . ; } + .mdata 0x2000 : + AT ( ADDR (.text) + SIZEOF (.text) ) + { _data = . ; *(.data); _edata = . ; } + .bss 0x3000 : + { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} +} + +.Ed +.Pp +The run-time initialization code for use with a program generated with this +linker script would include something like the following, to copy the initialized +data from the ROM image to its runtime address. Notice how this code takes +advantage of the symbols defined by the linker script. +.Pp +.Bd -literal -offset indent + +extern char _etext, _data, _edata, _bstart, _bend; +char *src = &_etext; +char *dst = &_data; + +/* ROM has data at end of text; copy it. */ +while (dst < &_edata) { + *dst++ = *src++; +} + +/* Zero bss */ +for (dst = &_bstart; dst< &_bend; dst++) + *dst = 0; + +.Ed +.Pp +.No Forced Output Alignment +.Pp +You can increase an output section's alignment by using ALIGN. +.Pp +.No Forced Input Alignment +.Pp +You can force input section alignment within an output section by using SUBALIGN. +The value specified overrides any alignment given by input sections, whether +larger or smaller. +.Pp +.No Output Section Region +.Pp +You can assign a section to a previously defined region of memory by using +.Li > Va region . +See Section.Dq MEMORY . +.Pp +Here is a simple example: +.Bd -literal -offset indent + +MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } +SECTIONS { ROM : { *(.text) } >rom } + +.Ed +.Pp +.No Output Section Phdr +.Pp +You can assign a section to a previously defined program segment by using +.Li : Va phdr . +See Section.Dq PHDRS . +If a section is assigned to one or more segments, then all subsequent allocated +sections will be assigned to those segments as well, unless they use an explicitly +.Li : Va phdr +modifier. You can use +.Li :NONE +to tell the linker to not put the section in any segment at all. +.Pp +Here is a simple example: +.Bd -literal -offset indent + +PHDRS { text PT_LOAD ; } +SECTIONS { .text : { *(.text) } :text } + +.Ed +.Pp +.No Output Section Fill +.Pp +You can set the fill pattern for an entire section by using +.Li = Va fillexp . +.Va fillexp +is an expression (see Section +.Dq Expressions ) . +Any otherwise unspecified regions of memory within the output section (for +example, gaps left due to the required alignment of input sections) will be +filled with the value, repeated as necessary. If the fill expression is a +simple hex number, ie. a string of hex digit starting with +.Li 0x +and without a trailing +.Li k +or +.Li M , +then an arbitrarily long sequence of hex digits can be used to specify the +fill pattern; Leading zeros become part of the pattern too. For all other +cases, including extra parentheses or a unary +.Li + , +the fill pattern is the four least significant bytes of the value of the expression. +In all cases, the number is big-endian. +.Pp +You can also change the fill value with a +.Li FILL +command in the output section commands; (see Section +.Dq Output Section Data ) . +.Pp +Here is a simple example: +.Bd -literal -offset indent + +SECTIONS { .text : { *(.text) } =0x90909090 } + +.Ed +.Pp +.Em Overlay Description +.Pp +An overlay description provides an easy way to describe sections which are +to be loaded as part of a single memory image but are to be run at the same +memory address. At run time, some sort of overlay manager will copy the overlaid +sections in and out of the runtime memory address as required, perhaps by +simply manipulating addressing bits. This approach can be useful, for example, +when a certain region of memory is faster than another. +.Pp +Overlays are described using the +.Li OVERLAY +command. The +.Li OVERLAY +command is used within a +.Li SECTIONS +command, like an output section description. The full syntax of the +.Li OVERLAY +command is as follows: +.Bd -literal -offset indent + +OVERLAY [start] : [NOCROSSREFS] [AT ( ldaddr )] + { + secname1 + { + output-section-command + output-section-command + ... + } [:phdr...] [=fill] + secname2 + { + output-section-command + output-section-command + ... + } [:phdr...] [=fill] + ... + } [>region] [:phdr...] [=fill] + +.Ed +.Pp +Everything is optional except +.Li OVERLAY +(a keyword), and each section must have a name ( +.Va secname1 +and +.Va secname2 +above). The section definitions within the +.Li OVERLAY +construct are identical to those within the general +.Li SECTIONS +contruct (see Section +.Dq SECTIONS ) , +except that no addresses and no memory regions may be defined for sections +within an +.Li OVERLAY . +.Pp +The sections are all defined with the same starting address. The load addresses +of the sections are arranged such that they are consecutive in memory starting +at the load address used for the +.Li OVERLAY +as a whole (as with normal section definitions, the load address is optional, +and defaults to the start address; the start address is also optional, and +defaults to the current value of the location counter). +.Pp +If the +.Li NOCROSSREFS +keyword is used, and there any references among the sections, the linker will +report an error. Since the sections all run at the same address, it normally +does not make sense for one section to refer directly to another.See Section +.Dq Miscellaneous Commands . +.Pp +For each section within the +.Li OVERLAY , +the linker automatically provides two symbols. The symbol +.Li __load_start_ Va secname +is defined as the starting load address of the section. The symbol +.Li __load_stop_ Va secname +is defined as the final load address of the section. Any characters within +.Va secname +which are not legal within C identifiers are removed. C (or assembler) code +may use these symbols to move the overlaid sections around as necessary. +.Pp +At the end of the overlay, the value of the location counter is set to the +start address of the overlay plus the size of the largest section. +.Pp +Here is an example. Remember that this would appear inside a +.Li SECTIONS +construct. +.Bd -literal -offset indent + + OVERLAY 0x1000 : AT (0x4000) + { + .text0 { o1/*.o(.text) } + .text1 { o2/*.o(.text) } + } + +.Ed +This will define both +.Li .text0 +and +.Li .text1 +to start at address 0x1000. +.Li .text0 +will be loaded at address 0x4000, and +.Li .text1 +will be loaded immediately after +.Li .text0 . +The following symbols will be defined if referenced: +.Li __load_start_text0 , +.Li __load_stop_text0 , +.Li __load_start_text1 , +.Li __load_stop_text1 . +.Pp +C code to copy overlay +.Li .text1 +into the overlay area might look like the following. +.Pp +.Bd -literal -offset indent + + extern char __load_start_text1, __load_stop_text1; + memcpy ((char *) 0x1000, &__load_start_text1, + &__load_stop_text1 - &__load_start_text1); + +.Ed +.Pp +Note that the +.Li OVERLAY +command is just syntactic sugar, since everything it does can be done using +the more basic commands. The above example could have been written identically +as follows. +.Pp +.Bd -literal -offset indent + + .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } + PROVIDE (__load_start_text0 = LOADADDR (.text0)); + PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); + .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } + PROVIDE (__load_start_text1 = LOADADDR (.text1)); + PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); + . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); + +.Ed +.Pp +.Ss MEMORY Command +The linker's default configuration permits allocation of all available memory. +You can override this by using the +.Li MEMORY +command. +.Pp +The +.Li MEMORY +command describes the location and size of blocks of memory in the target. +You can use it to describe which memory regions may be used by the linker, +and which memory regions it must avoid. You can then assign sections to particular +memory regions. The linker will set section addresses based on the memory +regions, and will warn about regions that become too full. The linker will +not shuffle sections around to fit into the available regions. +.Pp +A linker script may contain at most one use of the +.Li MEMORY +command. However, you can define as many blocks of memory within it as you +wish. The syntax is: +.Bd -literal -offset indent + +MEMORY + { + name [(attr)] : ORIGIN = origin, LENGTH = len + ... + } + +.Ed +.Pp +The +.Va name +is a name used in the linker script to refer to the region. The region name +has no meaning outside of the linker script. Region names are stored in a +separate name space, and will not conflict with symbol names, file names, +or section names. Each memory region must have a distinct name. +.Pp +The +.Va attr +string is an optional list of attributes that specify whether to use a particular +memory region for an input section which is not explicitly mapped in the linker +script. As described in SECTIONS, if you do not specify an output section +for some input section, the linker will create an output section with the +same name as the input section. If you define region attributes, the linker +will use them to select the memory region for the output section that it creates. +.Pp +The +.Va attr +string must consist only of the following characters: +.Bl -tag -width Ds +.It R +Read-only section +.It W +Read/write section +.It X +Executable section +.It A +Allocatable section +.It I +Initialized section +.It L +Same as +.Li I +.It ! +Invert the sense of any of the preceding attributes +.El +.Pp +If a unmapped section matches any of the listed attributes other than +.Li ! , +it will be placed in the memory region. The +.Li ! +attribute reverses this test, so that an unmapped section will be placed in +the memory region only if it does not match any of the listed attributes. +.Pp +The +.Va origin +is an numerical expression for the start address of the memory region. The +expression must evaluate to a constant and it cannot involve any symbols. +The keyword +.Li ORIGIN +may be abbreviated to +.Li org +or +.Li o +(but not, for example, +.Li ORG ) . +.Pp +The +.Va len +is an expression for the size in bytes of the memory region. As with the +.Va origin +expression, the expression must be numerical only and must evaluate to a constant. +The keyword +.Li LENGTH +may be abbreviated to +.Li len +or +.Li l . +.Pp +In the following example, we specify that there are two memory regions available +for allocation: one starting at +.Li 0 +for 256 kilobytes, and the other starting at +.Li 0x40000000 +for four megabytes. The linker will place into the +.Li rom +memory region every section which is not explicitly mapped into a memory region, +and is either read-only or executable. The linker will place other sections +which are not explicitly mapped into a memory region into the +.Li ram +memory region. +.Pp +.Bd -literal -offset indent + +MEMORY + { + rom (rx) : ORIGIN = 0, LENGTH = 256K + ram (!rx) : org = 0x40000000, l = 4M + } + +.Ed +.Pp +Once you define a memory region, you can direct the linker to place specific +output sections into that memory region by using the +.Li > Va region +output section attribute. For example, if you have a memory region named +.Li mem , +you would use +.Li >mem +in the output section definition.See Section +.Dq Output Section Region . +If no address was specified for the output section, the linker will set the +address to the next available address within the memory region. If the combined +output sections directed to a memory region are too large for the region, +the linker will issue an error message. +.Pp +It is possible to access the origin and length of a memory in an expression +via the +.Li ORIGIN( Va memory) +and +.Li LENGTH( Va memory) +functions: +.Pp +.Bd -literal -offset indent + + _fstack = ORIGIN(ram) + LENGTH(ram) - 4; + +.Ed +.Pp +.Ss PHDRS Command +The ELF object file format uses +.Em program headers , +also knows as +.Em segments . +The program headers describe how the program should be loaded into memory. +You can print them out by using the +.Li objdump +program with the +.Li -p +option. +.Pp +When you run an ELF program on a native ELF system, the system loader reads +the program headers in order to figure out how to load the program. This will +only work if the program headers are set correctly. This manual does not describe +the details of how the system loader interprets program headers; for more +information, see the ELF ABI. +.Pp +The linker will create reasonable program headers by default. However, in +some cases, you may need to specify the program headers more precisely. You +may use the +.Li PHDRS +command for this purpose. When the linker sees the +.Li PHDRS +command in the linker script, it will not create any program headers other +than the ones specified. +.Pp +The linker only pays attention to the +.Li PHDRS +command when generating an ELF output file. In other cases, the linker will +simply ignore +.Li PHDRS . +.Pp +This is the syntax of the +.Li PHDRS +command. The words +.Li PHDRS , +.Li FILEHDR , +.Li AT , +and +.Li FLAGS +are keywords. +.Pp +.Bd -literal -offset indent + +PHDRS +{ + name type [ FILEHDR ] [ PHDRS ] [ AT ( address ) ] + [ FLAGS ( flags ) ] ; +} + +.Ed +.Pp +The +.Va name +is used only for reference in the +.Li SECTIONS +command of the linker script. It is not put into the output file. Program +header names are stored in a separate name space, and will not conflict with +symbol names, file names, or section names. Each program header must have +a distinct name. +.Pp +Certain program header types describe segments of memory which the system +loader will load from the file. In the linker script, you specify the contents +of these segments by placing allocatable output sections in the segments. +You use the +.Li : Va phdr +output section attribute to place a section in a particular segment.See Section +.Dq Output Section Phdr . +.Pp +It is normal to put certain sections in more than one segment. This merely +implies that one segment of memory contains another. You may repeat +.Li : Va phdr , +using it once for each segment which should contain the section. +.Pp +If you place a section in one or more segments using +.Li : Va phdr , +then the linker will place all subsequent allocatable sections which do not +specify +.Li : Va phdr +in the same segments. This is for convenience, since generally a whole set +of contiguous sections will be placed in a single segment. You can use +.Li :NONE +to override the default segment and tell the linker to not put the section +in any segment at all. +.Pp +You may use the +.Li FILEHDR +and +.Li PHDRS +keywords appear after the program header type to further describe the contents +of the segment. The +.Li FILEHDR +keyword means that the segment should include the ELF file header. The +.Li PHDRS +keyword means that the segment should include the ELF program headers themselves. +.Pp +The +.Va type +may be one of the following. The numbers indicate the value of the keyword. +.Pp +.Bl -tag -width Ds +.It Li PT_NULL (0) +Indicates an unused program header. +.Pp +.It Li PT_LOAD (1) +Indicates that this program header describes a segment to be loaded from the +file. +.Pp +.It Li PT_DYNAMIC (2) +Indicates a segment where dynamic linking information can be found. +.Pp +.It Li PT_INTERP (3) +Indicates a segment where the name of the program interpreter may be found. +.Pp +.It Li PT_NOTE (4) +Indicates a segment holding note information. +.Pp +.It Li PT_SHLIB (5) +A reserved program header type, defined but not specified by the ELF ABI. +.Pp +.It Li PT_PHDR (6) +Indicates a segment where the program headers may be found. +.Pp +.It Va expression +An expression giving the numeric type of the program header. This may be used +for types not defined above. +.El +.Pp +You can specify that a segment should be loaded at a particular address in +memory by using an +.Li AT +expression. This is identical to the +.Li AT +command used as an output section attribute (see Section +.Dq Output Section LMA ) . +The +.Li AT +command for a program header overrides the output section attribute. +.Pp +The linker will normally set the segment flags based on the sections which +comprise the segment. You may use the +.Li FLAGS +keyword to explicitly specify the segment flags. The value of +.Va flags +must be an integer. It is used to set the +.Li p_flags +field of the program header. +.Pp +Here is an example of +.Li PHDRS . +This shows a typical set of program headers used on a native ELF system. +.Pp +.Bd -literal -offset indent + +PHDRS +{ + headers PT_PHDR PHDRS ; + interp PT_INTERP ; + text PT_LOAD FILEHDR PHDRS ; + data PT_LOAD ; + dynamic PT_DYNAMIC ; +} + +SECTIONS +{ + . = SIZEOF_HEADERS; + .interp : { *(.interp) } :text :interp + .text : { *(.text) } :text + .rodata : { *(.rodata) } /* defaults to :text */ + ... + . = . + 0x1000; /* move to a new page in memory */ + .data : { *(.data) } :data + .dynamic : { *(.dynamic) } :data :dynamic + ... +} + +.Ed +.Pp +.Ss VERSION Command +The linker supports symbol versions when using ELF. Symbol versions are only +useful when using shared libraries. The dynamic linker can use symbol versions +to select a specific version of a function when it runs a program that may +have been linked against an earlier version of the shared library. +.Pp +You can include a version script directly in the main linker script, or you +can supply the version script as an implicit linker script. You can also use +the +.Li --version-script +linker option. +.Pp +The syntax of the +.Li VERSION +command is simply +.Bd -literal -offset indent +VERSION { version-script-commands } +.Ed +.Pp +The format of the version script commands is identical to that used by Sun's +linker in Solaris 2.5. The version script defines a tree of version nodes. +You specify the node names and interdependencies in the version script. You +can specify which symbols are bound to which version nodes, and you can reduce +a specified set of symbols to local scope so that they are not globally visible +outside of the shared library. +.Pp +The easiest way to demonstrate the version script language is with a few examples. +.Pp +.Bd -literal -offset indent +VERS_1.1 { + global: + foo1; + local: + old*; + original*; + new*; +}; + +VERS_1.2 { + foo2; +} VERS_1.1; + +VERS_2.0 { + bar1; bar2; + extern "C++" { + ns::*; + "int f(int, double)"; + } +} VERS_1.2; +.Ed +.Pp +This example version script defines three version nodes. The first version +node defined is +.Li VERS_1.1 ; +it has no other dependencies. The script binds the symbol +.Li foo1 +to +.Li VERS_1.1 . +It reduces a number of symbols to local scope so that they are not visible +outside of the shared library; this is done using wildcard patterns, so that +any symbol whose name begins with +.Li old , +.Li original , +or +.Li new +is matched. The wildcard patterns available are the same as those used in +the shell when matching filenames (also known as \(lqglobbing\(rq). However, if you +specify the symbol name inside double quotes, then the name is treated as +literal, rather than as a glob pattern. +.Pp +Next, the version script defines node +.Li VERS_1.2 . +This node depends upon +.Li VERS_1.1 . +The script binds the symbol +.Li foo2 +to the version node +.Li VERS_1.2 . +.Pp +Finally, the version script defines node +.Li VERS_2.0 . +This node depends upon +.Li VERS_1.2 . +The scripts binds the symbols +.Li bar1 +and +.Li bar2 +are bound to the version node +.Li VERS_2.0 . +.Pp +When the linker finds a symbol defined in a library which is not specifically +bound to a version node, it will effectively bind it to an unspecified base +version of the library. You can bind all otherwise unspecified symbols to +a given version node by using +.Li global: *; +somewhere in the version script. +.Pp +The names of the version nodes have no specific meaning other than what they +might suggest to the person reading them. The +.Li 2.0 +version could just as well have appeared in between +.Li 1.1 +and +.Li 1.2 . +However, this would be a confusing way to write a version script. +.Pp +Node name can be omitted, provided it is the only version node in the version +script. Such version script doesn't assign any versions to symbols, only selects +which symbols will be globally visible out and which won't. +.Pp +.Bd -literal -offset indent +{ global: foo; bar; local: *; }; +.Ed +.Pp +When you link an application against a shared library that has versioned symbols, +the application itself knows which version of each symbol it requires, and +it also knows which version nodes it needs from each shared library it is +linked against. Thus at runtime, the dynamic loader can make a quick check +to make sure that the libraries you have linked against do in fact supply +all of the version nodes that the application will need to resolve all of +the dynamic symbols. In this way it is possible for the dynamic linker to +know with certainty that all external symbols that it needs will be resolvable +without having to search for each symbol reference. +.Pp +The symbol versioning is in effect a much more sophisticated way of doing +minor version checking that SunOS does. The fundamental problem that is being +addressed here is that typically references to external functions are bound +on an as-needed basis, and are not all bound when the application starts up. +If a shared library is out of date, a required interface may be missing; when +the application tries to use that interface, it may suddenly and unexpectedly +fail. With symbol versioning, the user will get a warning when they start +their program if the libraries being used with the application are too old. +.Pp +There are several GNU extensions to Sun's versioning approach. The first of +these is the ability to bind a symbol to a version node in the source file +where the symbol is defined instead of in the versioning script. This was +done mainly to reduce the burden on the library maintainer. You can do this +by putting something like: +.Bd -literal -offset indent +__asm__(".symver original_foo,foo@VERS_1.1"); +.Ed +in the C source file. This renames the function +.Li original_foo +to be an alias for +.Li foo +bound to the version node +.Li VERS_1.1 . +The +.Li local: +directive can be used to prevent the symbol +.Li original_foo +from being exported. A +.Li .symver +directive takes precedence over a version script. +.Pp +The second GNU extension is to allow multiple versions of the same function +to appear in a given shared library. In this way you can make an incompatible +change to an interface without increasing the major version number of the +shared library, while still allowing applications linked against the old interface +to continue to function. +.Pp +To do this, you must use multiple +.Li .symver +directives in the source file. Here is an example: +.Pp +.Bd -literal -offset indent +__asm__(".symver original_foo,foo@"); +__asm__(".symver old_foo,foo@VERS_1.1"); +__asm__(".symver old_foo1,foo@VERS_1.2"); +__asm__(".symver new_foo,foo@@VERS_2.0"); +.Ed +.Pp +In this example, +.Li foo@ +represents the symbol +.Li foo +bound to the unspecified base version of the symbol. The source file that +contains this example would define 4 C functions: +.Li original_foo , +.Li old_foo , +.Li old_foo1 , +and +.Li new_foo . +.Pp +When you have multiple definitions of a given symbol, there needs to be some +way to specify a default version to which external references to this symbol +will be bound. You can do this with the +.Li foo@@VERS_2.0 +type of +.Li .symver +directive. You can only declare one version of a symbol as the default in +this manner; otherwise you would effectively have multiple definitions of +the same symbol. +.Pp +If you wish to bind a reference to a specific version of the symbol within +the shared library, you can use the aliases of convenience (i.e., +.Li old_foo ) , +or you can use the +.Li .symver +directive to specifically bind to an external version of the function in question. +.Pp +You can also specify the language in the version script: +.Pp +.Bd -literal -offset indent +VERSION extern "lang" { version-script-commands } +.Ed +.Pp +The supported +.Li lang +s are +.Li C , +.Li C++ , +and +.Li Java . +The linker will iterate over the list of symbols at the link time and demangle +them according to +.Li lang +before matching them to the patterns specified in +.Li version-script-commands . +.Pp +Demangled names may contains spaces and other special characters. As described +above, you can use a glob pattern to match demangled names, or you can use +a double-quoted string to match the string exactly. In the latter case, be +aware that minor differences (such as differing whitespace) between the version +script and the demangler output will cause a mismatch. As the exact string +generated by the demangler might change in the future, even if the mangled +name does not, you should check that all of your version directives are behaving +as you expect when you upgrade. +.Pp +.Ss Expressions in Linker Scripts +The syntax for expressions in the linker script language is identical to that +of C expressions. All expressions are evaluated as integers. All expressions +are evaluated in the same size, which is 32 bits if both the host and target +are 32 bits, and is otherwise 64 bits. +.Pp +You can use and set symbol values in expressions. +.Pp +The linker defines several special purpose builtin functions for use in expressions. +.Pp +.Em Constants +.Pp +All constants are integers. +.Pp +As in C, the linker considers an integer beginning with +.Li 0 +to be octal, and an integer beginning with +.Li 0x +or +.Li 0X +to be hexadecimal. The linker considers other integers to be decimal. +.Pp +In addition, you can use the suffixes +.Li K +and +.Li M +to scale a constant by +.Li 1024 +or +.Li 1024*1024 +respectively. For example, the following all refer to the same quantity: +.Bd -literal -offset indent +_fourk_1 = 4K; +_fourk_2 = 4096; +_fourk_3 = 0x1000; +.Ed +.Pp +.Em Symbol Names +.Pp +Unless quoted, symbol names start with a letter, underscore, or period and +may include letters, digits, underscores, periods, and hyphens. 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: +.Bd -literal -offset indent +"SECTION" = 9; +"with a space" = "also with a space" + 10; +.Ed +.Pp +Since symbols can contain many non-alphabetic characters, it is safest to +delimit symbols with spaces. For example, +.Li A-B +is one symbol, whereas +.Li A - B +is an expression involving subtraction. +.Pp +.Em Orphan Sections +.Pp +Orphan sections are sections present in the input files which are not explicitly +placed into the output file by the linker script. The linker will still copy +these sections into the output file, but it has to guess as to where they +should be placed. The linker uses a simple heuristic to do this. It attempts +to place orphan sections after non-orphan sections of the same attribute, +such as code vs data, loadable vs non-loadable, etc. If there is not enough +room to do this then it places at the end of the file. +.Pp +For ELF targets, the attribute of the section includes section type as well +as section flag. +.Pp +.Em The Location Counter +.Pp +The special linker variable +.Em dot +.Li . +always contains the current output location counter. Since the +.Li . +always refers to a location in an output section, it may only appear in an +expression within a +.Li SECTIONS +command. The +.Li . +symbol may appear anywhere that an ordinary symbol is allowed in an expression. +.Pp +Assigning a value to +.Li . +will cause the location counter to be moved. This may be used to create holes +in the output section. The location counter may not be moved backwards inside +an output section, and may not be moved backwards outside of an output section +if so doing creates areas with overlapping LMAs. +.Pp +.Bd -literal -offset indent +SECTIONS +{ + output : + { + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + } = 0x12345678; +} +.Ed +In the previous example, the +.Li .text +section from +.Pa file1 +is located at the beginning of the output section +.Li output . +It is followed by a 1000 byte gap. Then the +.Li .text +section from +.Pa file2 +appears, also with a 1000 byte gap following before the +.Li .text +section from +.Pa file3 . +The notation +.Li = 0x12345678 +specifies what data to write in the gaps (see Section +.Dq Output Section Fill ) . +.Pp +Note: +.Li . +actually refers to the byte offset from the start of the current containing +object. Normally this is the +.Li SECTIONS +statement, whose start address is 0, hence +.Li . +can be used as an absolute address. If +.Li . +is used inside a section description however, it refers to the byte offset +from the start of that section, not an absolute address. Thus in a script +like this: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + . = 0x100 + .text: { + *(.text) + . = 0x200 + } + . = 0x500 + .data: { + *(.data) + . += 0x600 + } +} +.Ed +.Pp +The +.Li .text +section will be assigned a starting address of 0x100 and a size of exactly +0x200 bytes, even if there is not enough data in the +.Li .text +input sections to fill this area. (If there is too much data, an error will +be produced because this would be an attempt to move +.Li . +backwards). The +.Li .data +section will start at 0x500 and it will have an extra 0x600 bytes worth of +space after the end of the values from the +.Li .data +input sections and before the end of the +.Li .data +output section itself. +.Pp +Setting symbols to the value of the location counter outside of an output +section statement can result in unexpected values if the linker needs to place +orphan sections. For example, given the following: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +If the linker needs to place some input section, e.g. +.Li .rodata , +not mentioned in the script, it might choose to place that section between +.Li .text +and +.Li .data . +You might think the linker should place +.Li .rodata +on the blank line in the above script, but blank lines are of no particular +significance to the linker. As well, the linker doesn't associate the above +symbol names with their sections. Instead, it assumes that all assignments +or other statements belong to the previous output section, except for the +special case of an assignment to +.Li . . +I.e., the linker will place the orphan +.Li .rodata +section as if the script was written as follows: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .rodata: { *(.rodata) } + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +This may or may not be the script author's intention for the value of +.Li start_of_data . +One way to influence the orphan section placement is to assign the location +counter to itself, as the linker assumes that an assignment to +.Li . +is setting the start address of a following output section and thus should +be grouped with that section. So you could write: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + . = . ; + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +Now, the orphan +.Li .rodata +section will be placed between +.Li end_of_text +and +.Li start_of_data . +.Pp +.Em Operators +.Pp +The linker recognizes the standard C set of arithmetic operators, with the +standard bindings and precedence levels: +.Bd -literal -offset indent +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) +.Ed +Notes: (1) Prefix operators (2)See Section +.Dq Assignments . +.Pp +.Em Evaluation +.Pp +The linker evaluates expressions lazily. It only computes the value of an +expression when absolutely necessary. +.Pp +The linker needs some information, such as the value of the start address +of the first section, and the origins and 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 linker script. +.Pp +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. +.Pp +The sizes of sections cannot be known until after allocation, so assignments +dependent upon these are not performed until after allocation. +.Pp +Some expressions, such as those depending upon the location counter +.Li . , +must be evaluated during section allocation. +.Pp +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 +.Bd -literal -offset indent + +SECTIONS + { + .text 9+this_isnt_constant : + { *(.text) } + } + +.Ed +will cause the error message +.Li non constant expression for initial address . +.Pp +.Em The Section of an Expression +.Pp +When the linker evaluates an expression, the result is either absolute or +relative to some section. A relative expression is expressed as a fixed offset +from the base of a section. +.Pp +The position of the expression within the linker script determines whether +it is absolute or relative. An expression which appears within an output section +definition is relative to the base of the output section. An expression which +appears elsewhere will be absolute. +.Pp +A symbol set to a relative expression will be relocatable if you request relocatable +output using the +.Li -r +option. That means that a further link operation may change the value of the +symbol. The symbol's section will be the section of the relative expression. +.Pp +A symbol set to an absolute expression will retain the same value through +any further link operation. The symbol will be absolute, and will not have +any particular associated section. +.Pp +You can use the builtin function +.Li ABSOLUTE +to force an expression to be absolute when it would otherwise be relative. +For example, to create an absolute symbol set to the address of the end of +the output section +.Li .data : +.Bd -literal -offset indent +SECTIONS + { + .data : { *(.data) _edata = ABSOLUTE(.); } + } +.Ed +If +.Li ABSOLUTE +were not used, +.Li _edata +would be relative to the +.Li .data +section. +.Pp +.Em Builtin Functions +.Pp +The linker script language includes a number of builtin functions for use +in linker script expressions. +.Pp +.Bl -tag -width Ds +.It ABSOLUTE( Va exp) +Return the absolute (non-relocatable, as opposed to non-negative) value of +the expression +.Va exp . +Primarily useful to assign an absolute value to a symbol within a section +definition, where symbol values are normally section relative.See Section +.Dq Expression Section . +.Pp +.It ADDR( Va section) +Return the absolute address (the VMA) of the named +.Va section . +Your script must previously have defined the location of that section. In +the following example, +.Li symbol_1 +and +.Li symbol_2 +are assigned identical values: +.Bd -literal -offset indent + +SECTIONS { ... + .output1 : + { + start_of_output_1 = ABSOLUTE(.); + ... + } + .output : + { + symbol_1 = ADDR(.output1); + symbol_2 = start_of_output_1; + } +\&... } + +.Ed +.Pp +.It ALIGN( Va align) +.It ALIGN( Va exp, Va align) +Return the location counter ( +.Li . ) +or arbitrary expression aligned to the next +.Va align +boundary. The single operand +.Li ALIGN +doesn't change the value of the location counter---it just does arithmetic +on it. The two operand +.Li ALIGN +allows an arbitrary expression to be aligned upwards ( +.Li ALIGN( Va align) +is equivalent to +.Li ALIGN(., Va align) ) . +.Pp +Here is an example which aligns the output +.Li .data +section to the next +.Li 0x2000 +byte boundary after the preceding section and sets a variable within the section +to the next +.Li 0x8000 +boundary after the input sections: +.Bd -literal -offset indent + +SECTIONS { ... + .data ALIGN(0x2000): { + *(.data) + variable = ALIGN(0x8000); + } +\&... } + +.Ed +The first use of +.Li ALIGN +in this example specifies the location of a section because it is used as +the optional +.Va address +attribute of a section definition (see Section +.Dq Output Section Address ) . +The second use of +.Li ALIGN +is used to defines the value of a symbol. +.Pp +The builtin function +.Li NEXT +is closely related to +.Li ALIGN . +.Pp +.It ALIGNOF( Va section) +Return the alignment in bytes of the named +.Va section , +if that section has been allocated. If the section has not been allocated +when this is evaluated, the linker will report an error. In the following +example, the alignment of the +.Li .output +section is stored as the first value in that section. +.Bd -literal -offset indent + +SECTIONS{ ... + .output { + LONG (ALIGNOF (.output)) + ... + } +\&... } + +.Ed +.Pp +.It BLOCK( Va exp) +This is a synonym for +.Li ALIGN , +for compatibility with older linker scripts. It is most often seen when setting +the address of an output section. +.Pp +.It DATA_SEGMENT_ALIGN( Va maxpagesize, Va commonpagesize) +This is equivalent to either +.Bd -literal -offset indent +(ALIGN(maxpagesize) + (. & (maxpagesize - 1))) +.Ed +or +.Bd -literal -offset indent +(ALIGN(maxpagesize) + (. & (maxpagesize - commonpagesize))) +.Ed +depending on whether the latter uses fewer +.Va commonpagesize +sized pages for the data segment (area between the result of this expression +and +.Li DATA_SEGMENT_END ) +than the former or not. If the latter form is used, it means +.Va commonpagesize +bytes of runtime memory will be saved at the expense of up to +.Va commonpagesize +wasted bytes in the on-disk file. +.Pp +This expression can only be used directly in +.Li SECTIONS +commands, not in any output section descriptions and only once in the linker +script. +.Va commonpagesize +should be less or equal to +.Va maxpagesize +and should be the system page size the object wants to be optimized for (while +still working on system page sizes up to +.Va maxpagesize ) . +.Pp +Example: +.Bd -literal -offset indent + . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); +.Ed +.Pp +.It DATA_SEGMENT_END( Va exp) +This defines the end of data segment for +.Li DATA_SEGMENT_ALIGN +evaluation purposes. +.Pp +.Bd -literal -offset indent + . = DATA_SEGMENT_END(.); +.Ed +.Pp +.It DATA_SEGMENT_RELRO_END( Va offset, Va exp) +This defines the end of the +.Li PT_GNU_RELRO +segment when +.Li -z relro +option is used. Second argument is returned. When +.Li -z relro +option is not present, +.Li DATA_SEGMENT_RELRO_END +does nothing, otherwise +.Li DATA_SEGMENT_ALIGN +is padded so that +.Va exp ++ +.Va offset +is aligned to the most commonly used page boundary for particular target. +If present in the linker script, it must always come in between +.Li DATA_SEGMENT_ALIGN +and +.Li DATA_SEGMENT_END . +.Pp +.Bd -literal -offset indent + . = DATA_SEGMENT_RELRO_END(24, .); +.Ed +.Pp +.It DEFINED( Va symbol) +Return 1 if +.Va symbol +is in the linker global symbol table and is defined before the statement using +DEFINED in the script, otherwise return 0. You can use this function to provide +default values for symbols. For example, the following script fragment shows +how to set a global symbol +.Li begin +to the first location in the +.Li .text +section---but if a symbol called +.Li begin +already existed, its value is preserved: +.Pp +.Bd -literal -offset indent + +SECTIONS { ... + .text : { + begin = DEFINED(begin) ? begin : . ; + ... + } + ... +} + +.Ed +.Pp +.It LENGTH( Va memory) +Return the length of the memory region named +.Va memory . +.Pp +.It LOADADDR( Va section) +Return the absolute LMA of the named +.Va section . +This is normally the same as +.Li ADDR , +but it may be different if the +.Li AT +attribute is used in the output section definition (see Section +.Dq Output Section LMA ) . +.Pp +.It MAX( Va exp1, Va exp2) +Returns the maximum of +.Va exp1 +and +.Va exp2 . +.Pp +.It MIN( Va exp1, Va exp2) +Returns the minimum of +.Va exp1 +and +.Va exp2 . +.Pp +.It NEXT( Va exp) +Return the next unallocated address that is a multiple of +.Va exp . +This function is closely related to +.Li ALIGN( Va exp) ; +unless you use the +.Li MEMORY +command to define discontinuous memory for the output file, the two functions +are equivalent. +.Pp +.It ORIGIN( Va memory) +Return the origin of the memory region named +.Va memory . +.Pp +.It SEGMENT_START( Va segment, Va default) +Return the base address of the named +.Va segment . +If an explicit value has been given for this segment (with a command-line +.Li -T +option) that value will be returned; otherwise the value will be +.Va default . +At present, the +.Li -T +command-line option can only be used to set the base address for the \(lqtext\(rq, +\(lqdata\(rq, and \(lqbss\(rq sections, but you use +.Li SEGMENT_START +with any segment name. +.Pp +.It SIZEOF( Va section) +Return the size in bytes of the named +.Va section , +if that section has been allocated. If the section has not been allocated +when this is evaluated, the linker will report an error. In the following +example, +.Li symbol_1 +and +.Li symbol_2 +are assigned identical values: +.Bd -literal -offset indent + +SECTIONS{ ... + .output { + .start = . ; + ... + .end = . ; + } + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); +\&... } + +.Ed +.Pp +.It SIZEOF_HEADERS +.It sizeof_headers +Return the size in bytes of the output file's headers. This is information +which appears at the start of the output file. You can use this number when +setting the start address of the first section, if you choose, to facilitate +paging. +.Pp +When producing an ELF output file, if the linker script uses the +.Li SIZEOF_HEADERS +builtin function, the linker must compute the number of program headers before +it has determined all the section addresses and sizes. If the linker later +discovers that it needs additional program headers, it will report an error +.Li not enough room for program headers . +To avoid this error, you must avoid using the +.Li SIZEOF_HEADERS +function, or you must rework your linker script to avoid forcing the linker +to use additional program headers, or you must define the program headers +yourself using the +.Li PHDRS +command (see Section +.Dq PHDRS ) . +.El +.Pp +.Ss Implicit Linker Scripts +If you specify a linker input file which the linker can not recognize as an +object file or an archive file, it will try to read the file as a linker script. +If the file can not be parsed as a linker script, the linker will report an +error. +.Pp +An implicit linker script will not replace the default linker script. +.Pp +Typically an implicit linker script would contain only symbol assignments, +or the +.Li INPUT , +.Li GROUP , +or +.Li VERSION +commands. +.Pp +Any input files read because of an implicit linker script will be read at +the position in the command line where the implicit linker script was read. +This can affect archive searching. +.Pp +.Sh Machine Dependent Features +.Xr ld +has additional features on some platforms; the following sections describe +them. Machines where +.Xr ld +has no additional functionality are not listed. +.Pp +.Ss Xr ld and the H8/300 +For the H8/300, +.Xr ld +can perform these global optimizations when you specify the +.Li --relax +command-line option. +.Pp +.Bl -tag -width Ds +.It relaxing address modes +.Xr ld +finds all +.Li jsr +and +.Li jmp +instructions whose targets are within eight bits, and turns them into eight-bit +program-counter relative +.Li bsr +and +.Li bra +instructions, respectively. +.Pp +.It synthesizing instructions +.Xr ld +finds all +.Li 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 +.Li mov.b Li @ Va aa:16 +into +.Li mov.b Li @ Va aa:8 +whenever the address +.Va aa +is in the top page of memory). +.Pp +.It bit manipulation instructions +.Xr ld +finds all bit manipulation instructions like +.Li band, bclr, biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor +which use 32 bit and 16 bit absolute address form, but refer to the top page +of memory, and changes them to use the 8 bit address form. (That is: the linker +turns +.Li bset #xx:3, Li @ Va aa:32 +into +.Li bset #xx:3, Li @ Va aa:8 +whenever the address +.Va aa +is in the top page of memory). +.Pp +.It system control instructions +.Xr ld +finds all +.Li ldc.w, stc.w +instructions which use the 32 bit absolute address form, but refer to the +top page of memory, and changes them to use 16 bit address form. (That is: +the linker turns +.Li ldc.w Li @ Va aa:32,ccr +into +.Li ldc.w Li @ Va aa:16,ccr +whenever the address +.Va aa +is in the top page of memory). +.El +.Pp +.Ss Xr ld and the Intel 960 Family +You can use the +.Li -A Va architecture +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. +.Pp +For example, if your +.Xr ld +command line included +.Li -ACA +as well as +.Li -ltry +, the linker would look (in its built-in search paths, and in any paths you +specify with +.Li -L ) +for a library with the names +.Pp +.Bd -literal -offset indent + +try +libtry.a +tryca +libtryca.a + +.Ed +.Pp +The first two possibilities would be considered in any event; the last two +are due to the use of +.Li -ACA +\&. +.Pp +You can meaningfully use +.Li -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 +.Li -l +specifies a library. +.Pp +.Xr ld +supports the +.Li --relax +option for the i960 family. If you specify +.Li --relax , +.Xr ld +finds all +.Li balx +and +.Li calx +instructions whose targets are within 24 bits, and turns them into 24-bit +program-counter relative +.Li bal +and +.Li cal +instructions, respectively. +.Xr ld +also turns +.Li cal +instructions into +.Li bal +instructions when it determines that the target subroutine is a leaf routine +(that is, the target subroutine does not itself call any subroutines). +.Pp +.Ss Xr ld and the Motorola 68HC11 and 68HC12 families +.Em Linker Relaxation +.Pp +For the Motorola 68HC11, +.Xr ld +can perform these global optimizations when you specify the +.Li --relax +command-line option. +.Pp +.Bl -tag -width Ds +.It relaxing address modes +.Xr ld +finds all +.Li jsr +and +.Li jmp +instructions whose targets are within eight bits, and turns them into eight-bit +program-counter relative +.Li bsr +and +.Li bra +instructions, respectively. +.Pp +.Xr ld +also looks at all 16-bit extended addressing modes and transforms them in +a direct addressing mode when the address is in page 0 (between 0 and 0x0ff). +.Pp +.It relaxing gcc instruction group +When +.Xr gcc +is called with +.Op -mrelax , +it can emit group of instructions that the linker can optimize to use a 68HC11 +direct addressing mode. These instructions consists of +.Li bclr +or +.Li bset +instructions. +.Pp +.El +.Em Trampoline Generation +.Pp +For 68HC11 and 68HC12, +.Xr ld +can generate trampoline code to call a far function using a normal +.Li jsr +instruction. The linker will also change the relocation to some far function +to use the trampoline address instead of the function address. This is typically +the case when a pointer to a function is taken. The pointer will in fact point +to the function trampoline. +.Pp +The +.Li --pic-veneer +switch makes the linker use PIC sequences for ARM/Thumb interworking veneers, +even if the rest of the binary is not PIC. This avoids problems on uClinux +targets where +.Li --emit-relocs +is used to generate relocatable binaries. +.Pp +.Ss Xr ld and the ARM family +For the ARM, +.Xr ld +will generate code stubs to allow functions calls between ARM and Thumb code. +These stubs only work with code that has been compiled and assembled with +the +.Li -mthumb-interwork +command line option. If it is necessary to link with old ARM object files +or libraries, which have not been compiled with the -mthumb-interwork option +then the +.Li --support-old-code +command line switch should be given to the linker. This will make it generate +larger stub functions which will work with non-interworking aware ARM code. +Note, however, the linker does not support generating stubs for function calls +to non-interworking aware Thumb code. +.Pp +The +.Li --thumb-entry +switch is a duplicate of the generic +.Li --entry +switch, in that it sets the program's starting address. But it also sets the +bottom bit of the address, so that it can be branched to using a BX instruction, +and the program will start executing in Thumb mode straight away. +.Pp +The +.Li --be8 +switch instructs +.Xr ld +to generate BE8 format executables. This option is only valid when linking +big-endian objects. The resulting image will contain big-endian data and little-endian +code. +.Pp +The +.Li R_ARM_TARGET1 +relocation is typically used for entries in the +.Li .init_array +section. It is interpreted as either +.Li R_ARM_REL32 +or +.Li R_ARM_ABS32 , +depending on the target. The +.Li --target1-rel +and +.Li --target1-abs +switches override the default. +.Pp +The +.Li --target2=type +switch overrides the default definition of the +.Li R_ARM_TARGET2 +relocation. Valid values for +.Li type , +their meanings, and target defaults are as follows: +.Bl -tag -width Ds +.It rel +.Li R_ARM_REL32 +(arm*-*-elf, arm*-*-eabi) +.It abs +.Li R_ARM_ABS32 +(arm*-*-symbianelf) +.It got-rel +.Li R_ARM_GOT_PREL +(arm*-*-linux, arm*-*-*bsd) +.El +.Pp +The +.Li R_ARM_V4BX +relocation (defined by the ARM AAELF specification) enables objects compiled +for the ARMv4 architecture to be interworking-safe when linked with other +objects compiled for ARMv4t, but also allows pure ARMv4 binaries to be built +from the same ARMv4 objects. +.Pp +In the latter case, the switch +.Op --fix-v4bx +must be passed to the linker, which causes v4t +.Li BX rM +instructions to be rewritten as +.Li MOV PC,rM , +since v4 processors do not have a +.Li BX +instruction. +.Pp +In the former case, the switch should not be used, and +.Li R_ARM_V4BX +relocations are ignored. +.Pp +The +.Li --use-blx +switch enables the linker to use ARM/Thumb BLX instructions (available on +ARMv5t and above) in various situations. Currently it is used to perform calls +via the PLT from Thumb code using BLX rather than using BX and a mode-switching +stub before each PLT entry. This should lead to such calls executing slightly +faster. +.Pp +This option is enabled implicitly for SymbianOS, so there is no need to specify +it if you are using that target. +.Pp +The +.Li --vfp11-denorm-fix +switch enables a link-time workaround for a bug in certain VFP11 coprocessor +hardware, which sometimes allows instructions with denorm operands (which +must be handled by support code) to have those operands overwritten by subsequent +instructions before the support code can read the intended values. +.Pp +The bug may be avoided in scalar mode if you allow at least one intervening +instruction between a VFP11 instruction which uses a register and another +instruction which writes to the same register, or at least two intervening +instructions if vector mode is in use. The bug only affects full-compliance +floating-point mode: you do not need this workaround if you are using "runfast" +mode. Please contact ARM for further details. +.Pp +If you know you are using buggy VFP11 hardware, you can enable this workaround +by specifying the linker option +.Li --vfp-denorm-fix=scalar +if you are using the VFP11 scalar mode only, or +.Li --vfp-denorm-fix=vector +if you are using vector mode (the latter also works for scalar code). The +default is +.Li --vfp-denorm-fix=none . +.Pp +If the workaround is enabled, instructions are scanned for potentially-troublesome +sequences, and a veneer is created for each such sequence which may trigger +the erratum. The veneer consists of the first instruction of the sequence +and a branch back to the subsequent instruction. The original instruction +is then replaced with a branch to the veneer. The extra cycles required to +call and return from the veneer are sufficient to avoid the erratum in both +the scalar and vector cases. +.Pp +The +.Li --no-enum-size-warning +switch prevents the linker from warning when linking object files that specify +incompatible EABI enumeration size attributes. For example, with this switch +enabled, linking of an object file using 32-bit enumeration values with another +using enumeration values fitted into the smallest possible space will not +be diagnosed. +.Pp +.Ss Xr ld and HPPA 32-bit ELF Support +When generating a shared library, +.Xr ld +will by default generate import stubs suitable for use with a single sub-space +application. The +.Li --multi-subspace +switch causes +.Xr ld +to generate export stubs, and different (larger) import stubs suitable for +use with multiple sub-spaces. +.Pp +Long branch stubs and import/export stubs are placed by +.Xr ld +in stub sections located between groups of input sections. +.Li --stub-group-size +specifies the maximum size of a group of input sections handled by one stub +section. Since branch offsets are signed, a stub section may serve two groups +of input sections, one group before the stub section, and one group after +it. However, when using conditional branches that require stubs, it may be +better (for branch prediction) that stub sections only serve one group of +input sections. A negative value for +.Li N +chooses this scheme, ensuring that branches to stubs always use a negative +offset. Two special values of +.Li N +are recognized, +.Li 1 +and +.Li -1 . +These both instruct +.Xr ld +to automatically size input section groups for the branch types detected, +with the same behaviour regarding stub placement as other positive or negative +values of +.Li N +respectively. +.Pp +Note that +.Li --stub-group-size +does not split input sections. A single input section larger than the group +size specified will of course create a larger group (of one section). If input +sections are too large, it may not be possible for a branch to reach its stub. +.Pp +.Ss Li ld and MMIX +For MMIX, there is a choice of generating +.Li ELF +object files or +.Li mmo +object files when linking. The simulator +.Li mmix +understands the +.Li mmo +format. The binutils +.Li objcopy +utility can translate between the two formats. +.Pp +There is one special section, the +.Li .MMIX.reg_contents +section. Contents in this section is assumed to correspond to that of global +registers, and symbols referring to it are translated to special symbols, +equal to registers. In a final link, the start address of the +.Li .MMIX.reg_contents +section corresponds to the first allocated global register multiplied by 8. +Register +.Li $255 +is not included in this section; it is always set to the program entry, which +is at the symbol +.Li Main +for +.Li mmo +files. +.Pp +Symbols with the prefix +.Li __.MMIX.start. , +for example +.Li __.MMIX.start..text +and +.Li __.MMIX.start..data +are special; there must be only one each, even if they are local. The default +linker script uses these to set the default start address of a section. +.Pp +Initial and trailing multiples of zero-valued 32-bit words in a section, are +left out from an mmo file. +.Pp +.Ss Li ld and MSP430 +For the MSP430 it is possible to select the MPU architecture. The flag +.Li -m [mpu type] +will select an appropriate linker script for selected MPU type. (To get a +list of known MPUs just pass +.Li -m help +option to the linker). +.Pp +The linker will recognize some extra sections which are MSP430 specific: +.Pp +.Bl -tag -width Ds +.It Li .vectors +Defines a portion of ROM where interrupt vectors located. +.Pp +.It Li .bootloader +Defines the bootloader portion of the ROM (if applicable). Any code in this +section will be uploaded to the MPU. +.Pp +.It Li .infomem +Defines an information memory section (if applicable). Any code in this section +will be uploaded to the MPU. +.Pp +.It Li .infomemnobits +This is the same as the +.Li .infomem +section except that any code in this section will not be uploaded to the MPU. +.Pp +.It Li .noinit +Denotes a portion of RAM located above +.Li .bss +section. +.Pp +The last two sections are used by gcc. +.El +.Pp +.Ss Xr ld and PowerPC 32-bit ELF Support +Branches on PowerPC processors are limited to a signed 26-bit displacement, +which may result in +.Xr ld +giving +.Li relocation truncated to fit +errors with very large programs. +.Li --relax +enables the generation of trampolines that can access the entire 32-bit address +space. These trampolines are inserted at section boundaries, so may not themselves +be reachable if an input section exceeds 33M in size. +.Pp +.Bl -tag -width Ds +.It --bss-plt +Current PowerPC GCC accepts a +.Li -msecure-plt +option that generates code capable of using a newer PLT and GOT layout that +has the security advantage of no executable section ever needing to be writable +and no writable section ever being executable. PowerPC +.Xr ld +will generate this layout, including stubs to access the PLT, if all input +files (including startup and static libraries) were compiled with +.Li -msecure-plt . +.Li --bss-plt +forces the old BSS PLT (and GOT layout) which can give slightly better performance. +.Pp +.It --secure-plt +.Xr ld +will use the new PLT and GOT layout if it is linking new +.Li -fpic +or +.Li -fPIC +code, but does not do so automatically when linking non-PIC code. This option +requests the new PLT and GOT layout. A warning will be given if some object +file requires the old style BSS PLT. +.Pp +.It --sdata-got +The new secure PLT and GOT are placed differently relative to other sections +compared to older BSS PLT and GOT placement. The location of +.Li .plt +must change because the new secure PLT is an initialized section while the +old PLT is uninitialized. The reason for the +.Li .got +change is more subtle: The new placement allows +.Li .got +to be read-only in applications linked with +.Li -z relro -z now . +However, this placement means that +.Li .sdata +cannot always be used in shared libraries, because the PowerPC ABI accesses +.Li .sdata +in shared libraries from the GOT pointer. +.Li --sdata-got +forces the old GOT placement. PowerPC GCC doesn't use +.Li .sdata +in shared libraries, so this option is really only useful for other compilers +that may do so. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label linker stubs with a local symbol that encodes the stub type and destination. +.Pp +.It --no-tls-optimize +PowerPC +.Xr ld +normally performs some optimization of code sequences used to access Thread-Local +Storage. Use this option to disable the optimization. +.El +.Pp +.Ss Xr ld and PowerPC64 64-bit ELF Support +.Bl -tag -width Ds +.It --stub-group-size +Long branch stubs, PLT call stubs and TOC adjusting stubs are placed by +.Xr ld +in stub sections located between groups of input sections. +.Li --stub-group-size +specifies the maximum size of a group of input sections handled by one stub +section. Since branch offsets are signed, a stub section may serve two groups +of input sections, one group before the stub section, and one group after +it. However, when using conditional branches that require stubs, it may be +better (for branch prediction) that stub sections only serve one group of +input sections. A negative value for +.Li N +chooses this scheme, ensuring that branches to stubs always use a negative +offset. Two special values of +.Li N +are recognized, +.Li 1 +and +.Li -1 . +These both instruct +.Xr ld +to automatically size input section groups for the branch types detected, +with the same behaviour regarding stub placement as other positive or negative +values of +.Li N +respectively. +.Pp +Note that +.Li --stub-group-size +does not split input sections. A single input section larger than the group +size specified will of course create a larger group (of one section). If input +sections are too large, it may not be possible for a branch to reach its stub. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label linker stubs with a local symbol that encodes the stub type and destination. +.Pp +.It --dotsyms, --no-dotsyms +These two options control how +.Xr ld +interprets version patterns in a version script. Older PowerPC64 compilers +emitted both a function descriptor symbol with the same name as the function, +and a code entry symbol with the name prefixed by a dot ( +.Li . ) . +To properly version a function +.Li foo , +the version script thus needs to control both +.Li foo +and +.Li .foo . +The option +.Li --dotsyms , +on by default, automatically adds the required dot-prefixed patterns. Use +.Li --no-dotsyms +to disable this feature. +.Pp +.It --no-tls-optimize +PowerPC64 +.Xr ld +normally performs some optimization of code sequences used to access Thread-Local +Storage. Use this option to disable the optimization. +.Pp +.It --no-opd-optimize +PowerPC64 +.Xr ld +normally removes +.Li .opd +section entries corresponding to deleted link-once functions, or functions +removed by the action of +.Li --gc-sections +or linker scrip +.Li /DISCARD/ . +Use this option to disable +.Li .opd +optimization. +.Pp +.It --non-overlapping-opd +Some PowerPC64 compilers have an option to generate compressed +.Li .opd +entries spaced 16 bytes apart, overlapping the third word, the static chain +pointer (unused in C) with the first word of the next entry. This option expands +such entries to the full 24 bytes. +.Pp +.It --no-toc-optimize +PowerPC64 +.Xr ld +normally removes unused +.Li .toc +section entries. Such entries are detected by examining relocations that reference +the TOC in code sections. A reloc in a deleted code section marks a TOC word +as unneeded, while a reloc in a kept code section marks a TOC word as needed. +Since the TOC may reference itself, TOC relocs are also examined. TOC words +marked as both needed and unneeded will of course be kept. TOC words without +any referencing reloc are assumed to be part of a multi-word entry, and are +kept or discarded as per the nearest marked preceding word. This works reliably +for compiler generated code, but may be incorrect if assembly code is used +to insert TOC entries. Use this option to disable the optimization. +.Pp +.It --no-multi-toc +By default, PowerPC64 GCC generates code for a TOC model where TOC entries +are accessed with a 16-bit offset from r2. This limits the total TOC size +to 64K. PowerPC64 +.Xr ld +extends this limit by grouping code sections such that each group uses less +than 64K for its TOC entries, then inserts r2 adjusting stubs between inter-group +calls. +.Xr ld +does not split apart input sections, so cannot help if a single input file +has a +.Li .toc +section that exceeds 64K, most likely from linking multiple files with +.Xr ld -r . +Use this option to turn off this feature. +.El +.Pp +.Ss Xr ld and SPU ELF Support +.Bl -tag -width Ds +.It --plugin +This option marks an executable as a PIC plugin module. +.Pp +.It --no-overlays +Normally, +.Xr ld +recognizes calls to functions within overlay regions, and redirects such calls +to an overlay manager via a stub. +.Xr ld +also provides a built-in overlay manager. This option turns off all this special +overlay handling. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label overlay stubs with a local symbol that encodes the stub type and +destination. +.Pp +.It --extra-overlay-stubs +This option causes +.Xr ld +to add overlay call stubs on all function calls out of overlay regions. Normally +stubs are not added on calls to non-overlay regions. +.Pp +.It --local-store=lo:hi +.Xr ld +usually checks that a final executable for SPU fits in the address range 0 +to 256k. This option may be used to change the range. Disable the check entirely +with +.Op --local-store=0:0 . +.Pp +.It --stack-analysis +SPU local store space is limited. Over-allocation of stack space unnecessarily +limits space available for code and data, while under-allocation results in +runtime failures. If given this option, +.Xr ld +will provide an estimate of maximum stack usage. +.Xr ld +does this by examining symbols in code sections to determine the extents of +functions, and looking at function prologues for stack adjusting instructions. +A call-graph is created by looking for relocations on branch instructions. +The graph is then searched for the maximum stack usage path. Note that this +analysis does not find calls made via function pointers, and does not handle +recursion and other cycles in the call graph. Stack usage may be under-estimated +if your code makes such calls. Also, stack usage for dynamic allocation, e.g. +alloca, will not be detected. If a link map is requested, detailed information +about each function's stack usage and calls will be given. +.Pp +.It --emit-stack-syms +This option, if given along with +.Op --stack-analysis +will result in +.Xr ld +emitting stack sizing symbols for each function. These take the form +.Li __stack_<function_name> +for global functions, and +.Li __stack_<number>_<function_name> +for static functions. +.Li <number> +is the section id in hex. The value of such symbols is the stack requirement +for the corresponding function. The symbol size will be zero, type +.Li STT_NOTYPE , +binding +.Li STB_LOCAL , +and section +.Li SHN_ABS . +.El +.Pp +.Ss Xr ld's Support for Various TI COFF Versions +The +.Li --format +switch allows selection of one of the various TI COFF versions. The latest +of this writing is 2; versions 0 and 1 are also supported. The TI COFF versions +also vary in header byte-order format; +.Xr ld +will read any version or byte order, but the output header format depends +on the default specified by the specific target. +.Pp +.Ss Xr ld and WIN32 (cygwin/mingw) +This section describes some of the win32 specific +.Xr ld +issues. See Options,,Command Line Options for detailed description of the +command line options mentioned here. +.Pp +.Bl -tag -width Ds +.It import libraries +The standard Windows linker creates and uses so-called import libraries, which +contains information for linking to dll's. They are regular static archives +and are handled as any other static archive. The cygwin and mingw ports of +.Xr ld +have specific support for creating such libraries provided with the +.Li --out-implib +command line option. +.Pp +.It exporting DLL symbols +The cygwin/mingw +.Xr ld +has several ways to export symbols for dll's. +.Pp +.Bl -tag -width Ds +.It using auto-export functionality +By default +.Xr ld +exports symbols with the auto-export functionality, which is controlled by +the following command line options: +.Pp +.Bl -bullet +.It +--export-all-symbols [This is the default] +.It +--exclude-symbols +.It +--exclude-libs +.El +.Pp +If, however, +.Li --export-all-symbols +is not given explicitly on the command line, then the default auto-export +behavior will be +.Em disabled +if either of the following are true: +.Pp +.Bl -bullet +.It +A DEF file is used. +.It +Any symbol in any object file was marked with the __declspec(dllexport) attribute. +.El +.Pp +.It using a DEF file +Another way of exporting symbols is using a DEF file. A DEF file is an ASCII +file containing definitions of symbols which should be exported when a dll +is created. Usually it is named +.Li <dll name>.def +and is added as any other object file to the linker's command line. The file's +name must end in +.Li .def +or +.Li .DEF . +.Pp +.Bd -literal -offset indent +gcc -o <output> <objectfiles> <dll name>.def +.Ed +.Pp +Using a DEF file turns off the normal auto-export behavior, unless the +.Li --export-all-symbols +option is also used. +.Pp +Here is an example of a DEF file for a shared library called +.Li xyz.dll : +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x20000000 + +EXPORTS +foo +bar +_bar = bar +another_foo = abc.dll.afoo +var1 DATA +.Ed +.Pp +This example defines a DLL with a non-default base address and five symbols +in the export table. The third exported symbol +.Li _bar +is an alias for the second. The fourth symbol, +.Li another_foo +is resolved by "forwarding" to another module and treating it as an alias +for +.Li afoo +exported from the DLL +.Li abc.dll . +The final symbol +.Li var1 +is declared to be a data object. +.Pp +The optional +.Li LIBRARY <name> +command indicates the +.Em internal +name of the output DLL. If +.Li <name> +does not include a suffix, the default library suffix, +.Li .DLL +is appended. +.Pp +When the .DEF file is used to build an application, rather than a library, +the +.Li NAME <name> +command should be used instead of +.Li LIBRARY . +If +.Li <name> +does not include a suffix, the default executable suffix, +.Li .EXE +is appended. +.Pp +With either +.Li LIBRARY <name> +or +.Li NAME <name> +the optional specification +.Li BASE = <number> +may be used to specify a non-default base address for the image. +.Pp +If neither +.Li LIBRARY <name> +nor +.Li NAME <name> +is specified, or they specify an empty string, the internal name is the same +as the filename specified on the command line. +.Pp +The complete specification of an export symbol is: +.Pp +.Bd -literal -offset indent +EXPORTS + ( ( ( <name1> [ = <name2> ] ) + | ( <name1> = <module-name> . <external-name>)) + [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * +.Ed +.Pp +Declares +.Li <name1> +as an exported symbol from the DLL, or declares +.Li <name1> +as an exported alias for +.Li <name2> ; +or declares +.Li <name1> +as a "forward" alias for the symbol +.Li <external-name> +in the DLL +.Li <module-name> . +Optionally, the symbol may be exported by the specified ordinal +.Li <integer> +alias. +.Pp +The optional keywords that follow the declaration indicate: +.Pp +.Li NONAME : +Do not put the symbol name in the DLL's export table. It will still be exported +by its ordinal alias (either the value specified by the .def specification +or, otherwise, the value assigned by the linker). The symbol name, however, +does remain visible in the import library (if any), unless +.Li PRIVATE +is also specified. +.Pp +.Li DATA : +The symbol is a variable or object, rather than a function. The import lib +will export only an indirect reference to +.Li foo +as the symbol +.Li _imp__foo +(ie, +.Li foo +must be resolved as +.Li *_imp__foo ) . +.Pp +.Li CONSTANT : +Like +.Li DATA , +but put the undecorated +.Li foo +as well as +.Li _imp__foo +into the import library. Both refer to the read-only import address table's +pointer to the variable, not to the variable itself. This can be dangerous. +If the user code fails to add the +.Li dllimport +attribute and also fails to explicitly add the extra indirection that the +use of the attribute enforces, the application will behave unexpectedly. +.Pp +.Li PRIVATE : +Put the symbol in the DLL's export table, but do not put it into the static +import library used to resolve imports at link time. The symbol can still +be imported using the +.Li LoadLibrary/GetProcAddress +API at runtime or by by using the GNU ld extension of linking directly to +the DLL without an import library. See ld/deffilep.y in the binutils sources +for the full specification of other DEF file statements +.Pp +While linking a shared dll, +.Xr ld +is able to create a DEF file with the +.Li --output-def <file> +command line option. +.Pp +.It Using decorations +Another way of marking symbols for export is to modify the source code itself, +so that when building the DLL each symbol to be exported is declared as: +.Pp +.Bd -literal -offset indent +__declspec(dllexport) int a_variable +__declspec(dllexport) void a_function(int with_args) +.Ed +.Pp +All such symbols will be exported from the DLL. If, however, any of the object +files in the DLL contain symbols decorated in this way, then the normal auto-export +behavior is disabled, unless the +.Li --export-all-symbols +option is also used. +.Pp +Note that object files that wish to access these symbols must +.Em not +decorate them with dllexport. Instead, they should use dllimport, instead: +.Pp +.Bd -literal -offset indent +__declspec(dllimport) int a_variable +__declspec(dllimport) void a_function(int with_args) +.Ed +.Pp +This complicates the structure of library header files, because when included +by the library itself the header must declare the variables and functions +as dllexport, but when included by client code the header must declare them +as dllimport. There are a number of idioms that are typically used to do this; +often client code can omit the __declspec() declaration completely. See +.Li --enable-auto-import +and +.Li automatic data imports +for more information. +.El +.Pp +.It automatic data imports +The standard Windows dll format supports data imports from dlls only by adding +special decorations (dllimport/dllexport), which let the compiler produce +specific assembler instructions to deal with this issue. This increases the +effort necessary to port existing Un*x code to these platforms, especially +for large c++ libraries and applications. The auto-import feature, which was +initially provided by Paul Sokolovsky, allows one to omit the decorations +to achieve a behavior that conforms to that on POSIX/Un*x platforms. This +feature is enabled with the +.Li --enable-auto-import +command-line option, although it is enabled by default on cygwin/mingw. The +.Li --enable-auto-import +option itself now serves mainly to suppress any warnings that are ordinarily +emitted when linked objects trigger the feature's use. +.Pp +auto-import of variables does not always work flawlessly without additional +assistance. Sometimes, you will see this message +.Pp +"variable '<var>' can't be auto-imported. Please read the documentation for +ld's +.Li --enable-auto-import +for details." +.Pp +The +.Li --enable-auto-import +documentation explains why this error occurs, and several methods that can +be used to overcome this difficulty. One of these methods is the +.Em runtime pseudo-relocs +feature, described below. +.Pp +For complex variables imported from DLLs (such as structs or classes), object +files typically contain a base address for the variable and an offset ( +.Em addend ) +within the variable--to specify a particular field or public member, for instance. +Unfortunately, the runtime loader used in win32 environments is incapable +of fixing these references at runtime without the additional information supplied +by dllimport/dllexport decorations. The standard auto-import feature described +above is unable to resolve these references. +.Pp +The +.Li --enable-runtime-pseudo-relocs +switch allows these references to be resolved without error, while leaving +the task of adjusting the references themselves (with their non-zero addends) +to specialized code provided by the runtime environment. Recent versions of +the cygwin and mingw environments and compilers provide this runtime support; +older versions do not. However, the support is only necessary on the developer's +platform; the compiled result will run without error on an older system. +.Pp +.Li --enable-runtime-pseudo-relocs +is not the default; it must be explicitly enabled as needed. +.Pp +.It direct linking to a dll +The cygwin/mingw ports of +.Xr ld +support the direct linking, including data symbols, to a dll without the usage +of any import libraries. This is much faster and uses much less memory than +does the traditional import library method, especially when linking large +libraries or applications. When +.Xr ld +creates an import lib, each function or variable exported from the dll is +stored in its own bfd, even though a single bfd could contain many exports. +The overhead involved in storing, loading, and processing so many bfd's is +quite large, and explains the tremendous time, memory, and storage needed +to link against particularly large or complex libraries when using import +libs. +.Pp +Linking directly to a dll uses no extra command-line switches other than +.Li -L +and +.Li -l , +because +.Xr ld +already searches for a number of names to match each library. All that is +needed from the developer's perspective is an understanding of this search, +in order to force ld to select the dll instead of an import library. +.Pp +For instance, when ld is called with the argument +.Li -lxxx +it will attempt to find, in the first directory of its search path, +.Pp +.Bd -literal -offset indent +libxxx.dll.a +xxx.dll.a +libxxx.a +xxx.lib +cygxxx.dll (*) +libxxx.dll +xxx.dll +.Ed +.Pp +before moving on to the next directory in the search path. +.Pp +(*) Actually, this is not +.Li cygxxx.dll +but in fact is +.Li <prefix>xxx.dll , +where +.Li <prefix> +is set by the +.Xr ld +option +.Li --dll-search-prefix=<prefix> . +In the case of cygwin, the standard gcc spec file includes +.Li --dll-search-prefix=cyg , +so in effect we actually search for +.Li cygxxx.dll . +.Pp +Other win32-based unix environments, such as mingw or pw32, may use other +.Li <prefix> +es, although at present only cygwin makes use of this feature. It was originally +intended to help avoid name conflicts among dll's built for the various win32/un*x +environments, so that (for example) two versions of a zlib dll could coexist +on the same machine. +.Pp +The generic cygwin/mingw path layout uses a +.Li bin +directory for applications and dll's and a +.Li lib +directory for the import libraries (using cygwin nomenclature): +.Pp +.Bd -literal -offset indent +bin/ + cygxxx.dll +lib/ + libxxx.dll.a (in case of dll's) + libxxx.a (in case of static archive) +.Ed +.Pp +Linking directly to a dll without using the import library can be done two +ways: +.Pp +1. Use the dll directly by adding the +.Li bin +path to the link line +.Bd -literal -offset indent +gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx +.Ed +.Pp +However, as the dll's often have version numbers appended to their names ( +.Li cygncurses-5.dll ) +this will often fail, unless one specifies +.Li -L../bin -lncurses-5 +to include the version. Import libs are generally not versioned, and do not +have this difficulty. +.Pp +2. Create a symbolic link from the dll to a file in the +.Li lib +directory according to the above mentioned search pattern. This should be +used to avoid unwanted changes in the tools needed for making the app/dll. +.Pp +.Bd -literal -offset indent +ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] +.Ed +.Pp +Then you can link without any make environment changes. +.Pp +.Bd -literal -offset indent +gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx +.Ed +.Pp +This technique also avoids the version number problems, because the following +is perfectly legal +.Pp +.Bd -literal -offset indent +bin/ + cygxxx-5.dll +lib/ + libxxx.dll.a -> ../bin/cygxxx-5.dll +.Ed +.Pp +Linking directly to a dll without using an import lib will work even when +auto-import features are exercised, and even when +.Li --enable-runtime-pseudo-relocs +is used. +.Pp +Given the improvements in speed and memory usage, one might justifiably wonder +why import libraries are used at all. There are three reasons: +.Pp +1. Until recently, the link-directly-to-dll functionality did +.Em not +work with auto-imported data. +.Pp +2. Sometimes it is necessary to include pure static objects within the import +library (which otherwise contains only bfd's for indirection symbols that +point to the exports of a dll). Again, the import lib for the cygwin kernel +makes use of this ability, and it is not possible to do this without an import +lib. +.Pp +3. Symbol aliases can only be resolved using an import lib. This is critical +when linking against OS-supplied dll's (eg, the win32 API) in which symbols +are usually exported as undecorated aliases of their stdcall-decorated assembly +names. +.Pp +So, import libs are not going away. But the ability to replace true import +libs with a simple symbolic link to (or a copy of) a dll, in many cases, is +a useful addition to the suite of tools binutils makes available to the win32 +developer. Given the massive improvements in memory requirements during linking, +storage requirements, and linking speed, we expect that many developers will +soon begin to use this feature whenever possible. +.Pp +.It symbol aliasing +.Bl -tag -width Ds +.It adding additional names +Sometimes, it is useful to export symbols with additional names. A symbol +.Li foo +will be exported as +.Li foo , +but it can also be exported as +.Li _foo +by using special directives in the DEF file when creating the dll. This will +affect also the optional created import library. Consider the following DEF +file: +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +foo +_foo = foo +.Ed +.Pp +The line +.Li _foo = foo +maps the symbol +.Li foo +to +.Li _foo . +.Pp +Another method for creating a symbol alias is to create it in the source code +using the "weak" attribute: +.Pp +.Bd -literal -offset indent +void foo () { /* Do something. */; } +void _foo () __attribute__ ((weak, alias ("foo"))); +.Ed +.Pp +See the gcc manual for more information about attributes and weak symbols. +.Pp +.It renaming symbols +Sometimes it is useful to rename exports. For instance, the cygwin kernel +does this regularly. A symbol +.Li _foo +can be exported as +.Li foo +but not as +.Li _foo +by using special directives in the DEF file. (This will also affect the import +library, if it is created). In the following example: +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +_foo = foo +.Ed +.Pp +The line +.Li _foo = foo +maps the exported symbol +.Li foo +to +.Li _foo . +.El +.Pp +Note: using a DEF file disables the default auto-export behavior, unless the +.Li --export-all-symbols +command line option is used. If, however, you are trying to rename symbols, +then you should list +.Em all +desired exports in the DEF file, including the symbols that are not being +renamed, and do +.Em not +use the +.Li --export-all-symbols +option. If you list only the renamed symbols in the DEF file, and use +.Li --export-all-symbols +to handle the other symbols, then the both the new names +.Em and +the original names for the renamed symbols will be exported. In effect, you'd +be aliasing those symbols, not renaming them, which is probably not what you +wanted. +.Pp +.It weak externals +The Windows object format, PE, specifies a form of weak symbols called weak +externals. When a weak symbol is linked and the symbol is not defined, the +weak symbol becomes an alias for some other symbol. There are three variants +of weak externals: +.Bl -bullet +.It +Definition is searched for in objects and libraries, historically +called lazy externals. +.It +Definition is searched for only in other objects, not in libraries. +This form is not presently implemented. +.It +No search; the symbol is an alias. This form is not presently +implemented. +.El +As a GNU extension, weak symbols that do not specify an alternate symbol are +supported. If the symbol is undefined when linking, the symbol uses a default +value. +.El +.Pp +.Ss Li ld and Xtensa Processors +The default +.Xr ld +behavior for Xtensa processors is to interpret +.Li SECTIONS +commands so that lists of explicitly named sections in a specification with +a wildcard file will be interleaved when necessary to keep literal pools within +the range of PC-relative load offsets. For example, with the command: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + .text : { + *(.literal .text) + } +} +.Ed +.Pp +.Xr ld +may interleave some of the +.Li .literal +and +.Li .text +sections from different object files to ensure that the literal pools are +within the range of PC-relative load offsets. A valid interleaving might place +the +.Li .literal +sections from an initial group of files followed by the +.Li .text +sections of that group of files. Then, the +.Li .literal +sections from the rest of the files and the +.Li .text +sections from the rest of the files would follow. +.Pp +Relaxation is enabled by default for the Xtensa version of +.Xr ld +and provides two important link-time optimizations. The first optimization +is to combine identical literal values to reduce code size. A redundant literal +will be removed and all the +.Li L32R +instructions that use it will be changed to reference an identical literal, +as long as the location of the replacement literal is within the offset range +of all the +.Li L32R +instructions. The second optimization is to remove unnecessary overhead from +assembler-generated \(lqlongcall\(rq sequences of +.Li L32R +/ +.Li CALLX Va n +when the target functions are within range of direct +.Li CALL Va n +instructions. +.Pp +For each of these cases where an indirect call sequence can be optimized to +a direct call, the linker will change the +.Li CALLX Va n +instruction to a +.Li CALL Va n +instruction, remove the +.Li L32R +instruction, and remove the literal referenced by the +.Li L32R +instruction if it is not used for anything else. Removing the +.Li L32R +instruction always reduces code size but can potentially hurt performance +by changing the alignment of subsequent branch targets. By default, the linker +will always preserve alignments, either by switching some instructions between +24-bit encodings and the equivalent density instructions or by inserting a +no-op in place of the +.Li L32R +instruction that was removed. If code size is more important than performance, +the +.Op --size-opt +option can be used to prevent the linker from widening density instructions +or inserting no-ops, except in a few cases where no-ops are required for correctness. +.Pp +The following Xtensa-specific command-line options can be used to control +the linker: +.Pp +.Bl -tag -width Ds +.It --no-relax +Since the Xtensa version of +.Li ld +enables the +.Op --relax +option by default, the +.Op --no-relax +option is provided to disable relaxation. +.Pp +.It --size-opt +When optimizing indirect calls to direct calls, optimize for code size more +than performance. With this option, the linker will not insert no-ops or widen +density instructions to preserve branch target alignment. There may still +be some cases where no-ops are required to preserve the correctness of the +code. +.El +.Pp +.Sh 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. To conserve +runtime memory, however, the linker and associated tools are usually configured +to support only a subset of the object file formats available. You can use +.Li objdump -i +(see Section +.Dq objdump ) +to list all the formats available for your configuration. +.Pp +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. +.Pp +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.See Section +.Dq BFD information loss . +.Pp +.Ss 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. +.Pp +As different information from 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. +.Pp +.Em Information Loss +.Pp +.Em 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 +.Li b.out . +There is nowhere in an +.Li a.out +format file to store alignment information on the contained data, so when +a file is linked from +.Li b.out +and an +.Li 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). +.Pp +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., +.Li 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. +.Pp +.Em 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. +.Pp +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 +.Li a.out +to +.Li b.out . +When a mixture of formats is linked, the information is only lost from the +files whose format differs from the destination. +.Pp +.Em The BFD canonical object-file format +.Pp +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. +.Pp +.Bl -tag -width Ds +.It 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 +.Li 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. +.Pp +.It 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. +.Pp +.It 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. +.Li ld +can operate on a collection of symbols of wildly different formats without +problems. +.Pp +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 +.Li 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. +.Pp +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. +.Pp +.It 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. +.Pp +.It 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). +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making +.Xr ld +reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of +.Xr ld +work better. Bug reports are your contribution to the maintenance of +.Xr ld . +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If the linker gets a fatal signal, for any input whatever, that is a +.Xr ld +bug. Reliable linkers never crash. +.Pp +.It +If +.Xr ld +produces an error message for valid input, that is a bug. +.Pp +.It +If +.Xr ld +does not produce an error message for invalid input, that may be a bug. In +the general case, the linker can not verify that object files are correct. +.Pp +.It +If you are an experienced user of linkers, your suggestions for improvement +of +.Xr ld +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained +.Xr ld +from a support organization, we recommend you contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a symbol you use in an example does not matter. Well, probably it +does not, but one cannot be sure. Perhaps the bug is a stray memory reference +which happens to fetch from the location where that name is stored in memory; +perhaps, if the name were different, the contents of that location would fool +the linker into doing the right thing despite the bug. Play it safe and give +a specific, complete example. That is the easiest thing for you to do, and +the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of +.Xr ld . +.Xr ld +announces it if you start it with the +.Li --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of +.Xr ld . +.Pp +.It +Any patches you may have applied to the +.Xr ld +source, including any patches made to the +.Li BFD +library. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile +.Xr ld +---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the linker to link your example and observe +the bug. To guarantee you will not omit something important, list them all. +A copy of the Makefile (or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file, or set of input files, that will reproduce the bug. +It is generally most helpful to send the actual object files provided that +they are reasonably small. Say no more than 10K. For bigger files you can +either make them available by FTP or HTTP or else state that you are willing +to send the object file(s) to whomever requests them. (Note - your email will +be going to a mailing list, so we do not want to clog it up with large attachments). +But small attachments are best. +.Pp +If the source files were assembled using +.Li gas +or compiled using +.Li gcc , +then it may be OK to send the source files rather than the object files. In +this case, be sure to say exactly what version of +.Li gas +or +.Li gcc +was used to produce the object files. Also say how +.Li gas +or +.Li gcc +were configured. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that +.Xr ld +gets a fatal signal, then we will certainly notice it. But if the bug is incorrect +output, we might not notice unless it is glaringly wrong. You might as well +not give us a chance to make a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as, your copy of +.Xr ld +is out of sync, or you have encountered a bug in the C library on your system. +(This has happened!) Your copy might crash and ours would not. If you told +us to expect a crash, then when ours fails to crash, we would know that the +bug was not happening for us. If you had not told us to expect a crash, then +we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the +.Xr ld +source, send us context diffs, as generated by +.Li diff +with the +.Li -u , +.Li -c , +or +.Li -p +option. Always send diffs from the old file to the new file. If you even discuss +something in the +.Xr ld +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with a program as complicated as +.Xr ld +it is very hard to construct an example that will make the program follow +a certain path through the code. If you do not send us the example, we will +not be able to construct one, so we will not be able to verify that the bug +is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh MRI Compatible Script Files +To aid users making the transition to GNU +.Xr ld +from the MRI linker, +.Xr ld +can use MRI compatible linker scripts as an alternative to the more general-purpose +linker scripting language described in Scripts. MRI compatible linker scripts +have a much simpler command set than the scripting language otherwise used +with +.Xr ld . +GNU +.Xr ld +supports the most commonly used MRI linker commands; these commands are described +here. +.Pp +In general, MRI scripts aren't of much use with the +.Li a.out +object file format, since it only has three sections and MRI scripts lack +some features to make use of them. +.Pp +You can specify a file containing an MRI-compatible script using the +.Li -c +command-line option. +.Pp +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, +.Xr ld +issues a warning message, but continues processing the script. +.Pp +Lines beginning with +.Li * +are comments. +.Pp +You can write these commands using all upper-case letters, or all lower case; +for example, +.Li chip +is the same as +.Li CHIP . +The following list shows only the upper-case form of each command. +.Pp +.Bl -tag -width Ds +.It ABSOLUTE Va secname +.It ABSOLUTE Va secname, Va secname, ... Va secname +Normally, +.Xr ld +includes in the output file all sections from all the input files. However, +in an MRI-compatible script, you can use the +.Li ABSOLUTE +command to restrict the sections that will be present in your output program. +If the +.Li ABSOLUTE +command is used at all in a script, then only the sections named explicitly +in +.Li ABSOLUTE +commands will appear in the linker output. You can still use other input sections +(whatever you select on the command line, or using +.Li LOAD ) +to resolve addresses in the output file. +.Pp +.It ALIAS Va out-secname, Va in-secname +Use this command to place the data from input section +.Va in-secname +in a section called +.Va out-secname +in the linker output file. +.Pp +.Va in-secname +may be an integer. +.Pp +.It ALIGN Va secname = Va expression +Align the section called +.Va secname +to +.Va expression . +The +.Va expression +should be a power of two. +.Pp +.It BASE Va expression +Use the value of +.Va expression +as the lowest address (other than absolute addresses) in the output file. +.Pp +.It CHIP Va expression +.It CHIP Va expression, Va expression +This command does nothing; it is accepted only for compatibility. +.Pp +.It END +This command does nothing whatever; it's only accepted for compatibility. +.Pp +.It FORMAT Va output-format +Similar to the +.Li OUTPUT_FORMAT +command in the more general linker language, but restricted to one of these +output formats: +.Pp +.Bl -enum +.It +S-records, if +.Va output-format +is +.Li S +.Pp +.It +IEEE, if +.Va output-format +is +.Li IEEE +.Pp +.It +COFF (the +.Li coff-m68k +variant in BFD), if +.Va output-format +is +.Li COFF +.El +.Pp +.It LIST Va anything... +Print (to the standard output file) a link map, as produced by the +.Xr ld +command-line option +.Li -M . +.Pp +The keyword +.Li LIST +may be followed by anything on the same line, with no change in its effect. +.Pp +.It LOAD Va filename +.It LOAD Va filename, Va filename, ... Va filename +Include one or more object file +.Va filename +in the link; this has the same effect as specifying +.Va filename +directly on the +.Xr ld +command line. +.Pp +.It NAME Va output-name +.Va output-name +is the name for the program produced by +.Xr ld ; +the MRI-compatible command +.Li NAME +is equivalent to the command-line option +.Li -o +or the general script language command +.Li OUTPUT . +.Pp +.It ORDER Va secname, Va secname, ... Va secname +.It ORDER Va secname Va secname Va secname +Normally, +.Xr 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 +.Li ORDER +command. The sections you list with +.Li ORDER +will appear first in your output file, in the order specified. +.Pp +.It PUBLIC Va name= Va expression +.It PUBLIC Va name, Va expression +.It PUBLIC Va name Va expression +Supply a value ( +.Va expression ) +for external symbol +.Va name +used in the linker input files. +.Pp +.It SECT Va secname, Va expression +.It SECT Va secname= Va expression +.It SECT Va secname Va expression +You can use any of these three forms of the +.Li SECT +command to specify the start address ( +.Va expression ) +for section +.Va secname . +If you have more than one +.Li SECT +statement for the same +.Va secname , +only the +.Em first +sets the start address. +.El +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document 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. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation 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. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh LD Index diff --git a/contrib/binutils/ld/ld.txt b/contrib/binutils/ld/ld.txt deleted file mode 100644 index e4aa1f17d050..000000000000 --- a/contrib/binutils/ld/ld.txt +++ /dev/null @@ -1,6564 +0,0 @@ -START-INFO-DIR-ENTRY -* Ld: (ld). The GNU linker. -END-INFO-DIR-ENTRY - -LD -1 Overview -2 Invocation - 2.1 Command Line Options - 2.1.1 Options Specific to i386 PE Targets - 2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets - 2.2 Environment Variables -3 Linker Scripts - 3.1 Basic Linker Script Concepts - 3.2 Linker Script Format - 3.3 Simple Linker Script Example - 3.4 Simple Linker Script Commands - 3.4.1 Setting the Entry Point - 3.4.2 Commands Dealing with Files - 3.4.3 Commands Dealing with Object File Formats - 3.4.4 Other Linker Script Commands - 3.5 Assigning Values to Symbols - 3.5.1 Simple Assignments - 3.5.2 PROVIDE - 3.5.3 PROVIDE_HIDDEN - 3.5.4 Source Code Reference - 3.6 SECTIONS Command - 3.6.1 Output Section Description - 3.6.2 Output Section Name - 3.6.3 Output Section Address - 3.6.4 Input Section Description - 3.6.4.1 Input Section Basics - 3.6.4.2 Input Section Wildcard Patterns - 3.6.4.3 Input Section for Common Symbols - 3.6.4.4 Input Section and Garbage Collection - 3.6.4.5 Input Section Example - 3.6.5 Output Section Data - 3.6.6 Output Section Keywords - 3.6.7 Output Section Discarding - 3.6.8 Output Section Attributes - 3.6.8.1 Output Section Type - 3.6.8.2 Output Section LMA - 3.6.8.3 Forced Output Alignment - 3.6.8.4 Forced Input Alignment - 3.6.8.5 Output Section Region - 3.6.8.6 Output Section Phdr - 3.6.8.7 Output Section Fill - 3.6.9 Overlay Description - 3.7 MEMORY Command - 3.8 PHDRS Command - 3.9 VERSION Command - 3.10 Expressions in Linker Scripts - 3.10.1 Constants - 3.10.2 Symbol Names - 3.10.3 Orphan Sections - 3.10.4 The Location Counter - 3.10.5 Operators - 3.10.6 Evaluation - 3.10.7 The Section of an Expression - 3.10.8 Builtin Functions - 3.11 Implicit Linker Scripts -4 Machine Dependent Features - 4.1 'ld' and the H8/300 - 4.2 'ld' and the Intel 960 Family - 4.3 'ld' and the Motorola 68HC11 and 68HC12 families - 4.3.1 Linker Relaxation - 4.3.2 Trampoline Generation - 4.4 'ld' and the ARM family - 4.5 'ld' and HPPA 32-bit ELF Support - 4.6 'ld' and MMIX - 4.7 'ld' and MSP430 - 4.8 'ld' and PowerPC 32-bit ELF Support - 4.9 'ld' and PowerPC64 64-bit ELF Support - 4.10 'ld' and SPU ELF Support - 4.11 'ld''s Support for Various TI COFF Versions - 4.12 'ld' and WIN32 (cygwin/mingw) - 4.13 'ld' and Xtensa Processors -5 BFD - 5.1 How It Works: An Outline of BFD - 5.1.1 Information Loss - 5.1.2 The BFD canonical object-file format -6 Reporting Bugs - 6.1 Have You Found a Bug? - 6.2 How to Report Bugs -Appendix A MRI Compatible Script Files -Appendix B GNU Free Documentation License - ADDENDUM: How to use this License for your documents -LD Index -LD -** - -This file documents the GNU linker ld version "2.17.50 [FreeBSD] -2007-07-03". - - This document is distributed under the terms of the GNU Free -Documentation License. A copy of the license is included in the section -entitled "GNU Free Documentation License". - -1 Overview -********** - -'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 more information. - - 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). - -2 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. - -2.1 Command Line Options -======================== - -The linker supports a plethora of command-line options, 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.) - - Some of the command-line options to 'ld' may be specified at any -point in the command line. However, options which refer to files, such -as '-l' or '-T', cause the file to be read at the point at which the -option appears in the command line, relative to the object files and -other file options. Repeating non-file 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. Options which may be meaningfully specified more than once are -noted in the descriptions below. - - Non-option arguments are object files or archives which are to be -linked together. They may follow, precede, or be mixed in with -command-line options, except that an object file 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'. - - If the linker cannot recognize the format of an object file, it will -assume that it is a linker script. A script specified in this way -augments the main linker script used for the link (either the default -linker script or the one specified by using '-T'). This feature permits -the linker to link against a file which appears to be an object or an -archive, but actually merely defines some symbol values, or uses 'INPUT' -or 'GROUP' to load other objects. Note that specifying a script in this -way merely augments the main linker script; use the '-T' option to -replace the default linker script entirely. *Note Scripts::. - - For options whose names are a single letter, option arguments must -either follow the option letter without intervening whitespace, or be -given as separate arguments immediately following the option that -requires them. - - For options whose names are multiple letters, either one dash or two -can precede the option name; for example, '-trace-symbol' and -'--trace-symbol' are equivalent. Note--there is one exception to this -rule. Multiple letter options that start with a lower case 'o' can only -be preceded by two dashes. This is to reduce confusion with the '-o' -option. So for example '-omagic' sets the output file name to 'magic' -whereas '--omagic' sets the NMAGIC flag on the output. - - Arguments to multiple-letter options must either be separated from -the option name by an equals sign, or be given as separate arguments -immediately following the option that requires them. For example, -'--trace-symbol foo' and '--trace-symbol=foo' are equivalent. Unique -abbreviations of the names of multiple-letter options are accepted. - - Note--if the linker is being invoked indirectly, via a compiler -driver (e.g. 'gcc') then all the linker command line options should be -prefixed by '-Wl,' (or whatever is appropriate for the particular -compiler driver) like this: - - gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup - - This is important, because otherwise the compiler driver program may -silently drop the linker options, resulting in a bad link. - - Here is a table of the generic command line switches accepted by the -GNU linker: - -'@FILE' - Read command-line options from FILE. The options read are inserted - in place of the original @FILE option. If FILE does not exist, or - cannot be read, then the option will be treated literally, and not - removed. - - Options in FILE are separated by whitespace. A whitespace - character may be included in an option by surrounding the entire - option in either single or double quotes. Any character (including - a backslash) may be included by prefixing the character to be - included with a backslash. The FILE may itself contain additional - @FILE options; any such options will be processed recursively. - -'-aKEYWORD' - This option is supported for HP/UX compatibility. The KEYWORD - argument must be one of the strings 'archive', 'shared', or - 'default'. '-aarchive' is functionally equivalent to '-Bstatic', - and the other two keywords are functionally equivalent to - '-Bdynamic'. This option may be used any number of times. - -'-AARCHITECTURE' -'--architecture=ARCHITECTURE' - 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' -'--format=INPUT-FORMAT' - 'ld' may be configured to support more than one kind of object - file. If your 'ld' is configured this way, you can use the '-b' - option to specify the binary format for input object files that - follow this option on the command line. Even when 'ld' is - configured to support alternative object formats, you don't usually - need to specify this, as 'ld' should be 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'.) *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 Format - Commands::. - -'-c MRI-COMMANDFILE' -'--mri-script=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 Miscellaneous Commands::. - -'-e ENTRY' -'--entry=ENTRY' - Use ENTRY as the explicit symbol for beginning execution of your - program, rather than the default entry point. If there is no - symbol named ENTRY, the linker will try to parse ENTRY as a number, - and use that as the entry address (the number will be interpreted - in base 10; you may use a leading '0x' for base 16, or a leading - '0' for base 8). *Note Entry Point::, for a discussion of defaults - and other ways of specifying the entry point. - -'--exclude-libs LIB,LIB,...' - Specifies a list of archive libraries from which symbols should not - be automatically exported. The library names may be delimited by - commas or colons. Specifying '--exclude-libs ALL' excludes symbols - in all archive libraries from automatic export. This option is - available only for the i386 PE targeted port of the linker and for - ELF targeted ports. For i386 PE, symbols explicitly listed in a - .def file are still exported, regardless of this option. For ELF - targeted ports, symbols affected by this option will be treated as - hidden. - -'-E' -'--export-dynamic' - When creating a dynamically linked executable, add all symbols to - the dynamic symbol table. The dynamic symbol table is the set of - symbols which are visible from dynamic objects at run time. - - If you do not use this option, the dynamic symbol table will - normally contain only those symbols which are referenced by some - dynamic object mentioned in the link. - - If you use 'dlopen' to load a dynamic object which needs to refer - back to the symbols defined by the program, rather than some other - dynamic object, then you will probably need to use this option when - linking the program itself. - - You can also use the dynamic list to control what symbols should be - added to the dynamic symbol table if the output format supports it. - See the description of '--dynamic-list'. - -'-EB' - Link big-endian objects. This affects the default output format. - -'-EL' - Link little-endian objects. This affects the default output - format. - -'-f' -'--auxiliary NAME' - When creating an ELF shared object, set the internal DT_AUXILIARY - field to the specified name. This tells the dynamic linker that - the symbol table of the shared object should be used as an - auxiliary filter on the symbol table of the shared object NAME. - - If you later link a program against this filter object, then, when - you run the program, the dynamic linker will see the DT_AUXILIARY - field. If the dynamic linker resolves any symbols from the filter - object, it will first check whether there is a definition in the - shared object NAME. If there is one, it will be used instead of - the definition in the filter object. The shared object NAME need - not exist. Thus the shared object NAME may be used to provide an - alternative implementation of certain functions, perhaps for - debugging or for machine specific performance. - - This option may be specified more than once. The DT_AUXILIARY - entries will be created in the order in which they appear on the - command line. - -'-F NAME' -'--filter NAME' - When creating an ELF shared object, set the internal DT_FILTER - field to the specified name. This tells the dynamic linker that - the symbol table of the shared object which is being created should - be used as a filter on the symbol table of the shared object NAME. - - If you later link a program against this filter object, then, when - you run the program, the dynamic linker will see the DT_FILTER - field. The dynamic linker will resolve symbols according to the - symbol table of the filter object as usual, but it will actually - link to the definitions found in the shared object NAME. Thus the - filter object can be used to select a subset of the symbols - provided by the object NAME. - - Some older linkers used the '-F' option throughout a compilation - toolchain for specifying object-file format for both input and - output object files. The GNU linker uses other mechanisms for this - purpose: the '-b', '--format', '--oformat' options, the 'TARGET' - command in linker scripts, and the 'GNUTARGET' environment - variable. The GNU linker will ignore the '-F' option when not - creating an ELF shared object. - -'-fini NAME' - When creating an ELF executable or shared object, call NAME when - the executable or shared object is unloaded, by setting DT_FINI to - the address of the function. By default, the linker uses '_fini' - as the function to call. - -'-g' - Ignored. Provided for compatibility with other tools. - -'-GVALUE' -'--gpsize=VALUE' - Set the maximum size of objects to be optimized using the GP - register to SIZE. This is only meaningful for object file formats - such as MIPS ECOFF which supports putting large and small objects - into different sections. This is ignored for other object file - formats. - -'-hNAME' -'-soname=NAME' - When creating an ELF shared object, set the internal DT_SONAME - field to the specified name. When an executable is linked with a - shared object which has a DT_SONAME field, then when the executable - is run the dynamic linker will attempt to load the shared object - specified by the DT_SONAME field rather than the using the file - name given to the linker. - -'-i' - Perform an incremental link (same as option '-r'). - -'-init NAME' - When creating an ELF executable or shared object, call NAME when - the executable or shared object is loaded, by setting DT_INIT to - the address of the function. By default, the linker uses '_init' - as the function to call. - -'-lNAMESPEC' -'--library=NAMESPEC' - Add the archive or object file specified by NAMESPEC to the list of - files to link. This option may be used any number of times. If - NAMESPEC is of the form ':FILENAME', 'ld' will search the library - path for a file called FILENAME, otherise it will search the - library path for a file called 'libNAMESPEC.a'. - - On systems which support shared libraries, 'ld' may also search for - files other than 'libNAMESPEC.a'. Specifically, on ELF and SunOS - systems, 'ld' will search a directory for a library called - 'libNAMESPEC.so' before searching for one called 'libNAMESPEC.a'. - (By convention, a '.so' extension indicates a shared library.) - Note that this behavior does not apply to ':FILENAME', which always - specifies a file called FILENAME. - - The linker will search an archive only once, at the location where - it is specified on the command line. If the archive defines a - symbol which was undefined in some object which appeared before the - archive on the command line, the linker will include the - appropriate file(s) from the archive. However, an undefined symbol - in an object appearing later on the command line will not cause the - linker to search the archive again. - - See the '-(' option for a way to force the linker to search - archives multiple times. - - You may list the same archive multiple times on the command line. - - This type of archive searching is standard for Unix linkers. - However, if you are using 'ld' on AIX, note that it is different - from the behaviour of the AIX linker. - -'-LSEARCHDIR' -'--library-path=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 directories are searched in the - order in which they are specified on the command line. Directories - specified on the command line are searched before the default - directories. All '-L' options apply to all '-l' options, - regardless of the order in which the options appear. - - If SEARCHDIR begins with '=', then the '=' will be replaced by the - "sysroot prefix", a path specified when the linker is configured. - - 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. Directories specified this way are searched - at the point in which the linker script appears in the command - line. - -'-mEMULATION' - Emulate the EMULATION linker. You can list the available - emulations with the '--verbose' or '-V' options. - - If the '-m' option is not used, the emulation is taken from the - 'LDEMULATION' environment variable, if that is defined. - - Otherwise, the default emulation depends upon how the linker was - configured. - -'-M' -'--print-map' - Print a link map to the standard output. A link map provides - information about the link, including the following: - - * Where object files are mapped into memory. - * How common symbols are allocated. - * All archive members included in the link, with a mention of - the symbol which caused the archive member to be brought in. - * The values assigned to symbols. - - Note - symbols whose values are computed by an expression - which involves a reference to a previous value of the same - symbol may not have correct result displayed in the link map. - This is because the linker discards intermediate results and - only retains the final value of an expression. Under such - circumstances the linker will display the final value enclosed - by square brackets. Thus for example a linker script - containing: - - foo = 1 - foo = foo * 4 - foo = foo + 8 - - will produce the following output in the link map if the '-M' - option is used: - - 0x00000001 foo = 0x1 - [0x0000000c] foo = (foo * 0x4) - [0x0000000c] foo = (foo + 0x8) - - See *note Expressions:: for more information about expressions - in linker scripts. - -'-n' -'--nmagic' - Turn off page alignment of sections, and mark the output as - 'NMAGIC' if possible. - -'-N' -'--omagic' - Set the text and data sections to be readable and writable. Also, - do not page-align the data segment, and disable linking against - shared libraries. If the output format supports Unix style magic - numbers, mark the output as 'OMAGIC'. Note: Although a writable - text section is allowed for PE-COFF targets, it does not conform to - the format specification published by Microsoft. - -'--no-omagic' - This option negates most of the effects of the '-N' option. It - sets the text section to be read-only, and forces the data segment - to be page-aligned. Note - this option does not enable linking - against shared libraries. Use '-Bdynamic' for this. - -'-o OUTPUT' -'--output=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. - -'-O LEVEL' - If LEVEL is a numeric values greater than zero 'ld' optimizes the - output. This might take significantly longer and therefore - probably should only be enabled for the final binary. - -'-q' -'--emit-relocs' - Leave relocation sections and contents in fully linked executables. - Post link analysis and optimization tools may need this information - in order to perform correct modifications of executables. This - results in larger executables. - - This option is currently only supported on ELF platforms. - -'--force-dynamic' - Force the output file to have dynamic sections. This option is - specific to VxWorks targets. - -'-r' -'--relocatable' - 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'. - - When an input file does not have the same format as the output - file, partial linking is only supported if that input file does not - contain any relocations. Different output formats can have further - restrictions; for example some 'a.out'-based formats do not support - partial linking with input files in other formats at all. - - This option does the same thing as '-i'. - -'-R FILENAME' -'--just-symbols=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. You may use this option more than once. - - For compatibility with other ELF linkers, if the '-R' option is - followed by a directory name, rather than a file name, it is - treated as the '-rpath' option. - -'-s' -'--strip-all' - Omit all symbol information from the output file. - -'-S' -'--strip-debug' - Omit debugger symbol information (but not all symbols) from the - output file. - -'-t' -'--trace' - Print the names of the input files as 'ld' processes them. - -'-T SCRIPTFILE' -'--script=SCRIPTFILE' - Use SCRIPTFILE as the linker script. This script replaces 'ld''s - default linker script (rather than adding to it), so COMMANDFILE - must specify everything necessary to describe the output file. - *Note Scripts::. If SCRIPTFILE does not exist in the current - directory, 'ld' looks for it in the directories specified by any - preceding '-L' options. Multiple '-T' options accumulate. - -'-dT SCRIPTFILE' -'--default-script=SCRIPTFILE' - Use SCRIPTFILE as the default linker script. *Note Scripts::. - - This option is similar to the '--script' option except that - processing of the script is delayed until after the rest of the - command line has been processed. This allows options placed after - the '--default-script' option on the command line to affect the - behaviour of the linker script, which can be important when the - linker command line cannot be directly controlled by the user. (eg - because the command line is being constructed by another tool, such - as 'gcc'). - -'-u SYMBOL' -'--undefined=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. - This option is equivalent to the 'EXTERN' linker script command. - -'-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' _does_ 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 cannot be - added to. Use '-Ur' only for the last partial link, and '-r' for - the others. - -'--unique[=SECTION]' - Creates a separate output section for every input section matching - SECTION, or if the optional wildcard SECTION argument is missing, - for every orphan input section. An orphan section is one not - specifically mentioned in a linker script. You may use this option - multiple times on the command line; It prevents the normal merging - of input sections with the same name, overriding output section - assignments in a linker script. - -'-v' -'--version' -'-V' - Display the version number for 'ld'. The '-V' option also lists - the supported emulations. - -'-x' -'--discard-all' - Delete all local symbols. - -'-X' -'--discard-locals' - Delete all temporary local symbols. (These symbols start with - system-specific local label prefixes, typically '.L' for ELF - systems or 'L' for traditional a.out systems.) - -'-y SYMBOL' -'--trace-symbol=SYMBOL' - 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. - -'-Y PATH' - Add PATH to the default library search path. This option exists - for Solaris compatibility. - -'-z KEYWORD' - The recognized keywords are: - - 'combreloc' - Combines multiple reloc sections and sorts them to make - dynamic symbol lookup caching possible. - - 'defs' - Disallows undefined symbols in object files. Undefined - symbols in shared libraries are still allowed. - - 'execstack' - Marks the object as requiring executable stack. - - 'initfirst' - This option is only meaningful when building a shared object. - It marks the object so that its runtime initialization will - occur before the runtime initialization of any other objects - brought into the process at the same time. Similarly the - runtime finalization of the object will occur after the - runtime finalization of any other objects. - - 'interpose' - Marks the object that its symbol table interposes before all - symbols but the primary executable. - - 'lazy' - When generating an executable or shared library, mark it to - tell the dynamic linker to defer function call resolution to - the point when the function is called (lazy binding), rather - than at load time. Lazy binding is the default. - - 'loadfltr' - Marks the object that its filters be processed immediately at - runtime. - - 'muldefs' - Allows multiple definitions. - - 'nocombreloc' - Disables multiple reloc sections combining. - - 'nocopyreloc' - Disables production of copy relocs. - - 'nodefaultlib' - Marks the object that the search for dependencies of this - object will ignore any default library search paths. - - 'nodelete' - Marks the object shouldn't be unloaded at runtime. - - 'nodlopen' - Marks the object not available to 'dlopen'. - - 'nodump' - Marks the object can not be dumped by 'dldump'. - - 'noexecstack' - Marks the object as not requiring executable stack. - - 'norelro' - Don't create an ELF 'PT_GNU_RELRO' segment header in the - object. - - 'now' - When generating an executable or shared library, mark it to - tell the dynamic linker to resolve all symbols when the - program is started, or when the shared library is linked to - using dlopen, instead of deferring function call resolution to - the point when the function is first called. - - 'origin' - Marks the object may contain $ORIGIN. - - 'relro' - Create an ELF 'PT_GNU_RELRO' segment header in the object. - - 'max-page-size=VALUE' - Set the emulation maximum page size to VALUE. - - 'common-page-size=VALUE' - Set the emulation common page size to VALUE. - - Other keywords are ignored for Solaris compatibility. - -'-( ARCHIVES -)' -'--start-group ARCHIVES --end-group' - The ARCHIVES should be a list of archive files. They may be either - explicit file names, or '-l' options. - - The specified archives are searched repeatedly until no new - undefined references are created. Normally, an archive is searched - only once in the order that it is specified on the command line. - If a symbol in that archive is needed to resolve an undefined - symbol referred to by an object in an archive that appears later on - the command line, the linker would not be able to resolve that - reference. By grouping the archives, they all be searched - repeatedly until all possible references are resolved. - - Using this option has a significant performance cost. It is best - to use it only when there are unavoidable circular references - between two or more archives. - -'--accept-unknown-input-arch' -'--no-accept-unknown-input-arch' - Tells the linker to accept input files whose architecture cannot be - recognised. The assumption is that the user knows what they are - doing and deliberately wants to link in these unknown input files. - This was the default behaviour of the linker, before release 2.14. - The default behaviour from release 2.14 onwards is to reject such - input files, and so the '--accept-unknown-input-arch' option has - been added to restore the old behaviour. - -'--as-needed' -'--no-as-needed' - This option affects ELF DT_NEEDED tags for dynamic libraries - mentioned on the command line after the '--as-needed' option. - Normally, the linker will add a DT_NEEDED tag for each dynamic - library mentioned on the command line, regardless of whether the - library is actually needed. '--as-needed' causes DT_NEEDED tags to - only be emitted for libraries that satisfy some symbol reference - from regular objects which is undefined at the point that the - library was linked. '--no-as-needed' restores the default - behaviour. - -'--add-needed' -'--no-add-needed' - This option affects the treatment of dynamic libraries from ELF - DT_NEEDED tags in dynamic libraries mentioned on the command line - after the '--no-add-needed' option. Normally, the linker will add - a DT_NEEDED tag for each dynamic library from DT_NEEDED tags. - '--no-add-needed' causes DT_NEEDED tags will never be emitted for - those libraries from DT_NEEDED tags. '--add-needed' restores the - default behaviour. - -'-assert KEYWORD' - This option is ignored for SunOS compatibility. - -'-Bdynamic' -'-dy' -'-call_shared' - Link against dynamic libraries. This is only meaningful on - platforms for which shared libraries are supported. This option is - normally the default on such platforms. The different variants of - this option are for compatibility with various systems. You may - use this option multiple times on the command line: it affects - library searching for '-l' options which follow it. - -'-Bgroup' - Set the 'DF_1_GROUP' flag in the 'DT_FLAGS_1' entry in the dynamic - section. This causes the runtime linker to handle lookups in this - object and its dependencies to be performed only inside the group. - '--unresolved-symbols=report-all' is implied. This option is only - meaningful on ELF platforms which support shared libraries. - -'-Bstatic' -'-dn' -'-non_shared' -'-static' - Do not link against shared libraries. This is only meaningful on - platforms for which shared libraries are supported. The different - variants of this option are for compatibility with various systems. - You may use this option multiple times on the command line: it - affects library searching for '-l' options which follow it. This - option also implies '--unresolved-symbols=report-all'. This option - can be used with '-shared'. Doing so means that a shared library - is being created but that all of the library's external references - must be resolved by pulling in entries from static libraries. - -'-Bsymbolic' - When creating a shared library, bind references to global symbols - to the definition within the shared library, if any. Normally, it - is possible for a program linked against a shared library to - override the definition within the shared library. This option is - only meaningful on ELF platforms which support shared libraries. - -'-Bsymbolic-functions' - When creating a shared library, bind references to global function - symbols to the definition within the shared library, if any. This - option is only meaningful on ELF platforms which support shared - libraries. - -'--dynamic-list=DYNAMIC-LIST-FILE' - Specify the name of a dynamic list file to the linker. This is - typically used when creating shared libraries to specify a list of - global symbols whose references shouldn't be bound to the - definition within the shared library, or creating dynamically - linked executables to specify a list of symbols which should be - added to the symbol table in the executable. This option is only - meaningful on ELF platforms which support shared libraries. - - The format of the dynamic list is the same as the version node - without scope and node name. See *note VERSION:: for more - information. - -'--dynamic-list-data' - Include all global data symbols to the dynamic list. - -'--dynamic-list-cpp-new' - Provide the builtin dynamic list for C++ operator new and delete. - It is mainly useful for building shared libstdc++. - -'--dynamic-list-cpp-typeinfo' - Provide the builtin dynamic list for C++ runtime type - identification. - -'--check-sections' -'--no-check-sections' - Asks the linker _not_ to check section addresses after they have - been assigned to see if there are any overlaps. Normally the - linker will perform this check, and if it finds any overlaps it - will produce suitable error messages. The linker does know about, - and does make allowances for sections in overlays. The default - behaviour can be restored by using the command line switch - '--check-sections'. - -'--cref' - Output a cross reference table. If a linker map file is being - generated, the cross reference table is printed to the map file. - Otherwise, it is printed on the standard output. - - The format of the table is intentionally simple, so that it may be - easily processed by a script if necessary. The symbols are printed - out, sorted by name. For each symbol, a list of file names is - given. If the symbol is defined, the first file listed is the - location of the definition. The remaining files contain references - to the symbol. - -'--no-define-common' - This option inhibits the assignment of addresses to common symbols. - The script command 'INHIBIT_COMMON_ALLOCATION' has the same effect. - *Note Miscellaneous Commands::. - - The '--no-define-common' option allows decoupling the decision to - assign addresses to Common symbols from the choice of the output - file type; otherwise a non-Relocatable output type forces assigning - addresses to Common symbols. Using '--no-define-common' allows - Common symbols that are referenced from a shared library to be - assigned addresses only in the main program. This eliminates the - unused duplicate space in the shared library, and also prevents any - possible confusion over resolving to the wrong duplicate when there - are many dynamic modules with specialized search paths for runtime - symbol resolution. - -'--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: Assignments.). _Note:_ there - should be no white space between SYMBOL, the equals sign ("<=>"), - and EXPRESSION. - -'--demangle[=STYLE]' -'--no-demangle' - These options control whether to demangle symbol names in error - messages and other output. When the linker is told to demangle, it - tries to present symbol names in a readable fashion: it strips - leading underscores if they are used by the object file format, and - converts C++ mangled symbol names into user readable names. - Different compilers have different mangling styles. The optional - demangling style argument can be used to choose an appropriate - demangling style for your compiler. The linker will demangle by - default unless the environment variable 'COLLECT_NO_DEMANGLE' is - set. These options may be used to override the default. - -'--dynamic-linker FILE' - Set the name of the dynamic linker. This is only meaningful when - generating dynamically linked ELF executables. The default dynamic - linker is normally correct; don't use this unless you know what you - are doing. - -'--fatal-warnings' - Treat all warnings as errors. - -'--force-exe-suffix' - Make sure that an output file has a .exe suffix. - - If a successfully built fully linked output file does not have a - '.exe' or '.dll' suffix, this option forces the linker to copy the - output file to one of the same name with a '.exe' suffix. This - option is useful when using unmodified Unix makefiles on a - Microsoft Windows host, since some versions of Windows won't run an - image unless it ends in a '.exe' suffix. - -'--gc-sections' -'--no-gc-sections' - Enable garbage collection of unused input sections. It is ignored - on targets that do not support this option. This option is not - compatible with '-r' or '--emit-relocs'. The default behaviour (of - not performing this garbage collection) can be restored by - specifying '--no-gc-sections' on the command line. - -'--print-gc-sections' -'--no-print-gc-sections' - List all sections removed by garbage collection. The listing is - printed on stderr. This option is only effective if garbage - collection has been enabled via the '--gc-sections') option. The - default behaviour (of not listing the sections that are removed) - can be restored by specifying '--no-print-gc-sections' on the - command line. - -'--help' - Print a summary of the command-line options on the standard output - and exit. - -'--target-help' - Print a summary of all target specific options on the standard - output and exit. - -'-Map MAPFILE' - Print a link map to the file MAPFILE. See the description of the - '-M' option, above. - -'--no-keep-memory' - 'ld' normally optimizes for speed over memory usage by caching the - symbol tables of input files in memory. This option tells 'ld' to - instead optimize for memory usage, by rereading the symbol tables - as necessary. This may be required if 'ld' runs out of memory - space while linking a large executable. - -'--no-undefined' -'-z defs' - Report unresolved symbol references from regular object files. - This is done even if the linker is creating a non-symbolic shared - library. The switch '--[no-]allow-shlib-undefined' controls the - behaviour for reporting unresolved references found in shared - libraries being linked in. - -'--allow-multiple-definition' -'-z muldefs' - Normally when a symbol is defined multiple times, the linker will - report a fatal error. These options allow multiple definitions and - the first definition will be used. - -'--allow-shlib-undefined' -'--no-allow-shlib-undefined' - Allows (the default) or disallows undefined symbols in shared - libraries. This switch is similar to '--no-undefined' except that - it determines the behaviour when the undefined symbols are in a - shared library rather than a regular object file. It does not - affect how undefined symbols in regular object files are handled. - - The reason that '--allow-shlib-undefined' is the default is that - the shared library being specified at link time may not be the same - as the one that is available at load time, so the symbols might - actually be resolvable at load time. Plus there are some systems, - (eg BeOS) where undefined symbols in shared libraries is normal. - (The kernel patches them at load time to select which function is - most appropriate for the current architecture. This is used for - example to dynamically select an appropriate memset function). - Apparently it is also normal for HPPA shared libraries to have - undefined symbols. - -'--no-undefined-version' - Normally when a symbol has an undefined version, the linker will - ignore it. This option disallows symbols with undefined version - and a fatal error will be issued instead. - -'--default-symver' - Create and use a default symbol version (the soname) for - unversioned exported symbols. - -'--default-imported-symver' - Create and use a default symbol version (the soname) for - unversioned imported symbols. - -'--no-warn-mismatch' - Normally 'ld' will give an error if you try to link together input - files that are mismatched for some reason, perhaps because they - have been compiled for different processors or for different - endiannesses. This option tells 'ld' that it should silently - permit such possible errors. This option should only be used with - care, in cases when you have taken some special action that ensures - that the linker errors are inappropriate. - -'--no-warn-search-mismatch' - Normally 'ld' will give a warning if it finds an incompatible - library during a library search. This option silences the warning. - -'--no-whole-archive' - Turn off the effect of the '--whole-archive' option for subsequent - archive files. - -'--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. - -'-nostdlib' - Only search library directories explicitly specified on the command - line. Library directories specified in linker scripts (including - linker scripts specified on the command line) are ignored. - -'--oformat OUTPUT-FORMAT' - 'ld' may be configured to support more than one kind of object - file. If your 'ld' is configured this way, you can use the - '--oformat' option to specify the binary format for the output - object file. Even when 'ld' is configured to support alternative - object formats, you don't usually need to specify this, as 'ld' - should be 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::. - -'-pie' -'--pic-executable' - Create a position independent executable. This is currently only - supported on ELF platforms. Position independent executables are - similar to shared libraries in that they are relocated by the - dynamic linker to the virtual address the OS chooses for them - (which can vary between invocations). Like normal dynamically - linked executables they can be executed and symbols defined in the - executable cannot be overridden by shared libraries. - -'-qmagic' - This option is ignored for Linux compatibility. - -'-Qy' - This option is ignored for SVR4 compatibility. - -'--relax' - An option with machine dependent effects. This option is only - supported on a few targets. *Note 'ld' and the H8/300: H8/300. - *Note 'ld' and the Intel 960 family: i960. *Note 'ld' and Xtensa - Processors: Xtensa. *Note 'ld' and the 68HC11 and 68HC12: - M68HC11/68HC12. *Note 'ld' and PowerPC 32-bit ELF Support: PowerPC - ELF32. - - On some platforms, the '--relax' 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 some platforms these link time global optimizations may make - symbolic debugging of the resulting executable impossible. This is - known to be the case for the Matsushita MN10200 and MN10300 family - of processors. - - On platforms where this is not supported, '--relax' is accepted, - but ignored. - -'--retain-symbols-file FILENAME' - Retain _only_ the symbols listed in the file FILENAME, discarding - all others. FILENAME is simply a flat file, with one symbol name - per line. This option is especially useful in environments (such - as VxWorks) where a large global symbol table is accumulated - gradually, to conserve run-time memory. - - '--retain-symbols-file' does _not_ discard undefined symbols, or - symbols needed for relocations. - - You may only specify '--retain-symbols-file' once in the command - line. It overrides '-s' and '-S'. - -'-rpath DIR' - Add a directory to the runtime library search path. This is used - when linking an ELF executable with shared objects. All '-rpath' - arguments are concatenated and passed to the runtime linker, which - uses them to locate shared objects at runtime. The '-rpath' option - is also used when locating shared objects which are needed by - shared objects explicitly included in the link; see the description - of the '-rpath-link' option. If '-rpath' is not used when linking - an ELF executable, the contents of the environment variable - 'LD_RUN_PATH' will be used if it is defined. - - The '-rpath' option may also be used on SunOS. By default, on - SunOS, the linker will form a runtime search patch out of all the - '-L' options it is given. If a '-rpath' option is used, the - runtime search path will be formed exclusively using the '-rpath' - options, ignoring the '-L' options. This can be useful when using - gcc, which adds many '-L' options which may be on NFS mounted file - systems. - - For compatibility with other ELF linkers, if the '-R' option is - followed by a directory name, rather than a file name, it is - treated as the '-rpath' option. - -'-rpath-link DIR' - When using ELF or SunOS, one shared library may require another. - This happens when an 'ld -shared' link includes a shared library as - one of the input files. - - When the linker encounters such a dependency when doing a - non-shared, non-relocatable link, it will automatically try to - locate the required shared library and include it in the link, if - it is not included explicitly. In such a case, the '-rpath-link' - option specifies the first set of directories to search. The - '-rpath-link' option may specify a sequence of directory names - either by specifying a list of names separated by colons, or by - appearing multiple times. - - This option should be used with caution as it overrides the search - path that may have been hard compiled into a shared library. In - such a case it is possible to use unintentionally a different - search path than the runtime linker would do. - - The linker uses the following search paths to locate required - shared libraries: - 1. Any directories specified by '-rpath-link' options. - 2. Any directories specified by '-rpath' options. The difference - between '-rpath' and '-rpath-link' is that directories - specified by '-rpath' options are included in the executable - and used at runtime, whereas the '-rpath-link' option is only - effective at link time. Searching '-rpath' in this way is - only supported by native linkers and cross linkers which have - been configured with the '--with-sysroot' option. - 3. On an ELF system, if the '-rpath' and 'rpath-link' options - were not used, search the contents of the environment variable - 'LD_RUN_PATH'. It is for the native linker only. - 4. On SunOS, if the '-rpath' option was not used, search any - directories specified using '-L' options. - 5. For a native linker, the contents of the environment variable - 'LD_LIBRARY_PATH'. - 6. For a native ELF linker, the directories in 'DT_RUNPATH' or - 'DT_RPATH' of a shared library are searched for shared - libraries needed by it. The 'DT_RPATH' entries are ignored if - 'DT_RUNPATH' entries exist. - 7. The default directories, normally '/lib' and '/usr/lib'. - 8. For a native linker on an ELF system, if the file - '/etc/ld.so.conf' exists, the list of directories found in - that file. - - If the required shared library is not found, the linker will issue - a warning and continue with the link. - -'-shared' -'-Bshareable' - Create a shared library. This is currently only supported on ELF, - XCOFF and SunOS platforms. On SunOS, the linker will automatically - create a shared library if the '-e' option is not used and there - are undefined symbols in the link. - -'--sort-common' - This option tells 'ld' to sort the common symbols by size when it - places them in the appropriate output sections. First come all the - one byte symbols, then all the two byte, then all the four byte, - and then everything else. This is to prevent gaps between symbols - due to alignment constraints. - -'--sort-section name' - This option will apply 'SORT_BY_NAME' to all wildcard section - patterns in the linker script. - -'--sort-section alignment' - This option will apply 'SORT_BY_ALIGNMENT' to all wildcard section - patterns in the linker script. - -'--split-by-file [SIZE]' - Similar to '--split-by-reloc' but creates a new output section for - each input file when SIZE is reached. SIZE defaults to a size of 1 - if not given. - -'--split-by-reloc [COUNT]' - Tries to creates extra sections in the output file so that no - single output section in the file contains more than COUNT - relocations. This is useful when generating huge relocatable files - for downloading into certain real time kernels with the COFF object - file format; since COFF cannot represent more than 65535 - relocations in a single section. Note that this will fail to work - with object file formats which do not support arbitrary sections. - The linker will not split up individual input sections for - redistribution, so if a single input section contains more than - COUNT relocations one output section will contain that many - relocations. COUNT defaults to a value of 32768. - -'--stats' - Compute and display statistics about the operation of the linker, - such as execution time and memory usage. - -'--sysroot=DIRECTORY' - Use DIRECTORY as the location of the sysroot, overriding the - configure-time default. This option is only supported by linkers - that were configured using '--with-sysroot'. - -'--traditional-format' - For some targets, the output of 'ld' is different in some ways from - the output of some existing linker. This switch requests 'ld' to - use the traditional format instead. - - For example, on SunOS, 'ld' combines duplicate entries in the - symbol string table. This can reduce the size of an output file - with full debugging information by over 30 percent. Unfortunately, - the SunOS 'dbx' program can not read the resulting program ('gdb' - has no trouble). The '--traditional-format' switch tells 'ld' to - not combine duplicate entries. - -'--section-start SECTIONNAME=ORG' - Locate a section in the output file at the absolute address given - by ORG. You may use this option as many times as necessary to - locate multiple sections in the command line. ORG must be a single - hexadecimal integer; for compatibility with other linkers, you may - omit the leading '0x' usually associated with hexadecimal values. - _Note:_ there should be no white space between SECTIONNAME, the - equals sign ("<=>"), and ORG. - -'-Tbss ORG' -'-Tdata ORG' -'-Ttext ORG' - Same as -section-start, with '.bss', '.data' or '.text' as the - SECTIONNAME. - -'--unresolved-symbols=METHOD' - Determine how to handle unresolved symbols. There are four - possible values for 'method': - - 'ignore-all' - Do not report any unresolved symbols. - - 'report-all' - Report all unresolved symbols. This is the default. - - 'ignore-in-object-files' - Report unresolved symbols that are contained in shared - libraries, but ignore them if they come from regular object - files. - - 'ignore-in-shared-libs' - Report unresolved symbols that come from regular object files, - but ignore them if they come from shared libraries. This can - be useful when creating a dynamic binary and it is known that - all the shared libraries that it should be referencing are - included on the linker's command line. - - The behaviour for shared libraries on their own can also be - controlled by the '--[no-]allow-shlib-undefined' option. - - Normally the linker will generate an error message for each - reported unresolved symbol but the option - '--warn-unresolved-symbols' can change this to a warning. - -'--dll-verbose' -'--verbose' - Display the version number for 'ld' and list the linker emulations - supported. Display which input files can and cannot be opened. - Display the linker script being used by the linker. - -'--version-script=VERSION-SCRIPTFILE' - Specify the name of a version script to the linker. This is - typically used when creating shared libraries to specify additional - information about the version hierarchy for the library being - created. This option is only meaningful on ELF platforms which - support shared libraries. *Note VERSION::. - -'--warn-common' - Warn when a common symbol is combined with another common symbol or - with a symbol definition. Unix linkers allow this somewhat sloppy - practise, 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 practise, 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 - -'--warn-constructors' - Warn if any global constructors are used. This is only useful for - a few object file formats. For formats like COFF or ELF, the - linker can not detect the use of global constructors. - -'--warn-multiple-gp' - Warn if multiple global pointer values are required in the output - file. This is only meaningful for certain processors, such as the - Alpha. Specifically, some processors put large-valued constants in - a special section. A special register (the global pointer) points - into the middle of this section, so that constants can be loaded - efficiently via a base-register relative addressing mode. Since - the offset in base-register relative mode is fixed and relatively - small (e.g., 16 bits), this limits the maximum size of the constant - pool. Thus, in large programs, it is often necessary to use - multiple global pointer values in order to be able to address all - possible constants. This option causes a warning to be issued - whenever this case occurs. - -'--warn-once' - Only warn once for each undefined symbol, rather than once per - module which refers to it. - -'--warn-section-align' - Warn if the address of an output section is changed because of - alignment. Typically, the alignment will be set by an input - section. The address will only be changed if it not explicitly - specified; that is, if the 'SECTIONS' command does not specify a - start address for the section (*note SECTIONS::). - -'--warn-shared-textrel' - Warn if the linker adds a DT_TEXTREL to a shared object. - -'--warn-unresolved-symbols' - If the linker is going to report an unresolved symbol (see the - option '--unresolved-symbols') it will normally generate an error. - This option makes it generate a warning instead. - -'--error-unresolved-symbols' - This restores the linker's default behaviour of generating errors - when it is reporting unresolved symbols. - -'--whole-archive' - For each archive mentioned on the command line after the - '--whole-archive' option, include every object file in the archive - in the link, rather than searching the archive for the required - object files. This is normally used to turn an archive file into a - shared library, forcing every object to be included in the - resulting shared library. This option may be used more than once. - - Two notes when using this option from gcc: First, gcc doesn't know - about this option, so you have to use '-Wl,-whole-archive'. - Second, don't forget to use '-Wl,-no-whole-archive' after your list - of archives, because gcc will add its own list of archives to your - link and you may not want this flag to affect those as well. - -'--wrap SYMBOL' - Use a wrapper function for SYMBOL. Any undefined reference to - SYMBOL will be resolved to '__wrap_SYMBOL'. Any undefined - reference to '__real_SYMBOL' will be resolved to SYMBOL. - - This can be used to provide a wrapper for a system function. The - wrapper function should be called '__wrap_SYMBOL'. If it wishes to - call the system function, it should call '__real_SYMBOL'. - - Here is a trivial example: - - void * - __wrap_malloc (size_t c) - { - printf ("malloc called with %zu\n", c); - return __real_malloc (c); - } - - If you link other code with this file using '--wrap malloc', then - all calls to 'malloc' will call the function '__wrap_malloc' - instead. The call to '__real_malloc' in '__wrap_malloc' will call - the real 'malloc' function. - - You may wish to provide a '__real_malloc' function as well, so that - links without the '--wrap' option will succeed. If you do this, - you should not put the definition of '__real_malloc' in the same - file as '__wrap_malloc'; if you do, the assembler may resolve the - call before the linker has a chance to wrap it to 'malloc'. - -'--eh-frame-hdr' - Request creation of '.eh_frame_hdr' section and ELF - 'PT_GNU_EH_FRAME' segment header. - -'--enable-new-dtags' -'--disable-new-dtags' - This linker can create the new dynamic tags in ELF. But the older - ELF systems may not understand them. If you specify - '--enable-new-dtags', the dynamic tags will be created as needed. - If you specify '--disable-new-dtags', no new dynamic tags will be - created. By default, the new dynamic tags are not created. Note - that those options are only available for ELF systems. - -'--hash-size=NUMBER' - Set the default size of the linker's hash tables to a prime number - close to NUMBER. Increasing this value can reduce the length of - time it takes the linker to perform its tasks, at the expense of - increasing the linker's memory requirements. Similarly reducing - this value can reduce the memory requirements at the expense of - speed. - -'--hash-style=STYLE' - Set the type of linker's hash table(s). STYLE can be either 'sysv' - for classic ELF '.hash' section, 'gnu' for new style GNU - '.gnu.hash' section or 'both' for both the classic ELF '.hash' and - new style GNU '.gnu.hash' hash tables. The default is 'sysv'. - -'--reduce-memory-overheads' - This option reduces memory requirements at ld runtime, at the - expense of linking speed. This was introduced to select the old - O(n^2) algorithm for link map file generation, rather than the new - O(n) algorithm which uses about 40% more memory for symbol storage. - - Another effect of the switch is to set the default hash table size - to 1021, which again saves memory at the cost of lengthening the - linker's run time. This is not done however if the '--hash-size' - switch has been used. - - The '--reduce-memory-overheads' switch may be also be used to - enable other tradeoffs in future versions of the linker. - -2.1.1 Options Specific to i386 PE Targets ------------------------------------------ - -The i386 PE linker supports the '-shared' option, which causes the -output to be a dynamically linked library (DLL) instead of a normal -executable. You should name the output '*.dll' when you use this -option. In addition, the linker fully supports the standard '*.def' -files, which may be specified on the linker command line like an object -file (in fact, it should precede archives it exports symbols from, to -ensure that they get linked in, just like a normal object file). - - In addition to the options common to all targets, the i386 PE linker -support additional command line options that are specific to the i386 PE -target. Options that take values may be separated from their values by -either a space or an equals sign. - -'--add-stdcall-alias' - If given, symbols with a stdcall suffix (@NN) will be exported - as-is and also with the suffix stripped. [This option is specific - to the i386 PE targeted port of the linker] - -'--base-file FILE' - Use FILE as the name of a file in which to save the base addresses - of all the relocations needed for generating DLLs with 'dlltool'. - [This is an i386 PE specific option] - -'--dll' - Create a DLL instead of a regular executable. You may also use - '-shared' or specify a 'LIBRARY' in a given '.def' file. [This - option is specific to the i386 PE targeted port of the linker] - -'--enable-stdcall-fixup' -'--disable-stdcall-fixup' - If the link finds a symbol that it cannot resolve, it will attempt - to do "fuzzy linking" by looking for another defined symbol that - differs only in the format of the symbol name (cdecl vs stdcall) - and will resolve that symbol by linking to the match. For example, - the undefined symbol '_foo' might be linked to the function - '_foo@12', or the undefined symbol '_bar@16' might be linked to the - function '_bar'. When the linker does this, it prints a warning, - since it normally should have failed to link, but sometimes import - libraries generated from third-party dlls may need this feature to - be usable. If you specify '--enable-stdcall-fixup', this feature - is fully enabled and warnings are not printed. If you specify - '--disable-stdcall-fixup', this feature is disabled and such - mismatches are considered to be errors. [This option is specific - to the i386 PE targeted port of the linker] - -'--export-all-symbols' - If given, all global symbols in the objects used to build a DLL - will be exported by the DLL. Note that this is the default if there - otherwise wouldn't be any exported symbols. When symbols are - explicitly exported via DEF files or implicitly exported via - function attributes, the default is to not export anything else - unless this option is given. Note that the symbols 'DllMain@12', - 'DllEntryPoint@0', 'DllMainCRTStartup@12', and 'impure_ptr' will - not be automatically exported. Also, symbols imported from other - DLLs will not be re-exported, nor will symbols specifying the DLL's - internal layout such as those beginning with '_head_' or ending - with '_iname'. In addition, no symbols from 'libgcc', 'libstd++', - 'libmingw32', or 'crtX.o' will be exported. Symbols whose names - begin with '__rtti_' or '__builtin_' will not be exported, to help - with C++ DLLs. Finally, there is an extensive list of - cygwin-private symbols that are not exported (obviously, this - applies on when building DLLs for cygwin targets). These - cygwin-excludes are: '_cygwin_dll_entry@12', - '_cygwin_crt0_common@8', '_cygwin_noncygwin_dll_entry@12', - '_fmode', '_impure_ptr', 'cygwin_attach_dll', 'cygwin_premain0', - 'cygwin_premain1', 'cygwin_premain2', 'cygwin_premain3', and - 'environ'. [This option is specific to the i386 PE targeted port - of the linker] - -'--exclude-symbols SYMBOL,SYMBOL,...' - Specifies a list of symbols which should not be automatically - exported. The symbol names may be delimited by commas or colons. - [This option is specific to the i386 PE targeted port of the - linker] - -'--file-alignment' - Specify the file alignment. Sections in the file will always begin - at file offsets which are multiples of this number. This defaults - to 512. [This option is specific to the i386 PE targeted port of - the linker] - -'--heap RESERVE' -'--heap RESERVE,COMMIT' - Specify the amount of memory to reserve (and optionally commit) to - be used as heap for this program. The default is 1Mb reserved, 4K - committed. [This option is specific to the i386 PE targeted port - of the linker] - -'--image-base VALUE' - Use VALUE as the base address of your program or dll. This is the - lowest memory location that will be used when your program or dll - is loaded. To reduce the need to relocate and improve performance - of your dlls, each should have a unique base address and not - overlap any other dlls. The default is 0x400000 for executables, - and 0x10000000 for dlls. [This option is specific to the i386 PE - targeted port of the linker] - -'--kill-at' - If given, the stdcall suffixes (@NN) will be stripped from symbols - before they are exported. [This option is specific to the i386 PE - targeted port of the linker] - -'--large-address-aware' - If given, the appropriate bit in the "Characteristics" field of the - COFF header is set to indicate that this executable supports - virtual addresses greater than 2 gigabytes. This should be used in - conjunction with the /3GB or /USERVA=VALUE megabytes switch in the - "[operating systems]" section of the BOOT.INI. Otherwise, this bit - has no effect. [This option is specific to PE targeted ports of - the linker] - -'--major-image-version VALUE' - Sets the major number of the "image version". Defaults to 1. - [This option is specific to the i386 PE targeted port of the - linker] - -'--major-os-version VALUE' - Sets the major number of the "os version". Defaults to 4. [This - option is specific to the i386 PE targeted port of the linker] - -'--major-subsystem-version VALUE' - Sets the major number of the "subsystem version". Defaults to 4. - [This option is specific to the i386 PE targeted port of the - linker] - -'--minor-image-version VALUE' - Sets the minor number of the "image version". Defaults to 0. - [This option is specific to the i386 PE targeted port of the - linker] - -'--minor-os-version VALUE' - Sets the minor number of the "os version". Defaults to 0. [This - option is specific to the i386 PE targeted port of the linker] - -'--minor-subsystem-version VALUE' - Sets the minor number of the "subsystem version". Defaults to 0. - [This option is specific to the i386 PE targeted port of the - linker] - -'--output-def FILE' - The linker will create the file FILE which will contain a DEF file - corresponding to the DLL the linker is generating. This DEF file - (which should be called '*.def') may be used to create an import - library with 'dlltool' or may be used as a reference to - automatically or implicitly exported symbols. [This option is - specific to the i386 PE targeted port of the linker] - -'--out-implib FILE' - The linker will create the file FILE which will contain an import - lib corresponding to the DLL the linker is generating. This import - lib (which should be called '*.dll.a' or '*.a' may be used to link - clients against the generated DLL; this behaviour makes it possible - to skip a separate 'dlltool' import library creation step. [This - option is specific to the i386 PE targeted port of the linker] - -'--enable-auto-image-base' - Automatically choose the image base for DLLs, unless one is - specified using the '--image-base' argument. By using a hash - generated from the dllname to create unique image bases for each - DLL, in-memory collisions and relocations which can delay program - execution are avoided. [This option is specific to the i386 PE - targeted port of the linker] - -'--disable-auto-image-base' - Do not automatically generate a unique image base. If there is no - user-specified image base ('--image-base') then use the platform - default. [This option is specific to the i386 PE targeted port of - the linker] - -'--dll-search-prefix STRING' - When linking dynamically to a dll without an import library, search - for '<string><basename>.dll' in preference to 'lib<basename>.dll'. - This behaviour allows easy distinction between DLLs built for the - various "subplatforms": native, cygwin, uwin, pw, etc. For - instance, cygwin DLLs typically use '--dll-search-prefix=cyg'. - [This option is specific to the i386 PE targeted port of the - linker] - -'--enable-auto-import' - Do sophisticated linking of '_symbol' to '__imp__symbol' for DATA - imports from DLLs, and create the necessary thunking symbols when - building the import libraries with those DATA exports. Note: Use - of the 'auto-import' extension will cause the text section of the - image file to be made writable. This does not conform to the - PE-COFF format specification published by Microsoft. - - Using 'auto-import' generally will 'just work' - but sometimes you - may see this message: - - "variable '<var>' can't be auto-imported. Please read the - documentation for ld's '--enable-auto-import' for details." - - This message occurs when some (sub)expression accesses an address - ultimately given by the sum of two constants (Win32 import tables - only allow one). Instances where this may occur include accesses - to member fields of struct variables imported from a DLL, as well - as using a constant index into an array variable imported from a - DLL. Any multiword variable (arrays, structs, long long, etc) may - trigger this error condition. However, regardless of the exact - data type of the offending exported variable, ld will always detect - it, issue the warning, and exit. - - There are several ways to address this difficulty, regardless of - the data type of the exported variable: - - One way is to use -enable-runtime-pseudo-reloc switch. This leaves - the task of adjusting references in your client code for runtime - environment, so this method works only when runtime environment - supports this feature. - - A second solution is to force one of the 'constants' to be a - variable - that is, unknown and un-optimizable at compile time. - For arrays, there are two possibilities: a) make the indexee (the - array's address) a variable, or b) make the 'constant' index a - variable. Thus: - - extern type extern_array[]; - extern_array[1] --> - { volatile type *t=extern_array; t[1] } - - or - - extern type extern_array[]; - extern_array[1] --> - { volatile int t=1; extern_array[t] } - - For structs (and most other multiword data types) the only option - is to make the struct itself (or the long long, or the ...) - variable: - - extern struct s extern_struct; - extern_struct.field --> - { volatile struct s *t=&extern_struct; t->field } - - or - - extern long long extern_ll; - extern_ll --> - { volatile long long * local_ll=&extern_ll; *local_ll } - - A third method of dealing with this difficulty is to abandon - 'auto-import' for the offending symbol and mark it with - '__declspec(dllimport)'. However, in practise that requires using - compile-time #defines to indicate whether you are building a DLL, - building client code that will link to the DLL, or merely - building/linking to a static library. In making the choice between - the various methods of resolving the 'direct address with constant - offset' problem, you should consider typical real-world usage: - - Original: - --foo.h - extern int arr[]; - --foo.c - #include "foo.h" - void main(int argc, char **argv){ - printf("%d\n",arr[1]); - } - - Solution 1: - --foo.h - extern int arr[]; - --foo.c - #include "foo.h" - void main(int argc, char **argv){ - /* This workaround is for win32 and cygwin; do not "optimize" */ - volatile int *parr = arr; - printf("%d\n",parr[1]); - } - - Solution 2: - --foo.h - /* Note: auto-export is assumed (no __declspec(dllexport)) */ - #if (defined(_WIN32) || defined(__CYGWIN__)) && \ - !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) - #define FOO_IMPORT __declspec(dllimport) - #else - #define FOO_IMPORT - #endif - extern FOO_IMPORT int arr[]; - --foo.c - #include "foo.h" - void main(int argc, char **argv){ - printf("%d\n",arr[1]); - } - - A fourth way to avoid this problem is to re-code your library to - use a functional interface rather than a data interface for the - offending variables (e.g. set_foo() and get_foo() accessor - functions). [This option is specific to the i386 PE targeted port - of the linker] - -'--disable-auto-import' - Do not attempt to do sophisticated linking of '_symbol' to - '__imp__symbol' for DATA imports from DLLs. [This option is - specific to the i386 PE targeted port of the linker] - -'--enable-runtime-pseudo-reloc' - If your code contains expressions described in -enable-auto-import - section, that is, DATA imports from DLL with non-zero offset, this - switch will create a vector of 'runtime pseudo relocations' which - can be used by runtime environment to adjust references to such - data in your client code. [This option is specific to the i386 PE - targeted port of the linker] - -'--disable-runtime-pseudo-reloc' - Do not create pseudo relocations for non-zero offset DATA imports - from DLLs. This is the default. [This option is specific to the - i386 PE targeted port of the linker] - -'--enable-extra-pe-debug' - Show additional debug info related to auto-import symbol thunking. - [This option is specific to the i386 PE targeted port of the - linker] - -'--section-alignment' - Sets the section alignment. Sections in memory will always begin - at addresses which are a multiple of this number. Defaults to - 0x1000. [This option is specific to the i386 PE targeted port of - the linker] - -'--stack RESERVE' -'--stack RESERVE,COMMIT' - Specify the amount of memory to reserve (and optionally commit) to - be used as stack for this program. The default is 2Mb reserved, 4K - committed. [This option is specific to the i386 PE targeted port - of the linker] - -'--subsystem WHICH' -'--subsystem WHICH:MAJOR' -'--subsystem WHICH:MAJOR.MINOR' - Specifies the subsystem under which your program will execute. The - legal values for WHICH are 'native', 'windows', 'console', 'posix', - and 'xbox'. You may optionally set the subsystem version also. - Numeric values are also accepted for WHICH. [This option is - specific to the i386 PE targeted port of the linker] - -2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets ------------------------------------------------------------- - -The 68HC11 and 68HC12 linkers support specific options to control the -memory bank switching mapping and trampoline code generation. - -'--no-trampoline' - This option disables the generation of trampoline. By default a - trampoline is generated for each far function which is called using - a 'jsr' instruction (this happens when a pointer to a far function - is taken). - -'--bank-window NAME' - This option indicates to the linker the name of the memory region - in the 'MEMORY' specification that describes the memory bank - window. The definition of such region is then used by the linker - to compute paging and addresses within the memory window. - -2.2 Environment Variables -========================= - -You can change the behaviour of 'ld' with the environment variables -'GNUTARGET', 'LDEMULATION' and 'COLLECT_NO_DEMANGLE'. - - '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. - - 'LDEMULATION' determines the default emulation if you don't use the -'-m' option. The emulation can affect various aspects of linker -behaviour, particularly the default linker script. You can list the -available emulations with the '--verbose' or '-V' options. If the '-m' -option is not used, and the 'LDEMULATION' environment variable is not -defined, the default emulation depends upon how the linker was -configured. - - Normally, the linker will default to demangling symbols. However, if -'COLLECT_NO_DEMANGLE' is set in the environment, then it will default to -not demangling symbols. This environment variable is used in a similar -fashion by the 'gcc' linker wrapper program. The default may be -overridden by the '--demangle' and '--no-demangle' options. - -3 Linker Scripts -**************** - -Every link is controlled by a "linker script". This script is written -in the linker command language. - - The main purpose of the linker script is to describe how the sections -in the input files should be mapped into the output file, and to control -the memory layout of the output file. Most linker scripts do nothing -more than this. However, when necessary, the linker script can also -direct the linker to perform many other operations, using the commands -described below. - - The linker always uses a linker script. If you do not supply one -yourself, the linker will use a default script that is compiled into the -linker executable. You can use the '--verbose' command line option to -display the default linker script. Certain command line options, such -as '-r' or '-N', will affect the default linker script. - - You may supply your own linker script by using the '-T' command line -option. When you do this, your linker script will replace the default -linker script. - - You may also use linker scripts implicitly by naming them as input -files to the linker, as though they were files to be linked. *Note -Implicit Linker Scripts::. - -3.1 Basic Linker Script Concepts -================================ - -We need to define some basic concepts and vocabulary in order to -describe the linker script language. - - The linker combines input files into a single output file. The -output file and each input file are in a special data format known as an -"object file format". Each file is called an "object file". The output -file is often called an "executable", but for our purposes we will also -call it an object file. Each object file has, among other things, a -list of "sections". We sometimes refer to a section in an input file as -an "input section"; similarly, a section in the output file is an -"output section". - - Each section in an object file has a name and a size. Most sections -also have an associated block of data, known as the "section contents". -A section may be marked as "loadable", which mean that the contents -should be loaded into memory when the output file is run. A section -with no contents may be "allocatable", which means that an area in -memory should be set aside, but nothing in particular should be loaded -there (in some cases this memory must be zeroed out). A section which -is neither loadable nor allocatable typically contains some sort of -debugging information. - - Every loadable or allocatable output section has two addresses. The -first is the "VMA", or virtual memory address. This is the address the -section will have when the output file is run. The second is the "LMA", -or load memory address. This is the address at which the section will -be loaded. In most cases the two addresses will be the same. An -example of when they might be different is when a data section is loaded -into ROM, and then copied into RAM when the program starts up (this -technique is often used to initialize global variables in a ROM based -system). In this case the ROM address would be the LMA, and the RAM -address would be the VMA. - - You can see the sections in an object file by using the 'objdump' -program with the '-h' option. - - Every object file also has a list of "symbols", known as the "symbol -table". A symbol may be defined or undefined. Each symbol has a name, -and each defined symbol has an address, among other information. If you -compile a C or C++ program into an object file, you will get a defined -symbol for every defined function and global or static variable. Every -undefined function or global variable which is referenced in the input -file will become an undefined symbol. - - You can see the symbols in an object file by using the 'nm' program, -or by using the 'objdump' program with the '-t' option. - -3.2 Linker Script Format -======================== - -Linker scripts are text files. - - You write a linker script as a series of commands. Each command is -either a keyword, possibly followed by arguments, or an assignment to a -symbol. You may separate commands using semicolons. Whitespace is -generally ignored. - - Strings such as file or format names can normally be entered -directly. If the file name contains a character such as a comma which -would otherwise serve to separate file names, you may put the file name -in double quotes. There is no way to use a double quote character in a -file name. - - You may include comments in linker scripts just as in C, delimited by -'/*' and '*/'. As in C, comments are syntactically equivalent to -whitespace. - -3.3 Simple Linker Script Example -================================ - -Many linker scripts are fairly simple. - - The simplest possible linker script has just one command: 'SECTIONS'. -You use the 'SECTIONS' command to describe the memory layout of the -output file. - - The 'SECTIONS' command is a powerful command. Here we will describe -a simple use of it. Let's assume your program consists only of code, -initialized data, and uninitialized data. These will be in the '.text', -'.data', and '.bss' sections, respectively. Let's assume further that -these are the only sections which appear in your input files. - - For this example, let's say that the code should be loaded at address -0x10000, and that the data should start at address 0x8000000. Here is a -linker script which will do that: - SECTIONS - { - . = 0x10000; - .text : { *(.text) } - . = 0x8000000; - .data : { *(.data) } - .bss : { *(.bss) } - } - - You write the 'SECTIONS' command as the keyword 'SECTIONS', followed -by a series of symbol assignments and output section descriptions -enclosed in curly braces. - - The first line inside the 'SECTIONS' command of the above example -sets the value of the special symbol '.', which is the location counter. -If you do not specify the address of an output section in some other way -(other ways are described later), the address is set from the current -value of the location counter. The location counter is then incremented -by the size of the output section. At the start of the 'SECTIONS' -command, the location counter has the value '0'. - - The second line defines an output section, '.text'. The colon is -required syntax which may be ignored for now. Within the curly braces -after the output section name, you list the names of the input sections -which should be placed into this output section. The '*' is a wildcard -which matches any file name. The expression '*(.text)' means all -'.text' input sections in all input files. - - Since the location counter is '0x10000' when the output section -'.text' is defined, the linker will set the address of the '.text' -section in the output file to be '0x10000'. - - The remaining lines define the '.data' and '.bss' sections in the -output file. The linker will place the '.data' output section at -address '0x8000000'. After the linker places the '.data' output -section, the value of the location counter will be '0x8000000' plus the -size of the '.data' output section. The effect is that the linker will -place the '.bss' output section immediately after the '.data' output -section in memory. - - The linker will ensure that each output section has the required -alignment, by increasing the location counter if necessary. In this -example, the specified addresses for the '.text' and '.data' sections -will probably satisfy any alignment constraints, but the linker may have -to create a small gap between the '.data' and '.bss' sections. - - That's it! That's a simple and complete linker script. - -3.4 Simple Linker Script Commands -================================= - -In this section we describe the simple linker script commands. - -3.4.1 Setting the Entry Point ------------------------------ - -The first instruction to execute in a program is called the "entry -point". You can use the 'ENTRY' linker script command to set the entry -point. The argument is a symbol name: - ENTRY(SYMBOL) - - There are several ways to set the entry point. The linker will set -the entry point by trying each of the following methods in order, and -stopping when one of them succeeds: - * the '-e' ENTRY command-line option; - * the 'ENTRY(SYMBOL)' command in a linker script; - * the value of the symbol 'start', if defined; - * the address of the first byte of the '.text' section, if present; - * The address '0'. - -3.4.2 Commands Dealing with Files ---------------------------------- - -Several linker script commands deal with files. - -'INCLUDE FILENAME' - Include the linker script FILENAME at this point. The file will be - searched for in the current directory, and in any directory - specified with the '-L' option. You can nest calls to 'INCLUDE' up - to 10 levels deep. - -'INPUT(FILE, FILE, ...)' -'INPUT(FILE FILE ...)' - The 'INPUT' command directs the linker to include the named files - in the link, as though they were named on the command line. - - For example, if you always want to include 'subr.o' any time you do - a link, but you can't be bothered to put it on every link command - line, then you can put 'INPUT (subr.o)' in your linker script. - - In fact, if you like, you can list all of your input files in the - linker script, and then invoke the linker with nothing but a '-T' - option. - - In case a "sysroot prefix" is configured, and the filename starts - with the '/' character, and the script being processed was located - inside the "sysroot prefix", the filename will be looked for in the - "sysroot prefix". Otherwise, the linker will try to open the file - in the current directory. If it is not found, the linker will - search through the archive library search path. See the - description of '-L' in *note Command Line Options: Options. - - If you use 'INPUT (-lFILE)', 'ld' will transform the name to - 'libFILE.a', as with the command line argument '-l'. - - When you use the 'INPUT' command in an implicit linker script, the - files will be included in the link at the point at which the linker - script file is included. This can affect archive searching. - -'GROUP(FILE, FILE, ...)' -'GROUP(FILE FILE ...)' - The 'GROUP' command is like 'INPUT', except that the named files - should all be archives, and they are searched repeatedly until no - new undefined references are created. See the description of '-(' - in *note Command Line Options: Options. - -'AS_NEEDED(FILE, FILE, ...)' -'AS_NEEDED(FILE FILE ...)' - This construct can appear only inside of the 'INPUT' or 'GROUP' - commands, among other filenames. The files listed will be handled - as if they appear directly in the 'INPUT' or 'GROUP' commands, with - the exception of ELF shared libraries, that will be added only when - they are actually needed. This construct essentially enables - '--as-needed' option for all the files listed inside of it and - restores previous '--as-needed' resp. '--no-as-needed' setting - afterwards. - -'OUTPUT(FILENAME)' - The 'OUTPUT' command names the output file. Using - 'OUTPUT(FILENAME)' in the linker script is exactly like using '-o - FILENAME' on the command line (*note Command Line Options: - Options.). If both are used, the command line option takes - precedence. - - You can use the 'OUTPUT' command to define a default name for the - output file other than the usual default of 'a.out'. - -'SEARCH_DIR(PATH)' - The 'SEARCH_DIR' command adds PATH to the list of paths where 'ld' - looks for archive libraries. Using 'SEARCH_DIR(PATH)' is exactly - like using '-L PATH' on the command line (*note Command Line - Options: Options.). If both are used, then the linker will search - both paths. Paths specified using the command line option are - searched first. - -'STARTUP(FILENAME)' - The 'STARTUP' command is just like the 'INPUT' command, except that - FILENAME will become the first input file to be linked, as though - it were specified first on the command line. This may be useful - when using a system in which the entry point is always the start of - the first file. - -3.4.3 Commands Dealing with Object File Formats ------------------------------------------------ - -A couple of linker script commands deal with object file formats. - -'OUTPUT_FORMAT(BFDNAME)' -'OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)' - The 'OUTPUT_FORMAT' command names the BFD format to use for the - output file (*note BFD::). Using 'OUTPUT_FORMAT(BFDNAME)' is - exactly like using '--oformat BFDNAME' on the command line (*note - Command Line Options: Options.). If both are used, the command - line option takes precedence. - - You can use 'OUTPUT_FORMAT' with three arguments to use different - formats based on the '-EB' and '-EL' command line options. This - permits the linker script to set the output format based on the - desired endianness. - - If neither '-EB' nor '-EL' are used, then the output format will be - the first argument, DEFAULT. If '-EB' is used, the output format - will be the second argument, BIG. If '-EL' is used, the output - format will be the third argument, LITTLE. - - For example, the default linker script for the MIPS ELF target uses - this command: - OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) - This says that the default format for the output file is - 'elf32-bigmips', but if the user uses the '-EL' command line - option, the output file will be created in the 'elf32-littlemips' - format. - -'TARGET(BFDNAME)' - The 'TARGET' command names the BFD format to use when reading input - files. It affects subsequent 'INPUT' and 'GROUP' commands. This - command is like using '-b BFDNAME' on the command line (*note - Command Line Options: Options.). If the 'TARGET' command is used - but 'OUTPUT_FORMAT' is not, then the last 'TARGET' command is also - used to set the format for the output file. *Note BFD::. - -3.4.4 Other Linker Script Commands ----------------------------------- - -There are a few other linker scripts commands. - -'ASSERT(EXP, MESSAGE)' - Ensure that EXP is non-zero. If it is zero, then exit the linker - with an error code, and print MESSAGE. - -'EXTERN(SYMBOL 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. You may list several SYMBOLs for - each 'EXTERN', and you may use 'EXTERN' multiple times. This - command has the same effect as the '-u' command-line option. - -'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'). - -'INHIBIT_COMMON_ALLOCATION' - This command has the same effect as the '--no-define-common' - command-line option: to make 'ld' omit the assignment of addresses - to common symbols even for a non-relocatable output file. - -'NOCROSSREFS(SECTION SECTION ...)' - This command may be used to tell 'ld' to issue an error about any - references among certain output sections. - - In certain types of programs, particularly on embedded systems when - using overlays, when one section is loaded into memory, another - section will not be. Any direct references between the two - sections would be errors. For example, it would be an error if - code in one section called a function defined in the other section. - - The 'NOCROSSREFS' command takes a list of output section names. If - 'ld' detects any cross references between the sections, it reports - an error and returns a non-zero exit status. Note that the - 'NOCROSSREFS' command uses output section names, not input section - names. - -'OUTPUT_ARCH(BFDARCH)' - Specify a particular output machine architecture. The argument is - one of the names used by the BFD library (*note BFD::). You can - see the architecture of an object file by using the 'objdump' - program with the '-f' option. - -3.5 Assigning Values to Symbols -=============================== - -You may assign a value to a symbol in a linker script. This will define -the symbol and place it into the symbol table with a global scope. - -3.5.1 Simple Assignments ------------------------- - -You may assign to a symbol using any of the C assignment operators: - -'SYMBOL = EXPRESSION ;' -'SYMBOL += EXPRESSION ;' -'SYMBOL -= EXPRESSION ;' -'SYMBOL *= EXPRESSION ;' -'SYMBOL /= EXPRESSION ;' -'SYMBOL <<= EXPRESSION ;' -'SYMBOL >>= EXPRESSION ;' -'SYMBOL &= EXPRESSION ;' -'SYMBOL |= EXPRESSION ;' - - The first case will define SYMBOL to the value of EXPRESSION. In the -other cases, SYMBOL must already be defined, and the value will be -adjusted accordingly. - - The special symbol name '.' indicates the location counter. You may -only use this within a 'SECTIONS' command. *Note Location Counter::. - - The semicolon after EXPRESSION is required. - - Expressions are defined below; see *note Expressions::. - - You may write symbol assignments as commands in their own right, or -as statements within a 'SECTIONS' command, or as part of an output -section description in a 'SECTIONS' command. - - The section of the symbol will be set from the section of the -expression; for more information, see *note Expression Section::. - - Here is an example showing the three different places that symbol -assignments may be used: - - floating_point = 0; - SECTIONS - { - .text : - { - *(.text) - _etext = .; - } - _bdata = (. + 3) & ~ 3; - .data : { *(.data) } - } -In this example, the symbol 'floating_point' will be defined as zero. -The symbol '_etext' will be defined as the address following the last -'.text' input section. The symbol '_bdata' will be defined as the -address following the '.text' output section aligned upward to a 4 byte -boundary. - -3.5.2 PROVIDE -------------- - -In some cases, it is desirable for a linker script to define a symbol -only if it is referenced and is not defined by any object included in -the link. For example, traditional linkers defined the symbol 'etext'. -However, ANSI C requires that the user be able to use 'etext' as a -function name without encountering an error. The 'PROVIDE' keyword may -be used to define a symbol, such as 'etext', only if it is referenced -but not defined. The syntax is 'PROVIDE(SYMBOL = EXPRESSION)'. - - Here is an example of using 'PROVIDE' to define 'etext': - SECTIONS - { - .text : - { - *(.text) - _etext = .; - PROVIDE(etext = .); - } - } - - In this example, if the program defines '_etext' (with a leading -underscore), the linker will give a multiple definition error. If, on -the other hand, the program defines 'etext' (with no leading -underscore), the linker will silently use the definition in the program. -If the program references 'etext' but does not define it, the linker -will use the definition in the linker script. - -3.5.3 PROVIDE_HIDDEN --------------------- - -Similar to 'PROVIDE'. For ELF targeted ports, the symbol will be hidden -and won't be exported. - -3.5.4 Source Code Reference ---------------------------- - -Accessing a linker script defined variable from source code is not -intuitive. In particular a linker script symbol is not equivalent to a -variable declaration in a high level language, it is instead a symbol -that does not have a value. - - Before going further, it is important to note that compilers often -transform names in the source code into different names when they are -stored in the symbol table. For example, Fortran compilers commonly -prepend or append an underscore, and C++ performs extensive 'name -mangling'. Therefore there might be a discrepancy between the name of a -variable as it is used in source code and the name of the same variable -as it is defined in a linker script. For example in C a linker script -variable might be referred to as: - - extern int foo; - - But in the linker script it might be defined as: - - _foo = 1000; - - In the remaining examples however it is assumed that no name -transformation has taken place. - - When a symbol is declared in a high level language such as C, two -things happen. The first is that the compiler reserves enough space in -the program's memory to hold the _value_ of the symbol. The second is -that the compiler creates an entry in the program's symbol table which -holds the symbol's _address_. ie the symbol table contains the address -of the block of memory holding the symbol's value. So for example the -following C declaration, at file scope: - - int foo = 1000; - - creates a entry called 'foo' in the symbol table. This entry holds -the address of an 'int' sized block of memory where the number 1000 is -initially stored. - - When a program references a symbol the compiler generates code that -first accesses the symbol table to find the address of the symbol's -memory block and then code to read the value from that memory block. -So: - - foo = 1; - - looks up the symbol 'foo' in the symbol table, gets the address -associated with this symbol and then writes the value 1 into that -address. Whereas: - - int * a = & foo; - - looks up the symbol 'foo' in the symbol table, gets it address and -then copies this address into the block of memory associated with the -variable 'a'. - - Linker scripts symbol declarations, by contrast, create an entry in -the symbol table but do not assign any memory to them. Thus they are an -address without a value. So for example the linker script definition: - - foo = 1000; - - creates an entry in the symbol table called 'foo' which holds the -address of memory location 1000, but nothing special is stored at -address 1000. This means that you cannot access the _value_ of a linker -script defined symbol - it has no value - all you can do is access the -_address_ of a linker script defined symbol. - - Hence when you are using a linker script defined symbol in source -code you should always take the address of the symbol, and never attempt -to use its value. For example suppose you want to copy the contents of -a section of memory called .ROM into a section called .FLASH and the -linker script contains these declarations: - - start_of_ROM = .ROM; - end_of_ROM = .ROM + sizeof (.ROM) - 1; - start_of_FLASH = .FLASH; - - Then the C source code to perform the copy would be: - - extern char start_of_ROM, end_of_ROM, start_of_FLASH; - - memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); - - Note the use of the '&' operators. These are correct. - -3.6 SECTIONS Command -==================== - -The 'SECTIONS' command tells the linker how to map input sections into -output sections, and how to place the output sections in memory. - - The format of the 'SECTIONS' command is: - SECTIONS - { - SECTIONS-COMMAND - SECTIONS-COMMAND - ... - } - - Each SECTIONS-COMMAND may of be one of the following: - - * an 'ENTRY' command (*note Entry command: Entry Point.) - * a symbol assignment (*note Assignments::) - * an output section description - * an overlay description - - The 'ENTRY' command and symbol assignments are permitted inside the -'SECTIONS' command for convenience in using the location counter in -those commands. This can also make the linker script easier to -understand because you can use those commands at meaningful points in -the layout of the output file. - - Output section descriptions and overlay descriptions are described -below. - - If you do not use a 'SECTIONS' command in your linker script, the -linker will place 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. The first section will be at address zero. - -3.6.1 Output Section Description --------------------------------- - -The full description of an output section looks like this: - SECTION [ADDRESS] [(TYPE)] : - [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)] - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP] - - Most output sections do not use most of the optional section -attributes. - - The whitespace around SECTION is required, so that the section name -is unambiguous. The colon and the curly braces are also required. The -line breaks and other white space are optional. - - Each OUTPUT-SECTION-COMMAND may be one of the following: - - * a symbol assignment (*note Assignments::) - * an input section description (*note Input Section::) - * data values to include directly (*note Output Section Data::) - * a special output section keyword (*note Output Section Keywords::) - -3.6.2 Output Section Name -------------------------- - -The name of the output section is SECTION. SECTION 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 a name which contains any -unusual characters such as commas must be quoted. - - The output section name '/DISCARD/' is special; *note Output Section -Discarding::. - -3.6.3 Output Section Address ----------------------------- - -The ADDRESS is an expression for the VMA (the virtual memory address) of -the output section. If you do not provide ADDRESS, the linker will set -it based on REGION if present, or otherwise based on the current value -of the location counter. - - If you provide ADDRESS, the address of the output section will be set -to precisely that. If you provide neither ADDRESS nor REGION, then the -address of the output section will be set to the current value of the -location counter aligned to the alignment requirements of the output -section. The alignment requirement of the output section is the -strictest alignment of any input section contained within the output -section. - - For example, - .text . : { *(.text) } -and - .text : { *(.text) } -are subtly different. The first will set the address of the '.text' -output section to the current value of the location counter. The second -will set it to the current value of the location counter aligned to the -strictest alignment of a '.text' input section. - - The ADDRESS may be an arbitrary expression; *note Expressions::. For -example, if you want to align the section on a 0x10 byte boundary, so -that the lowest four bits of the section address are zero, you could do -something like this: - .text ALIGN(0x10) : { *(.text) } -This works because 'ALIGN' returns the current location counter aligned -upward to the specified value. - - Specifying ADDRESS for a section will change the value of the -location counter. - -3.6.4 Input Section Description -------------------------------- - -The most common output section command is an input section description. - - The input section description is the most basic linker script -operation. You use output sections to tell the linker how to lay out -your program in memory. You use input section descriptions to tell the -linker how to map the input files into your memory layout. - -3.6.4.1 Input Section Basics -............................ - -An input section description consists of a file name optionally followed -by a list of section names in parentheses. - - The file name and the section name may be wildcard patterns, which we -describe further below (*note Input Section Wildcards::). - - The most common input section description is to include all input -sections with a particular name in the output section. For example, to -include all input '.text' sections, you would write: - *(.text) -Here the '*' is a wildcard which matches any file name. To exclude a -list of files from matching the file name wildcard, EXCLUDE_FILE may be -used to match all files except the ones specified in the EXCLUDE_FILE -list. For example: - (*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)) - will cause all .ctors sections from all files except 'crtend.o' and -'otherfile.o' to be included. - - There are two ways to include more than one section: - *(.text .rdata) - *(.text) *(.rdata) -The difference between these is the order in which the '.text' and -'.rdata' input sections will appear in the output section. In the first -example, they will be intermingled, appearing in the same order as they -are found in the linker input. In the second example, all '.text' input -sections will appear first, followed by all '.rdata' input sections. - - You can specify a file name to include sections from a particular -file. You would do this if one or more of your files contain special -data that needs to be at a particular location in memory. For example: - data.o(.data) - - If you use a file name without a list of sections, then all sections -in the input file will be included in the output section. This is not -commonly done, but it may by useful on occasion. For example: - data.o - - When you use a file name which does not contain any wild card -characters, the linker will first see if you also specified the file -name on the linker command line or in an 'INPUT' command. If you did -not, the linker will attempt to open the file as an input file, as -though it appeared on the command line. Note that this differs from an -'INPUT' command, because the linker will not search for the file in the -archive search path. - -3.6.4.2 Input Section Wildcard Patterns -....................................... - -In an input section description, either the file name or the section -name or both may be wildcard patterns. - - The file name of '*' seen in many examples is a simple wildcard -pattern for the file name. - - The wildcard patterns are like those used by the Unix shell. - -'*' - matches any number of characters -'?' - matches any single character -'[CHARS]' - matches a single instance of any of the CHARS; the '-' character - may be used to specify a range of characters, as in '[a-z]' to - match any lower case letter -'\' - quotes the following character - - When a file name is matched with a wildcard, the wildcard characters -will not match a '/' character (used to separate directory names on -Unix). A pattern consisting of a single '*' character is an exception; -it will always match any file name, whether it contains a '/' or not. -In a section name, the wildcard characters will match a '/' character. - - File name wildcard patterns only match files which are explicitly -specified on the command line or in an 'INPUT' command. The linker does -not search directories to expand wildcards. - - If a file name matches more than one wildcard pattern, or if a file -name appears explicitly and is also matched by a wildcard pattern, the -linker will use the first match in the linker script. For example, this -sequence of input section descriptions is probably in error, because the -'data.o' rule will not be used: - .data : { *(.data) } - .data1 : { data.o(.data) } - - Normally, the linker will place files and sections matched by -wildcards in the order in which they are seen during the link. You can -change this by using the 'SORT_BY_NAME' keyword, which appears before a -wildcard pattern in parentheses (e.g., 'SORT_BY_NAME(.text*)'). When -the 'SORT_BY_NAME' keyword is used, the linker will sort the files or -sections into ascending order by name before placing them in the output -file. - - 'SORT_BY_ALIGNMENT' is very similar to 'SORT_BY_NAME'. The -difference is 'SORT_BY_ALIGNMENT' will sort sections into ascending -order by alignment before placing them in the output file. - - 'SORT' is an alias for 'SORT_BY_NAME'. - - When there are nested section sorting commands in linker script, -there can be at most 1 level of nesting for section sorting commands. - - 1. 'SORT_BY_NAME' ('SORT_BY_ALIGNMENT' (wildcard section pattern)). - It will sort the input sections by name first, then by alignment if - 2 sections have the same name. - 2. 'SORT_BY_ALIGNMENT' ('SORT_BY_NAME' (wildcard section pattern)). - It will sort the input sections by alignment first, then by name if - 2 sections have the same alignment. - 3. 'SORT_BY_NAME' ('SORT_BY_NAME' (wildcard section pattern)) is - treated the same as 'SORT_BY_NAME' (wildcard section pattern). - 4. 'SORT_BY_ALIGNMENT' ('SORT_BY_ALIGNMENT' (wildcard section - pattern)) is treated the same as 'SORT_BY_ALIGNMENT' (wildcard - section pattern). - 5. All other nested section sorting commands are invalid. - - When both command line section sorting option and linker script -section sorting command are used, section sorting command always takes -precedence over the command line option. - - If the section sorting command in linker script isn't nested, the -command line option will make the section sorting command to be treated -as nested sorting command. - - 1. 'SORT_BY_NAME' (wildcard section pattern ) with '--sort-sections - alignment' is equivalent to 'SORT_BY_NAME' ('SORT_BY_ALIGNMENT' - (wildcard section pattern)). - 2. 'SORT_BY_ALIGNMENT' (wildcard section pattern) with '--sort-section - name' is equivalent to 'SORT_BY_ALIGNMENT' ('SORT_BY_NAME' - (wildcard section pattern)). - - If the section sorting command in linker script is nested, the -command line option will be ignored. - - If you ever get confused about where input sections are going, use -the '-M' linker option to generate a map file. The map file shows -precisely how input sections are mapped to output sections. - - This example shows how wildcard patterns might be used to partition -files. This linker script directs the linker to place all '.text' -sections in '.text' and all '.bss' sections in '.bss'. The linker will -place the '.data' section from all files beginning with an upper case -character in '.DATA'; for all other files, the linker will place the -'.data' section in '.data'. - SECTIONS { - .text : { *(.text) } - .DATA : { [A-Z]*(.data) } - .data : { *(.data) } - .bss : { *(.bss) } - } - -3.6.4.3 Input Section for Common Symbols -........................................ - -A special notation is needed for common symbols, because in many object -file formats common symbols do not have a particular input section. The -linker treats common symbols as though they are in an input section -named 'COMMON'. - - You may use file names with the 'COMMON' section just as with any -other input sections. You can use this to place common symbols from a -particular input file in one section while common symbols from other -input files are placed in another section. - - In most cases, common symbols in input files will be placed in the -'.bss' section in the output file. For example: - .bss { *(.bss) *(COMMON) } - - Some object file formats have more than one type of common symbol. -For example, the MIPS ELF object file format distinguishes standard -common symbols and small common symbols. In this case, the linker will -use a different special section name for other types of common symbols. -In the case of MIPS ELF, the linker uses 'COMMON' for standard common -symbols and '.scommon' for small common symbols. This permits you to -map the different types of common symbols into memory at different -locations. - - You will sometimes see '[COMMON]' in old linker scripts. This -notation is now considered obsolete. It is equivalent to '*(COMMON)'. - -3.6.4.4 Input Section and Garbage Collection -............................................ - -When link-time garbage collection is in use ('--gc-sections'), it is -often useful to mark sections that should not be eliminated. This is -accomplished by surrounding an input section's wildcard entry with -'KEEP()', as in 'KEEP(*(.init))' or 'KEEP(SORT_BY_NAME(*)(.ctors))'. - -3.6.4.5 Input Section Example -............................. - -The following example is a complete linker script. It tells the linker -to read all of the sections from file 'all.o' and place 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) - } - } - -3.6.5 Output Section Data -------------------------- - -You can include explicit bytes of data in an output section by using -'BYTE', 'SHORT', 'LONG', 'QUAD', or 'SQUAD' as an output section -command. Each keyword is followed by an expression in parentheses -providing the value to store (*note Expressions::). The value of the -expression is stored at the current value of the location counter. - - The 'BYTE', 'SHORT', 'LONG', and 'QUAD' commands store one, two, -four, and eight bytes (respectively). After storing the bytes, the -location counter is incremented by the number of bytes stored. - - For example, this will store the byte 1 followed by the four byte -value of the symbol 'addr': - BYTE(1) - LONG(addr) - - When using a 64 bit host or target, 'QUAD' and 'SQUAD' are the same; -they both store an 8 byte, or 64 bit, value. When both host and target -are 32 bits, an expression is computed as 32 bits. In this case 'QUAD' -stores a 32 bit value zero extended to 64 bits, and 'SQUAD' stores a 32 -bit value sign extended to 64 bits. - - If the object file format of the output file has an explicit -endianness, which is the normal case, the value will be stored in that -endianness. When the object file format does not have an explicit -endianness, as is true of, for example, S-records, the value will be -stored in the endianness of the first input object file. - - Note--these commands only work inside a section description and not -between them, so the following will produce an error from the linker: - SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } - whereas this will work: - SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } - - You may use the 'FILL' command to set the fill pattern for the -current section. It is followed by an expression in parentheses. Any -otherwise unspecified regions of memory within the section (for example, -gaps left due to the required alignment of input sections) are filled -with the value of the expression, repeated as necessary. A 'FILL' -statement covers memory locations after the point at which 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. - - This example shows how to fill unspecified regions of memory with the -value '0x90': - FILL(0x90909090) - - The 'FILL' command is similar to the '=FILLEXP' output section -attribute, but it only affects the part of the section following the -'FILL' command, rather than the entire section. If both are used, the -'FILL' command takes precedence. *Note Output Section Fill::, for -details on the fill expression. - -3.6.6 Output Section Keywords ------------------------------ - -There are a couple of keywords which can appear as output section -commands. - -'CREATE_OBJECT_SYMBOLS' - The command tells the linker to create a symbol for each input - file. The name of each symbol will be the name of the - corresponding input file. The section of each symbol will be the - output section in which the 'CREATE_OBJECT_SYMBOLS' command - appears. - - This is conventional for the a.out object file format. It is not - normally used for any other object file format. - -'CONSTRUCTORS' - When linking using the a.out object file format, the linker uses an - unusual set construct to support C++ global constructors and - destructors. When linking object file formats which do not support - arbitrary sections, such as ECOFF and XCOFF, the linker will - automatically recognize C++ global constructors and destructors by - name. For these object file formats, the 'CONSTRUCTORS' command - tells the linker to place constructor information in the output - section where the 'CONSTRUCTORS' command appears. The - 'CONSTRUCTORS' command is ignored for other object file formats. - - The symbol '__CTOR_LIST__' marks the start of the global - constructors, and the symbol '__CTOR_END__' marks the end. - Similarly, '__DTOR_LIST__' and '__DTOR_END__' mark the start and - end of the global destructors. The first word in the list is the - number of entries, followed by the address of each constructor or - destructor, followed by a zero word. The compiler must arrange to - actually run the code. For these object file formats GNU C++ - normally calls constructors from a subroutine '__main'; a call to - '__main' is automatically inserted into the startup code for - 'main'. GNU C++ normally runs destructors either by using - 'atexit', or directly from the function 'exit'. - - For object file formats such as 'COFF' or 'ELF' which support - arbitrary section names, GNU C++ will normally arrange to put the - addresses of global constructors and destructors into the '.ctors' - and '.dtors' sections. Placing the following sequence into your - linker script will build the sort of table which the GNU C++ - runtime code expects to see. - - __CTOR_LIST__ = .; - LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) - *(.ctors) - LONG(0) - __CTOR_END__ = .; - __DTOR_LIST__ = .; - LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) - *(.dtors) - LONG(0) - __DTOR_END__ = .; - - If you are using the GNU C++ support for initialization priority, - which provides some control over the order in which global - constructors are run, you must sort the constructors at link time - to ensure that they are executed in the correct order. When using - the 'CONSTRUCTORS' command, use 'SORT_BY_NAME(CONSTRUCTORS)' - instead. When using the '.ctors' and '.dtors' sections, use - '*(SORT_BY_NAME(.ctors))' and '*(SORT_BY_NAME(.dtors))' instead of - just '*(.ctors)' and '*(.dtors)'. - - Normally the compiler and linker will handle these issues - automatically, and you will not need to concern yourself with them. - However, you may need to consider this if you are using C++ and - writing your own linker scripts. - -3.6.7 Output Section Discarding -------------------------------- - -The linker will not create output sections with no contents. This is -for convenience when referring to input sections that may or may not be -present in any of the input files. For example: - .foo : { *(.foo) } -will only create a '.foo' section in the output file if there is a -'.foo' section in at least one input file, and if the input sections are -not all empty. Other link script directives that allocate space in an -output section will also create the output section. - - The linker will ignore address assignments (*note Output Section -Address::) on discarded output sections, except when the linker script -defines symbols in the output section. In that case the linker will -obey the address assignments, possibly advancing dot even though the -section is discarded. - - The special output section name '/DISCARD/' may be used to discard -input sections. Any input sections which are assigned to an output -section named '/DISCARD/' are not included in the output file. - -3.6.8 Output Section Attributes -------------------------------- - -We showed above that the full description of an output section looked -like this: - SECTION [ADDRESS] [(TYPE)] : - [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)] - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP] - We've already described SECTION, ADDRESS, and OUTPUT-SECTION-COMMAND. -In this section we will describe the remaining section attributes. - -3.6.8.1 Output Section Type -........................... - -Each output section may have a type. The type is a keyword in -parentheses. The following types are defined: - -'NOLOAD' - The section should be marked as not loadable, so that it will not - be loaded into memory when the program is run. -'DSECT' -'COPY' -'INFO' -'OVERLAY' - These type names are supported for backward compatibility, and are - rarely used. They all have the same effect: the section should be - marked as not allocatable, so that no memory is allocated for the - section when the program is run. - - The linker normally sets the attributes of an output section based on -the input sections which map into it. You can override this by using -the section type. For example, in the script sample below, the 'ROM' -section is addressed at memory location '0' and does not need to be -loaded when the program is run. The contents of the 'ROM' section will -appear in the linker output file as usual. - SECTIONS { - ROM 0 (NOLOAD) : { ... } - ... - } - -3.6.8.2 Output Section LMA -.......................... - -Every section has a virtual address (VMA) and a load address (LMA); see -*note Basic Script Concepts::. The address expression which may appear -in an output section description sets the VMA (*note Output Section -Address::). - - The expression LMA that follows the 'AT' keyword specifies the load -address of the section. - - Alternatively, with 'AT>LMA_REGION' expression, you may specify a -memory region for the section's load address. *Note MEMORY::. Note -that if the section has not had a VMA assigned to it then the linker -will use the LMA_REGION as the VMA region as well. - - If neither 'AT' nor 'AT>' is specified for an allocatable section, -the linker will set the LMA such that the difference between VMA and LMA -for the section is the same as the preceding output section in the same -region. If there is no preceding output section or the section is not -allocatable, the linker will set the LMA equal to the VMA. *Note Output -Section Region::. - - This feature is designed to make it easy to build a ROM image. For -example, the following linker script creates three output sections: one -called '.text', which starts at '0x1000', one called '.mdata', which is -loaded at the end of the '.text' section even though its VMA is -'0x2000', and one called '.bss' to hold uninitialized data at address -'0x3000'. The symbol '_data' is defined with the value '0x2000', which -shows that the location counter holds the VMA value, not the LMA value. - - SECTIONS - { - .text 0x1000 : { *(.text) _etext = . ; } - .mdata 0x2000 : - AT ( ADDR (.text) + SIZEOF (.text) ) - { _data = . ; *(.data); _edata = . ; } - .bss 0x3000 : - { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} - } - - The run-time initialization code for use with a program generated -with this linker script would include something like the following, to -copy the initialized data from the ROM image to its runtime address. -Notice how this code takes advantage of the symbols defined by the -linker script. - - extern char _etext, _data, _edata, _bstart, _bend; - char *src = &_etext; - char *dst = &_data; - - /* ROM has data at end of text; copy it. */ - while (dst < &_edata) { - *dst++ = *src++; - } - - /* Zero bss */ - for (dst = &_bstart; dst< &_bend; dst++) - *dst = 0; - -3.6.8.3 Forced Output Alignment -............................... - -You can increase an output section's alignment by using ALIGN. - -3.6.8.4 Forced Input Alignment -.............................. - -You can force input section alignment within an output section by using -SUBALIGN. The value specified overrides any alignment given by input -sections, whether larger or smaller. - -3.6.8.5 Output Section Region -............................. - -You can assign a section to a previously defined region of memory by -using '>REGION'. *Note MEMORY::. - - Here is a simple example: - MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } - SECTIONS { ROM : { *(.text) } >rom } - -3.6.8.6 Output Section Phdr -........................... - -You can assign a section to a previously defined program segment by -using ':PHDR'. *Note PHDRS::. If a section is assigned to one or more -segments, then all subsequent allocated sections will be assigned to -those segments as well, unless they use an explicitly ':PHDR' modifier. -You can use ':NONE' to tell the linker to not put the section in any -segment at all. - - Here is a simple example: - PHDRS { text PT_LOAD ; } - SECTIONS { .text : { *(.text) } :text } - -3.6.8.7 Output Section Fill -........................... - -You can set the fill pattern for an entire section by using '=FILLEXP'. -FILLEXP is an expression (*note Expressions::). Any otherwise -unspecified regions of memory within the output section (for example, -gaps left due to the required alignment of input sections) will be -filled with the value, repeated as necessary. If the fill expression is -a simple hex number, ie. a string of hex digit starting with '0x' and -without a trailing 'k' or 'M', then an arbitrarily long sequence of hex -digits can be used to specify the fill pattern; Leading zeros become -part of the pattern too. For all other cases, including extra -parentheses or a unary '+', the fill pattern is the four least -significant bytes of the value of the expression. In all cases, the -number is big-endian. - - You can also change the fill value with a 'FILL' command in the -output section commands; (*note Output Section Data::). - - Here is a simple example: - SECTIONS { .text : { *(.text) } =0x90909090 } - -3.6.9 Overlay Description -------------------------- - -An overlay description provides an easy way to describe sections which -are to be loaded as part of a single memory image but are to be run at -the same memory address. At run time, some sort of overlay manager will -copy the overlaid sections in and out of the runtime memory address as -required, perhaps by simply manipulating addressing bits. This approach -can be useful, for example, when a certain region of memory is faster -than another. - - Overlays are described using the 'OVERLAY' command. The 'OVERLAY' -command is used within a 'SECTIONS' command, like an output section -description. The full syntax of the 'OVERLAY' command is as follows: - OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )] - { - SECNAME1 - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [:PHDR...] [=FILL] - SECNAME2 - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [:PHDR...] [=FILL] - ... - } [>REGION] [:PHDR...] [=FILL] - - Everything is optional except 'OVERLAY' (a keyword), and each section -must have a name (SECNAME1 and SECNAME2 above). The section definitions -within the 'OVERLAY' construct are identical to those within the general -'SECTIONS' contruct (*note SECTIONS::), except that no addresses and no -memory regions may be defined for sections within an 'OVERLAY'. - - The sections are all defined with the same starting address. The -load addresses of the sections are arranged such that they are -consecutive in memory starting at the load address used for the -'OVERLAY' as a whole (as with normal section definitions, the load -address is optional, and defaults to the start address; the start -address is also optional, and defaults to the current value of the -location counter). - - If the 'NOCROSSREFS' keyword is used, and there any references among -the sections, the linker will report an error. Since the sections all -run at the same address, it normally does not make sense for one section -to refer directly to another. *Note NOCROSSREFS: Miscellaneous -Commands. - - For each section within the 'OVERLAY', the linker automatically -provides two symbols. The symbol '__load_start_SECNAME' is defined as -the starting load address of the section. The symbol -'__load_stop_SECNAME' is defined as the final load address of the -section. Any characters within SECNAME which are not legal within C -identifiers are removed. C (or assembler) code may use these symbols to -move the overlaid sections around as necessary. - - At the end of the overlay, the value of the location counter is set -to the start address of the overlay plus the size of the largest -section. - - Here is an example. Remember that this would appear inside a -'SECTIONS' construct. - OVERLAY 0x1000 : AT (0x4000) - { - .text0 { o1/*.o(.text) } - .text1 { o2/*.o(.text) } - } -This will define both '.text0' and '.text1' to start at address 0x1000. -'.text0' will be loaded at address 0x4000, and '.text1' will be loaded -immediately after '.text0'. The following symbols will be defined if -referenced: '__load_start_text0', '__load_stop_text0', -'__load_start_text1', '__load_stop_text1'. - - C code to copy overlay '.text1' into the overlay area might look like -the following. - - extern char __load_start_text1, __load_stop_text1; - memcpy ((char *) 0x1000, &__load_start_text1, - &__load_stop_text1 - &__load_start_text1); - - Note that the 'OVERLAY' command is just syntactic sugar, since -everything it does can be done using the more basic commands. The above -example could have been written identically as follows. - - .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } - PROVIDE (__load_start_text0 = LOADADDR (.text0)); - PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); - .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } - PROVIDE (__load_start_text1 = LOADADDR (.text1)); - PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); - . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); - -3.7 MEMORY Command -================== - -The linker's default configuration permits allocation of all available -memory. You can override this by using the 'MEMORY' command. - - The 'MEMORY' command describes the location and size of blocks of -memory in the target. You can use it to describe which memory regions -may be used by the linker, and which memory regions it must avoid. You -can then assign sections to particular memory regions. The linker will -set section addresses based on the memory regions, and will warn about -regions that become too full. The linker will not shuffle sections -around to fit into the available regions. - - A linker script 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 - ... - } - - The NAME is a name used in the linker script to refer to the region. -The region name has no meaning outside of the linker script. Region -names are stored in a separate name space, and will not conflict with -symbol names, file names, or section names. Each memory region must -have a distinct name. - - The ATTR string is an optional list of attributes that specify -whether to use a particular memory region for an input section which is -not explicitly mapped in the linker script. As described in *note -SECTIONS::, if you do not specify an output section for some input -section, the linker will create an output section with the same name as -the input section. If you define region attributes, the linker will use -them to select the memory region for the output section that it creates. - - The ATTR string must consist only of the following characters: -'R' - Read-only section -'W' - Read/write section -'X' - Executable section -'A' - Allocatable section -'I' - Initialized section -'L' - Same as 'I' -'!' - Invert the sense of any of the preceding attributes - - If a unmapped section matches any of the listed attributes other than -'!', it will be placed in the memory region. The '!' attribute reverses -this test, so that an unmapped section will be placed in the memory -region only if it does not match any of the listed attributes. - - The ORIGIN is an numerical expression for the start address of the -memory region. The expression must evaluate to a constant and it cannot -involve any symbols. The keyword 'ORIGIN' may be abbreviated to 'org' -or 'o' (but not, for example, 'ORG'). - - The LEN is an expression for the size in bytes of the memory region. -As with the ORIGIN expression, the expression must be numerical only and -must evaluate to a constant. The keyword 'LENGTH' may be abbreviated to -'len' or 'l'. - - In the following example, we specify that there are two memory -regions available for allocation: one starting at '0' for 256 kilobytes, -and the other starting at '0x40000000' for four megabytes. The linker -will place into the 'rom' memory region every section which is not -explicitly mapped into a memory region, and is either read-only or -executable. The linker will place other sections which are not -explicitly mapped into a memory region into the 'ram' memory region. - - MEMORY - { - rom (rx) : ORIGIN = 0, LENGTH = 256K - ram (!rx) : org = 0x40000000, l = 4M - } - - Once you define a memory region, you can direct the linker to place -specific output sections into that memory region by using the '>REGION' -output section attribute. For example, if you have a memory region -named 'mem', you would use '>mem' in the output section definition. -*Note Output Section Region::. If no address was specified for the -output section, the linker will set the address to the next available -address within the memory region. If the combined output sections -directed to a memory region are too large for the region, the linker -will issue an error message. - - It is possible to access the origin and length of a memory in an -expression via the 'ORIGIN(MEMORY)' and 'LENGTH(MEMORY)' functions: - - _fstack = ORIGIN(ram) + LENGTH(ram) - 4; - -3.8 PHDRS Command -================= - -The ELF object file format uses "program headers", also knows as -"segments". The program headers describe how the program should be -loaded into memory. You can print them out by using the 'objdump' -program with the '-p' option. - - When you run an ELF program on a native ELF system, the system loader -reads the program headers in order to figure out how to load the -program. This will only work if the program headers are set correctly. -This manual does not describe the details of how the system loader -interprets program headers; for more information, see the ELF ABI. - - The linker will create reasonable program headers by default. -However, in some cases, you may need to specify the program headers more -precisely. You may use the 'PHDRS' command for this purpose. When the -linker sees the 'PHDRS' command in the linker script, it will not create -any program headers other than the ones specified. - - The linker only pays attention to the 'PHDRS' command when generating -an ELF output file. In other cases, the linker will simply ignore -'PHDRS'. - - This is the syntax of the 'PHDRS' command. The words 'PHDRS', -'FILEHDR', 'AT', and 'FLAGS' are keywords. - - PHDRS - { - NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ] - [ FLAGS ( FLAGS ) ] ; - } - - The NAME is used only for reference in the 'SECTIONS' command of the -linker script. It is not put into the output file. Program header -names are stored in a separate name space, and will not conflict with -symbol names, file names, or section names. Each program header must -have a distinct name. - - Certain program header types describe segments of memory which the -system loader will load from the file. In the linker script, you -specify the contents of these segments by placing allocatable output -sections in the segments. You use the ':PHDR' output section attribute -to place a section in a particular segment. *Note Output Section -Phdr::. - - It is normal to put certain sections in more than one segment. This -merely implies that one segment of memory contains another. You may -repeat ':PHDR', using it once for each segment which should contain the -section. - - If you place a section in one or more segments using ':PHDR', then -the linker will place all subsequent allocatable sections which do not -specify ':PHDR' in the same segments. This is for convenience, since -generally a whole set of contiguous sections will be placed in a single -segment. You can use ':NONE' to override the default segment and tell -the linker to not put the section in any segment at all. - - You may use the 'FILEHDR' and 'PHDRS' keywords appear after the -program header type to further describe the contents of the segment. -The 'FILEHDR' keyword means that the segment should include the ELF file -header. The 'PHDRS' keyword means that the segment should include the -ELF program headers themselves. - - The TYPE may be one of the following. The numbers indicate the value -of the keyword. - -'PT_NULL' (0) - Indicates an unused program header. - -'PT_LOAD' (1) - Indicates that this program header describes a segment to be loaded - from the file. - -'PT_DYNAMIC' (2) - Indicates a segment where dynamic linking information can be found. - -'PT_INTERP' (3) - Indicates a segment where the name of the program interpreter may - be found. - -'PT_NOTE' (4) - Indicates a segment holding note information. - -'PT_SHLIB' (5) - A reserved program header type, defined but not specified by the - ELF ABI. - -'PT_PHDR' (6) - Indicates a segment where the program headers may be found. - -EXPRESSION - An expression giving the numeric type of the program header. This - may be used for types not defined above. - - You can specify that a segment should be loaded at a particular -address in memory by using an 'AT' expression. This is identical to the -'AT' command used as an output section attribute (*note Output Section -LMA::). The 'AT' command for a program header overrides the output -section attribute. - - The linker will normally set the segment flags based on the sections -which comprise the segment. You may use the 'FLAGS' keyword to -explicitly specify the segment flags. The value of FLAGS must be an -integer. It is used to set the 'p_flags' field of the program header. - - Here is an example of 'PHDRS'. This shows a typical set of program -headers used on a native ELF system. - - PHDRS - { - headers PT_PHDR PHDRS ; - interp PT_INTERP ; - text PT_LOAD FILEHDR PHDRS ; - data PT_LOAD ; - dynamic PT_DYNAMIC ; - } - - SECTIONS - { - . = SIZEOF_HEADERS; - .interp : { *(.interp) } :text :interp - .text : { *(.text) } :text - .rodata : { *(.rodata) } /* defaults to :text */ - ... - . = . + 0x1000; /* move to a new page in memory */ - .data : { *(.data) } :data - .dynamic : { *(.dynamic) } :data :dynamic - ... - } - -3.9 VERSION Command -=================== - -The linker supports symbol versions when using ELF. Symbol versions are -only useful when using shared libraries. The dynamic linker can use -symbol versions to select a specific version of a function when it runs -a program that may have been linked against an earlier version of the -shared library. - - You can include a version script directly in the main linker script, -or you can supply the version script as an implicit linker script. You -can also use the '--version-script' linker option. - - The syntax of the 'VERSION' command is simply - VERSION { version-script-commands } - - The format of the version script commands is identical to that used -by Sun's linker in Solaris 2.5. The version script defines a tree of -version nodes. You specify the node names and interdependencies in the -version script. You can specify which symbols are bound to which -version nodes, and you can reduce a specified set of symbols to local -scope so that they are not globally visible outside of the shared -library. - - The easiest way to demonstrate the version script language is with a -few examples. - - VERS_1.1 { - global: - foo1; - local: - old*; - original*; - new*; - }; - - VERS_1.2 { - foo2; - } VERS_1.1; - - VERS_2.0 { - bar1; bar2; - extern "C++" { - ns::*; - "int f(int, double)"; - } - } VERS_1.2; - - This example version script defines three version nodes. The first -version node defined is 'VERS_1.1'; it has no other dependencies. The -script binds the symbol 'foo1' to 'VERS_1.1'. It reduces a number of -symbols to local scope so that they are not visible outside of the -shared library; this is done using wildcard patterns, so that any symbol -whose name begins with 'old', 'original', or 'new' is matched. The -wildcard patterns available are the same as those used in the shell when -matching filenames (also known as "globbing"). However, if you specify -the symbol name inside double quotes, then the name is treated as -literal, rather than as a glob pattern. - - Next, the version script defines node 'VERS_1.2'. This node depends -upon 'VERS_1.1'. The script binds the symbol 'foo2' to the version node -'VERS_1.2'. - - Finally, the version script defines node 'VERS_2.0'. This node -depends upon 'VERS_1.2'. The scripts binds the symbols 'bar1' and -'bar2' are bound to the version node 'VERS_2.0'. - - When the linker finds a symbol defined in a library which is not -specifically bound to a version node, it will effectively bind it to an -unspecified base version of the library. You can bind all otherwise -unspecified symbols to a given version node by using 'global: *;' -somewhere in the version script. - - The names of the version nodes have no specific meaning other than -what they might suggest to the person reading them. The '2.0' version -could just as well have appeared in between '1.1' and '1.2'. However, -this would be a confusing way to write a version script. - - Node name can be omitted, provided it is the only version node in the -version script. Such version script doesn't assign any versions to -symbols, only selects which symbols will be globally visible out and -which won't. - - { global: foo; bar; local: *; }; - - When you link an application against a shared library that has -versioned symbols, the application itself knows which version of each -symbol it requires, and it also knows which version nodes it needs from -each shared library it is linked against. Thus at runtime, the dynamic -loader can make a quick check to make sure that the libraries you have -linked against do in fact supply all of the version nodes that the -application will need to resolve all of the dynamic symbols. In this -way it is possible for the dynamic linker to know with certainty that -all external symbols that it needs will be resolvable without having to -search for each symbol reference. - - The symbol versioning is in effect a much more sophisticated way of -doing minor version checking that SunOS does. The fundamental problem -that is being addressed here is that typically references to external -functions are bound on an as-needed basis, and are not all bound when -the application starts up. If a shared library is out of date, a -required interface may be missing; when the application tries to use -that interface, it may suddenly and unexpectedly fail. With symbol -versioning, the user will get a warning when they start their program if -the libraries being used with the application are too old. - - There are several GNU extensions to Sun's versioning approach. The -first of these is the ability to bind a symbol to a version node in the -source file where the symbol is defined instead of in the versioning -script. This was done mainly to reduce the burden on the library -maintainer. You can do this by putting something like: - __asm__(".symver original_foo,foo@VERS_1.1"); -in the C source file. This renames the function 'original_foo' to be an -alias for 'foo' bound to the version node 'VERS_1.1'. The 'local:' -directive can be used to prevent the symbol 'original_foo' from being -exported. A '.symver' directive takes precedence over a version script. - - The second GNU extension is to allow multiple versions of the same -function to appear in a given shared library. In this way you can make -an incompatible change to an interface without increasing the major -version number of the shared library, while still allowing applications -linked against the old interface to continue to function. - - To do this, you must use multiple '.symver' directives in the source -file. Here is an example: - - __asm__(".symver original_foo,foo@"); - __asm__(".symver old_foo,foo@VERS_1.1"); - __asm__(".symver old_foo1,foo@VERS_1.2"); - __asm__(".symver new_foo,foo@@VERS_2.0"); - - In this example, 'foo@' represents the symbol 'foo' bound to the -unspecified base version of the symbol. The source file that contains -this example would define 4 C functions: 'original_foo', 'old_foo', -'old_foo1', and 'new_foo'. - - When you have multiple definitions of a given symbol, there needs to -be some way to specify a default version to which external references to -this symbol will be bound. You can do this with the 'foo@@VERS_2.0' -type of '.symver' directive. You can only declare one version of a -symbol as the default in this manner; otherwise you would effectively -have multiple definitions of the same symbol. - - If you wish to bind a reference to a specific version of the symbol -within the shared library, you can use the aliases of convenience (i.e., -'old_foo'), or you can use the '.symver' directive to specifically bind -to an external version of the function in question. - - You can also specify the language in the version script: - - VERSION extern "lang" { version-script-commands } - - The supported 'lang's are 'C', 'C++', and 'Java'. The linker will -iterate over the list of symbols at the link time and demangle them -according to 'lang' before matching them to the patterns specified in -'version-script-commands'. - - Demangled names may contains spaces and other special characters. As -described above, you can use a glob pattern to match demangled names, or -you can use a double-quoted string to match the string exactly. In the -latter case, be aware that minor differences (such as differing -whitespace) between the version script and the demangler output will -cause a mismatch. As the exact string generated by the demangler might -change in the future, even if the mangled name does not, you should -check that all of your version directives are behaving as you expect -when you upgrade. - -3.10 Expressions in Linker Scripts -================================== - -The syntax for expressions in the linker script language is identical to -that of C expressions. All expressions are evaluated as integers. All -expressions are evaluated in the same size, which is 32 bits if both the -host and target are 32 bits, and is otherwise 64 bits. - - You can use and set symbol values in expressions. - - The linker defines several special purpose builtin functions for use -in expressions. - -3.10.1 Constants ----------------- - -All constants are integers. - - As in C, the linker considers an integer beginning with '0' to be -octal, and an integer beginning with '0x' or '0X' to be hexadecimal. -The linker considers other integers to be decimal. - - In addition, you can use the suffixes 'K' and 'M' 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; - -3.10.2 Symbol Names -------------------- - -Unless quoted, symbol names start with a letter, underscore, or period -and may include letters, digits, underscores, periods, and hyphens. -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; - - Since symbols can contain many non-alphabetic characters, it is -safest to delimit symbols with spaces. For example, 'A-B' is one -symbol, whereas 'A - B' is an expression involving subtraction. - -3.10.3 Orphan Sections ----------------------- - -Orphan sections are sections present in the input files which are not -explicitly placed into the output file by the linker script. The linker -will still copy these sections into the output file, but it has to guess -as to where they should be placed. The linker uses a simple heuristic -to do this. It attempts to place orphan sections after non-orphan -sections of the same attribute, such as code vs data, loadable vs -non-loadable, etc. If there is not enough room to do this then it -places at the end of the file. - - For ELF targets, the attribute of the section includes section type -as well as section flag. - -3.10.4 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 may only appear in an expression within a 'SECTIONS' -command. The '.' symbol may appear anywhere that an ordinary symbol is -allowed in an expression. - - Assigning a value to '.' will cause the location counter to be moved. -This may be used to create holes in the output section. The location -counter may not be moved backwards inside an output section, and may not -be moved backwards outside of an output section if so doing creates -areas with overlapping LMAs. - - SECTIONS - { - output : - { - file1(.text) - . = . + 1000; - file2(.text) - . += 1000; - file3(.text) - } = 0x12345678; - } -In the previous example, the '.text' section from 'file1' is located at -the beginning of the output section 'output'. It is followed by a 1000 -byte gap. Then the '.text' section from 'file2' appears, also with a -1000 byte gap following before the '.text' section from 'file3'. The -notation '= 0x12345678' specifies what data to write in the gaps (*note -Output Section Fill::). - - Note: '.' actually refers to the byte offset from the start of the -current containing object. Normally this is the 'SECTIONS' statement, -whose start address is 0, hence '.' can be used as an absolute address. -If '.' is used inside a section description however, it refers to the -byte offset from the start of that section, not an absolute address. -Thus in a script like this: - - SECTIONS - { - . = 0x100 - .text: { - *(.text) - . = 0x200 - } - . = 0x500 - .data: { - *(.data) - . += 0x600 - } - } - - The '.text' section will be assigned a starting address of 0x100 and -a size of exactly 0x200 bytes, even if there is not enough data in the -'.text' input sections to fill this area. (If there is too much data, -an error will be produced because this would be an attempt to move '.' -backwards). The '.data' section will start at 0x500 and it will have an -extra 0x600 bytes worth of space after the end of the values from the -'.data' input sections and before the end of the '.data' output section -itself. - - Setting symbols to the value of the location counter outside of an -output section statement can result in unexpected values if the linker -needs to place orphan sections. For example, given the following: - - SECTIONS - { - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - start_of_data = . ; - .data: { *(.data) } - end_of_data = . ; - } - - If the linker needs to place some input section, e.g. '.rodata', not -mentioned in the script, it might choose to place that section between -'.text' and '.data'. You might think the linker should place '.rodata' -on the blank line in the above script, but blank lines are of no -particular significance to the linker. As well, the linker doesn't -associate the above symbol names with their sections. Instead, it -assumes that all assignments or other statements belong to the previous -output section, except for the special case of an assignment to '.'. -I.e., the linker will place the orphan '.rodata' section as if the -script was written as follows: - - SECTIONS - { - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - start_of_data = . ; - .rodata: { *(.rodata) } - .data: { *(.data) } - end_of_data = . ; - } - - This may or may not be the script author's intention for the value of -'start_of_data'. One way to influence the orphan section placement is -to assign the location counter to itself, as the linker assumes that an -assignment to '.' is setting the start address of a following output -section and thus should be grouped with that section. So you could -write: - - SECTIONS - { - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - . = . ; - start_of_data = . ; - .data: { *(.data) } - end_of_data = . ; - } - - Now, the orphan '.rodata' section will be placed between -'end_of_text' and 'start_of_data'. - -3.10.5 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 Assignments::. - -3.10.6 Evaluation ------------------ - -The linker evaluates expressions lazily. It only computes the value of -an expression when absolutely necessary. - - The linker needs some information, such as the value of the start -address of the first section, and the origins and 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 linker script. - - 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. - - 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 -'.', must be evaluated during section 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 : - { *(.text) } - } -will cause the error message 'non constant expression for initial -address'. - -3.10.7 The Section of an Expression ------------------------------------ - -When the linker evaluates an expression, the result is either absolute -or relative to some section. A relative expression is expressed as a -fixed offset from the base of a section. - - The position of the expression within the linker script determines -whether it is absolute or relative. An expression which appears within -an output section definition is relative to the base of the output -section. An expression which appears elsewhere will be absolute. - - A symbol set to a relative expression will be relocatable if you -request relocatable output using the '-r' option. That means that a -further link operation may change the value of the symbol. The symbol's -section will be the section of the relative expression. - - A symbol set to an absolute expression will retain the same value -through any further link operation. The symbol will be absolute, and -will not have any particular associated section. - - You can use the builtin function 'ABSOLUTE' to force an expression to -be absolute when it would otherwise be relative. For example, to create -an absolute symbol set to the address of the end of the output section -'.data': - SECTIONS - { - .data : { *(.data) _edata = ABSOLUTE(.); } - } -If 'ABSOLUTE' were not used, '_edata' would be relative to the '.data' -section. - -3.10.8 Builtin Functions ------------------------- - -The linker script language includes a number of builtin functions for -use in linker 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. *Note Expression - Section::. - -'ADDR(SECTION)' - Return the absolute address (the VMA) 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(ALIGN)' -'ALIGN(EXP,ALIGN)' - Return the location counter ('.') or arbitrary expression aligned - to the next ALIGN boundary. The single operand 'ALIGN' doesn't - change the value of the location counter--it just does arithmetic - on it. The two operand 'ALIGN' allows an arbitrary expression to - be aligned upwards ('ALIGN(ALIGN)' is equivalent to 'ALIGN(., - ALIGN)'). - - Here is an example which aligns the output '.data' section to the - next '0x2000' byte boundary after the preceding section and sets 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 ADDRESS attribute of a - section definition (*note Output Section Address::). The second - use of 'ALIGN' is used to defines the value of a symbol. - - The builtin function 'NEXT' is closely related to 'ALIGN'. - -'ALIGNOF(SECTION)' - Return the alignment in bytes of the named SECTION, if that section - has been allocated. If the section has not been allocated when - this is evaluated, the linker will report an error. In the - following example, the alignment of the '.output' section is stored - as the first value in that section. - SECTIONS{ ... - .output { - LONG (ALIGNOF (.output)) - ... - } - ... } - -'BLOCK(EXP)' - This is a synonym for 'ALIGN', for compatibility with older linker - scripts. It is most often seen when setting the address of an - output section. - -'DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)' - This is equivalent to either - (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1))) - or - (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE))) - depending on whether the latter uses fewer COMMONPAGESIZE sized - pages for the data segment (area between the result of this - expression and 'DATA_SEGMENT_END') than the former or not. If the - latter form is used, it means COMMONPAGESIZE bytes of runtime - memory will be saved at the expense of up to COMMONPAGESIZE wasted - bytes in the on-disk file. - - This expression can only be used directly in 'SECTIONS' commands, - not in any output section descriptions and only once in the linker - script. COMMONPAGESIZE should be less or equal to MAXPAGESIZE and - should be the system page size the object wants to be optimized for - (while still working on system page sizes up to MAXPAGESIZE). - - Example: - . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); - -'DATA_SEGMENT_END(EXP)' - This defines the end of data segment for 'DATA_SEGMENT_ALIGN' - evaluation purposes. - - . = DATA_SEGMENT_END(.); - -'DATA_SEGMENT_RELRO_END(OFFSET, EXP)' - This defines the end of the 'PT_GNU_RELRO' segment when '-z relro' - option is used. Second argument is returned. When '-z relro' - option is not present, 'DATA_SEGMENT_RELRO_END' does nothing, - otherwise 'DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is - aligned to the most commonly used page boundary for particular - target. If present in the linker script, it must always come in - between 'DATA_SEGMENT_ALIGN' and 'DATA_SEGMENT_END'. - - . = DATA_SEGMENT_RELRO_END(24, .); - -'DEFINED(SYMBOL)' - Return 1 if SYMBOL is in the linker global symbol table and is - defined before the statement using DEFINED in the script, otherwise - return 0. You can use this function to provide default values for - symbols. For example, the following script 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 : . ; - ... - } - ... - } - -'LENGTH(MEMORY)' - Return the length of the memory region named MEMORY. - -'LOADADDR(SECTION)' - Return the absolute LMA of the named SECTION. This is normally the - same as 'ADDR', but it may be different if the 'AT' attribute is - used in the output section definition (*note Output Section LMA::). - -'MAX(EXP1, EXP2)' - Returns the maximum of EXP1 and EXP2. - -'MIN(EXP1, EXP2)' - Returns the minimum of EXP1 and EXP2. - -'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. - -'ORIGIN(MEMORY)' - Return the origin of the memory region named MEMORY. - -'SEGMENT_START(SEGMENT, DEFAULT)' - Return the base address of the named SEGMENT. If an explicit value - has been given for this segment (with a command-line '-T' option) - that value will be returned; otherwise the value will be DEFAULT. - At present, the '-T' command-line option can only be used to set - the base address for the "text", "data", and "bss" sections, but - you use 'SEGMENT_START' with any segment name. - -'SIZEOF(SECTION)' - Return the size in bytes of the named SECTION, if that section has - been allocated. If the section has not been allocated when this is - evaluated, the linker will report an error. 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. This is - information which appears at the start of the output file. You can - use this number when setting the start address of the first - section, if you choose, to facilitate paging. - - When producing an ELF output file, if the linker script uses the - 'SIZEOF_HEADERS' builtin function, the linker must compute the - number of program headers before it has determined all the section - addresses and sizes. If the linker later discovers that it needs - additional program headers, it will report an error 'not enough - room for program headers'. To avoid this error, you must avoid - using the 'SIZEOF_HEADERS' function, or you must rework your linker - script to avoid forcing the linker to use additional program - headers, or you must define the program headers yourself using the - 'PHDRS' command (*note PHDRS::). - -3.11 Implicit Linker Scripts -============================ - -If you specify a linker input file which the linker can not recognize as -an object file or an archive file, it will try to read the file as a -linker script. If the file can not be parsed as a linker script, the -linker will report an error. - - An implicit linker script will not replace the default linker script. - - Typically an implicit linker script would contain only symbol -assignments, or the 'INPUT', 'GROUP', or 'VERSION' commands. - - Any input files read because of an implicit linker script will be -read at the position in the command line where the implicit linker -script was read. This can affect archive searching. - -4 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. - -4.1 '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). - -_bit manipulation instructions_ - 'ld' finds all bit manipulation instructions like 'band, bclr, - biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, - bxor' which use 32 bit and 16 bit absolute address form, but refer - to the top page of memory, and changes them to use the 8 bit - address form. (That is: the linker turns 'bset #xx:3,'@'AA:32' - into 'bset #xx:3,'@'AA:8' whenever the address AA is in the top - page of memory). - -_system control instructions_ - 'ld' finds all 'ldc.w, stc.w' instructions which use the 32 bit - absolute address form, but refer to the top page of memory, and - changes them to use 16 bit address form. (That is: the linker - turns 'ldc.w '@'AA:32,ccr' into 'ldc.w '@'AA:16,ccr' whenever the - address AA is in the top page of memory). - -4.2 '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. - - 'ld' supports the '--relax' option for the i960 family. If you -specify '--relax', 'ld' finds all 'balx' and 'calx' instructions whose -targets are within 24 bits, and turns them into 24-bit program-counter -relative 'bal' and 'cal' instructions, respectively. 'ld' also turns -'cal' instructions into 'bal' instructions when it determines that the -target subroutine is a leaf routine (that is, the target subroutine does -not itself call any subroutines). - -4.3 'ld' and the Motorola 68HC11 and 68HC12 families -==================================================== - -4.3.1 Linker Relaxation ------------------------ - -For the Motorola 68HC11, '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. - - 'ld' also looks at all 16-bit extended addressing modes and - transforms them in a direct addressing mode when the address is in - page 0 (between 0 and 0x0ff). - -_relaxing gcc instruction group_ - When 'gcc' is called with '-mrelax', it can emit group of - instructions that the linker can optimize to use a 68HC11 direct - addressing mode. These instructions consists of 'bclr' or 'bset' - instructions. - -4.3.2 Trampoline Generation ---------------------------- - -For 68HC11 and 68HC12, 'ld' can generate trampoline code to call a far -function using a normal 'jsr' instruction. The linker will also change -the relocation to some far function to use the trampoline address -instead of the function address. This is typically the case when a -pointer to a function is taken. The pointer will in fact point to the -function trampoline. - - The '--pic-veneer' switch makes the linker use PIC sequences for -ARM/Thumb interworking veneers, even if the rest of the binary is not -PIC. This avoids problems on uClinux targets where '--emit-relocs' is -used to generate relocatable binaries. - -4.4 'ld' and the ARM family -=========================== - -For the ARM, 'ld' will generate code stubs to allow functions calls -between ARM and Thumb code. These stubs only work with code that has -been compiled and assembled with the '-mthumb-interwork' command line -option. If it is necessary to link with old ARM object files or -libraries, which have not been compiled with the -mthumb-interwork -option then the '--support-old-code' command line switch should be given -to the linker. This will make it generate larger stub functions which -will work with non-interworking aware ARM code. Note, however, the -linker does not support generating stubs for function calls to -non-interworking aware Thumb code. - - The '--thumb-entry' switch is a duplicate of the generic '--entry' -switch, in that it sets the program's starting address. But it also -sets the bottom bit of the address, so that it can be branched to using -a BX instruction, and the program will start executing in Thumb mode -straight away. - - The '--be8' switch instructs 'ld' to generate BE8 format executables. -This option is only valid when linking big-endian objects. The -resulting image will contain big-endian data and little-endian code. - - The 'R_ARM_TARGET1' relocation is typically used for entries in the -'.init_array' section. It is interpreted as either 'R_ARM_REL32' or -'R_ARM_ABS32', depending on the target. The '--target1-rel' and -'--target1-abs' switches override the default. - - The '--target2=type' switch overrides the default definition of the -'R_ARM_TARGET2' relocation. Valid values for 'type', their meanings, -and target defaults are as follows: -'rel' - 'R_ARM_REL32' (arm*-*-elf, arm*-*-eabi) -'abs' - 'R_ARM_ABS32' (arm*-*-symbianelf) -'got-rel' - 'R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd) - - The 'R_ARM_V4BX' relocation (defined by the ARM AAELF specification) -enables objects compiled for the ARMv4 architecture to be -interworking-safe when linked with other objects compiled for ARMv4t, -but also allows pure ARMv4 binaries to be built from the same ARMv4 -objects. - - In the latter case, the switch '--fix-v4bx' must be passed to the -linker, which causes v4t 'BX rM' instructions to be rewritten as 'MOV -PC,rM', since v4 processors do not have a 'BX' instruction. - - In the former case, the switch should not be used, and 'R_ARM_V4BX' -relocations are ignored. - - The '--use-blx' switch enables the linker to use ARM/Thumb BLX -instructions (available on ARMv5t and above) in various situations. -Currently it is used to perform calls via the PLT from Thumb code using -BLX rather than using BX and a mode-switching stub before each PLT -entry. This should lead to such calls executing slightly faster. - - This option is enabled implicitly for SymbianOS, so there is no need -to specify it if you are using that target. - - The '--vfp11-denorm-fix' switch enables a link-time workaround for a -bug in certain VFP11 coprocessor hardware, which sometimes allows -instructions with denorm operands (which must be handled by support -code) to have those operands overwritten by subsequent instructions -before the support code can read the intended values. - - The bug may be avoided in scalar mode if you allow at least one -intervening instruction between a VFP11 instruction which uses a -register and another instruction which writes to the same register, or -at least two intervening instructions if vector mode is in use. The bug -only affects full-compliance floating-point mode: you do not need this -workaround if you are using "runfast" mode. Please contact ARM for -further details. - - If you know you are using buggy VFP11 hardware, you can enable this -workaround by specifying the linker option '--vfp-denorm-fix=scalar' if -you are using the VFP11 scalar mode only, or '--vfp-denorm-fix=vector' -if you are using vector mode (the latter also works for scalar code). -The default is '--vfp-denorm-fix=none'. - - If the workaround is enabled, instructions are scanned for -potentially-troublesome sequences, and a veneer is created for each such -sequence which may trigger the erratum. The veneer consists of the -first instruction of the sequence and a branch back to the subsequent -instruction. The original instruction is then replaced with a branch to -the veneer. The extra cycles required to call and return from the -veneer are sufficient to avoid the erratum in both the scalar and vector -cases. - - The '--no-enum-size-warning' switch prevents the linker from warning -when linking object files that specify incompatible EABI enumeration -size attributes. For example, with this switch enabled, linking of an -object file using 32-bit enumeration values with another using -enumeration values fitted into the smallest possible space will not be -diagnosed. - -4.5 'ld' and HPPA 32-bit ELF Support -==================================== - -When generating a shared library, 'ld' will by default generate import -stubs suitable for use with a single sub-space application. The -'--multi-subspace' switch causes 'ld' to generate export stubs, and -different (larger) import stubs suitable for use with multiple -sub-spaces. - - Long branch stubs and import/export stubs are placed by 'ld' in stub -sections located between groups of input sections. '--stub-group-size' -specifies the maximum size of a group of input sections handled by one -stub section. Since branch offsets are signed, a stub section may serve -two groups of input sections, one group before the stub section, and one -group after it. However, when using conditional branches that require -stubs, it may be better (for branch prediction) that stub sections only -serve one group of input sections. A negative value for 'N' chooses -this scheme, ensuring that branches to stubs always use a negative -offset. Two special values of 'N' are recognized, '1' and '-1'. These -both instruct 'ld' to automatically size input section groups for the -branch types detected, with the same behaviour regarding stub placement -as other positive or negative values of 'N' respectively. - - Note that '--stub-group-size' does not split input sections. A -single input section larger than the group size specified will of course -create a larger group (of one section). If input sections are too -large, it may not be possible for a branch to reach its stub. - -4.6 'ld' and MMIX -================= - -For MMIX, there is a choice of generating 'ELF' object files or 'mmo' -object files when linking. The simulator 'mmix' understands the 'mmo' -format. The binutils 'objcopy' utility can translate between the two -formats. - - There is one special section, the '.MMIX.reg_contents' section. -Contents in this section is assumed to correspond to that of global -registers, and symbols referring to it are translated to special -symbols, equal to registers. In a final link, the start address of the -'.MMIX.reg_contents' section corresponds to the first allocated global -register multiplied by 8. Register '$255' is not included in this -section; it is always set to the program entry, which is at the symbol -'Main' for 'mmo' files. - - Symbols with the prefix '__.MMIX.start.', for example -'__.MMIX.start..text' and '__.MMIX.start..data' are special; there must -be only one each, even if they are local. The default linker script -uses these to set the default start address of a section. - - Initial and trailing multiples of zero-valued 32-bit words in a -section, are left out from an mmo file. - -4.7 'ld' and MSP430 -=================== - -For the MSP430 it is possible to select the MPU architecture. The flag -'-m [mpu type]' will select an appropriate linker script for selected -MPU type. (To get a list of known MPUs just pass '-m help' option to -the linker). - - The linker will recognize some extra sections which are MSP430 -specific: - -''.vectors'' - Defines a portion of ROM where interrupt vectors located. - -''.bootloader'' - Defines the bootloader portion of the ROM (if applicable). Any - code in this section will be uploaded to the MPU. - -''.infomem'' - Defines an information memory section (if applicable). Any code in - this section will be uploaded to the MPU. - -''.infomemnobits'' - This is the same as the '.infomem' section except that any code in - this section will not be uploaded to the MPU. - -''.noinit'' - Denotes a portion of RAM located above '.bss' section. - - The last two sections are used by gcc. - -4.8 'ld' and PowerPC 32-bit ELF Support -======================================= - -Branches on PowerPC processors are limited to a signed 26-bit -displacement, which may result in 'ld' giving 'relocation truncated to -fit' errors with very large programs. '--relax' enables the generation -of trampolines that can access the entire 32-bit address space. These -trampolines are inserted at section boundaries, so may not themselves be -reachable if an input section exceeds 33M in size. - -'--bss-plt' - Current PowerPC GCC accepts a '-msecure-plt' option that generates - code capable of using a newer PLT and GOT layout that has the - security advantage of no executable section ever needing to be - writable and no writable section ever being executable. PowerPC - 'ld' will generate this layout, including stubs to access the PLT, - if all input files (including startup and static libraries) were - compiled with '-msecure-plt'. '--bss-plt' forces the old BSS PLT - (and GOT layout) which can give slightly better performance. - -'--secure-plt' - 'ld' will use the new PLT and GOT layout if it is linking new - '-fpic' or '-fPIC' code, but does not do so automatically when - linking non-PIC code. This option requests the new PLT and GOT - layout. A warning will be given if some object file requires the - old style BSS PLT. - -'--sdata-got' - The new secure PLT and GOT are placed differently relative to other - sections compared to older BSS PLT and GOT placement. The location - of '.plt' must change because the new secure PLT is an initialized - section while the old PLT is uninitialized. The reason for the - '.got' change is more subtle: The new placement allows '.got' to be - read-only in applications linked with '-z relro -z now'. However, - this placement means that '.sdata' cannot always be used in shared - libraries, because the PowerPC ABI accesses '.sdata' in shared - libraries from the GOT pointer. '--sdata-got' forces the old GOT - placement. PowerPC GCC doesn't use '.sdata' in shared libraries, - so this option is really only useful for other compilers that may - do so. - -'--emit-stub-syms' - This option causes 'ld' to label linker stubs with a local symbol - that encodes the stub type and destination. - -'--no-tls-optimize' - PowerPC 'ld' normally performs some optimization of code sequences - used to access Thread-Local Storage. Use this option to disable - the optimization. - -4.9 'ld' and PowerPC64 64-bit ELF Support -========================================= - -'--stub-group-size' - Long branch stubs, PLT call stubs and TOC adjusting stubs are - placed by 'ld' in stub sections located between groups of input - sections. '--stub-group-size' specifies the maximum size of a - group of input sections handled by one stub section. Since branch - offsets are signed, a stub section may serve two groups of input - sections, one group before the stub section, and one group after - it. However, when using conditional branches that require stubs, - it may be better (for branch prediction) that stub sections only - serve one group of input sections. A negative value for 'N' - chooses this scheme, ensuring that branches to stubs always use a - negative offset. Two special values of 'N' are recognized, '1' and - '-1'. These both instruct 'ld' to automatically size input section - groups for the branch types detected, with the same behaviour - regarding stub placement as other positive or negative values of - 'N' respectively. - - Note that '--stub-group-size' does not split input sections. A - single input section larger than the group size specified will of - course create a larger group (of one section). If input sections - are too large, it may not be possible for a branch to reach its - stub. - -'--emit-stub-syms' - This option causes 'ld' to label linker stubs with a local symbol - that encodes the stub type and destination. - -'--dotsyms, --no-dotsyms' - These two options control how 'ld' interprets version patterns in a - version script. Older PowerPC64 compilers emitted both a function - descriptor symbol with the same name as the function, and a code - entry symbol with the name prefixed by a dot ('.'). To properly - version a function 'foo', the version script thus needs to control - both 'foo' and '.foo'. The option '--dotsyms', on by default, - automatically adds the required dot-prefixed patterns. Use - '--no-dotsyms' to disable this feature. - -'--no-tls-optimize' - PowerPC64 'ld' normally performs some optimization of code - sequences used to access Thread-Local Storage. Use this option to - disable the optimization. - -'--no-opd-optimize' - PowerPC64 'ld' normally removes '.opd' section entries - corresponding to deleted link-once functions, or functions removed - by the action of '--gc-sections' or linker scrip '/DISCARD/'. Use - this option to disable '.opd' optimization. - -'--non-overlapping-opd' - Some PowerPC64 compilers have an option to generate compressed - '.opd' entries spaced 16 bytes apart, overlapping the third word, - the static chain pointer (unused in C) with the first word of the - next entry. This option expands such entries to the full 24 bytes. - -'--no-toc-optimize' - PowerPC64 'ld' normally removes unused '.toc' section entries. - Such entries are detected by examining relocations that reference - the TOC in code sections. A reloc in a deleted code section marks - a TOC word as unneeded, while a reloc in a kept code section marks - a TOC word as needed. Since the TOC may reference itself, TOC - relocs are also examined. TOC words marked as both needed and - unneeded will of course be kept. TOC words without any referencing - reloc are assumed to be part of a multi-word entry, and are kept or - discarded as per the nearest marked preceding word. This works - reliably for compiler generated code, but may be incorrect if - assembly code is used to insert TOC entries. Use this option to - disable the optimization. - -'--no-multi-toc' - By default, PowerPC64 GCC generates code for a TOC model where TOC - entries are accessed with a 16-bit offset from r2. This limits the - total TOC size to 64K. PowerPC64 'ld' extends this limit by - grouping code sections such that each group uses less than 64K for - its TOC entries, then inserts r2 adjusting stubs between - inter-group calls. 'ld' does not split apart input sections, so - cannot help if a single input file has a '.toc' section that - exceeds 64K, most likely from linking multiple files with 'ld -r'. - Use this option to turn off this feature. - -4.10 'ld' and SPU ELF Support -============================= - -'--plugin' - This option marks an executable as a PIC plugin module. - -'--no-overlays' - Normally, 'ld' recognizes calls to functions within overlay - regions, and redirects such calls to an overlay manager via a stub. - 'ld' also provides a built-in overlay manager. This option turns - off all this special overlay handling. - -'--emit-stub-syms' - This option causes 'ld' to label overlay stubs with a local symbol - that encodes the stub type and destination. - -'--extra-overlay-stubs' - This option causes 'ld' to add overlay call stubs on all function - calls out of overlay regions. Normally stubs are not added on - calls to non-overlay regions. - -'--local-store=lo:hi' - 'ld' usually checks that a final executable for SPU fits in the - address range 0 to 256k. This option may be used to change the - range. Disable the check entirely with '--local-store=0:0'. - -'--stack-analysis' - SPU local store space is limited. Over-allocation of stack space - unnecessarily limits space available for code and data, while - under-allocation results in runtime failures. If given this - option, 'ld' will provide an estimate of maximum stack usage. 'ld' - does this by examining symbols in code sections to determine the - extents of functions, and looking at function prologues for stack - adjusting instructions. A call-graph is created by looking for - relocations on branch instructions. The graph is then searched for - the maximum stack usage path. Note that this analysis does not - find calls made via function pointers, and does not handle - recursion and other cycles in the call graph. Stack usage may be - under-estimated if your code makes such calls. Also, stack usage - for dynamic allocation, e.g. alloca, will not be detected. If a - link map is requested, detailed information about each function's - stack usage and calls will be given. - -'--emit-stack-syms' - This option, if given along with '--stack-analysis' will result in - 'ld' emitting stack sizing symbols for each function. These take - the form '__stack_<function_name>' for global functions, and - '__stack_<number>_<function_name>' for static functions. - '<number>' is the section id in hex. The value of such symbols is - the stack requirement for the corresponding function. The symbol - size will be zero, type 'STT_NOTYPE', binding 'STB_LOCAL', and - section 'SHN_ABS'. - -4.11 'ld''s Support for Various TI COFF Versions -================================================ - -The '--format' switch allows selection of one of the various TI COFF -versions. The latest of this writing is 2; versions 0 and 1 are also -supported. The TI COFF versions also vary in header byte-order format; -'ld' will read any version or byte order, but the output header format -depends on the default specified by the specific target. - -4.12 'ld' and WIN32 (cygwin/mingw) -================================== - -This section describes some of the win32 specific 'ld' issues. See -*note Command Line Options: Options. for detailed description of the -command line options mentioned here. - -_import libraries_ - The standard Windows linker creates and uses so-called import - libraries, which contains information for linking to dll's. They - are regular static archives and are handled as any other static - archive. The cygwin and mingw ports of 'ld' have specific support - for creating such libraries provided with the '--out-implib' - command line option. - -_exporting DLL symbols_ - The cygwin/mingw 'ld' has several ways to export symbols for dll's. - - _using auto-export functionality_ - By default 'ld' exports symbols with the auto-export - functionality, which is controlled by the following command - line options: - - * -export-all-symbols [This is the default] - * -exclude-symbols - * -exclude-libs - - If, however, '--export-all-symbols' is not given explicitly on - the command line, then the default auto-export behavior will - be _disabled_ if either of the following are true: - - * A DEF file is used. - * Any symbol in any object file was marked with the - __declspec(dllexport) attribute. - - _using a DEF file_ - Another way of exporting symbols is using a DEF file. A DEF - file is an ASCII file containing definitions of symbols which - should be exported when a dll is created. Usually it is named - '<dll name>.def' and is added as any other object file to the - linker's command line. The file's name must end in '.def' or - '.DEF'. - - gcc -o <output> <objectfiles> <dll name>.def - - Using a DEF file turns off the normal auto-export behavior, - unless the '--export-all-symbols' option is also used. - - Here is an example of a DEF file for a shared library called - 'xyz.dll': - - LIBRARY "xyz.dll" BASE=0x20000000 - - EXPORTS - foo - bar - _bar = bar - another_foo = abc.dll.afoo - var1 DATA - - This example defines a DLL with a non-default base address and - five symbols in the export table. The third exported symbol - '_bar' is an alias for the second. The fourth symbol, - 'another_foo' is resolved by "forwarding" to another module - and treating it as an alias for 'afoo' exported from the DLL - 'abc.dll'. The final symbol 'var1' is declared to be a data - object. - - The optional 'LIBRARY <name>' command indicates the _internal_ - name of the output DLL. If '<name>' does not include a suffix, - the default library suffix, '.DLL' is appended. - - When the .DEF file is used to build an application, rather - than a library, the 'NAME <name>' command should be used - instead of 'LIBRARY'. If '<name>' does not include a suffix, - the default executable suffix, '.EXE' is appended. - - With either 'LIBRARY <name>' or 'NAME <name>' the optional - specification 'BASE = <number>' may be used to specify a - non-default base address for the image. - - If neither 'LIBRARY <name>' nor 'NAME <name>' is specified, or - they specify an empty string, the internal name is the same as - the filename specified on the command line. - - The complete specification of an export symbol is: - - EXPORTS - ( ( ( <name1> [ = <name2> ] ) - | ( <name1> = <module-name> . <external-name>)) - [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * - - Declares '<name1>' as an exported symbol from the DLL, or - declares '<name1>' as an exported alias for '<name2>'; or - declares '<name1>' as a "forward" alias for the symbol - '<external-name>' in the DLL '<module-name>'. Optionally, the - symbol may be exported by the specified ordinal '<integer>' - alias. - - The optional keywords that follow the declaration indicate: - - 'NONAME': Do not put the symbol name in the DLL's export - table. It will still be exported by its ordinal alias (either - the value specified by the .def specification or, otherwise, - the value assigned by the linker). The symbol name, however, - does remain visible in the import library (if any), unless - 'PRIVATE' is also specified. - - 'DATA': The symbol is a variable or object, rather than a - function. The import lib will export only an indirect - reference to 'foo' as the symbol '_imp__foo' (ie, 'foo' must - be resolved as '*_imp__foo'). - - 'CONSTANT': Like 'DATA', but put the undecorated 'foo' as well - as '_imp__foo' into the import library. Both refer to the - read-only import address table's pointer to the variable, not - to the variable itself. This can be dangerous. If the user - code fails to add the 'dllimport' attribute and also fails to - explicitly add the extra indirection that the use of the - attribute enforces, the application will behave unexpectedly. - - 'PRIVATE': Put the symbol in the DLL's export table, but do - not put it into the static import library used to resolve - imports at link time. The symbol can still be imported using - the 'LoadLibrary/GetProcAddress' API at runtime or by by using - the GNU ld extension of linking directly to the DLL without an - import library. - - See ld/deffilep.y in the binutils sources for the full - specification of other DEF file statements - - While linking a shared dll, 'ld' is able to create a DEF file - with the '--output-def <file>' command line option. - - _Using decorations_ - Another way of marking symbols for export is to modify the - source code itself, so that when building the DLL each symbol - to be exported is declared as: - - __declspec(dllexport) int a_variable - __declspec(dllexport) void a_function(int with_args) - - All such symbols will be exported from the DLL. If, however, - any of the object files in the DLL contain symbols decorated - in this way, then the normal auto-export behavior is disabled, - unless the '--export-all-symbols' option is also used. - - Note that object files that wish to access these symbols must - _not_ decorate them with dllexport. Instead, they should use - dllimport, instead: - - __declspec(dllimport) int a_variable - __declspec(dllimport) void a_function(int with_args) - - This complicates the structure of library header files, - because when included by the library itself the header must - declare the variables and functions as dllexport, but when - included by client code the header must declare them as - dllimport. There are a number of idioms that are typically - used to do this; often client code can omit the __declspec() - declaration completely. See '--enable-auto-import' and - 'automatic data imports' for more information. - -_automatic data imports_ - The standard Windows dll format supports data imports from dlls - only by adding special decorations (dllimport/dllexport), which let - the compiler produce specific assembler instructions to deal with - this issue. This increases the effort necessary to port existing - Un*x code to these platforms, especially for large c++ libraries - and applications. The auto-import feature, which was initially - provided by Paul Sokolovsky, allows one to omit the decorations to - achieve a behavior that conforms to that on POSIX/Un*x platforms. - This feature is enabled with the '--enable-auto-import' - command-line option, although it is enabled by default on - cygwin/mingw. The '--enable-auto-import' option itself now serves - mainly to suppress any warnings that are ordinarily emitted when - linked objects trigger the feature's use. - - auto-import of variables does not always work flawlessly without - additional assistance. Sometimes, you will see this message - - "variable '<var>' can't be auto-imported. Please read the - documentation for ld's '--enable-auto-import' for details." - - The '--enable-auto-import' documentation explains why this error - occurs, and several methods that can be used to overcome this - difficulty. One of these methods is the _runtime pseudo-relocs_ - feature, described below. - - For complex variables imported from DLLs (such as structs or - classes), object files typically contain a base address for the - variable and an offset (_addend_) within the variable-to specify a - particular field or public member, for instance. Unfortunately, - the runtime loader used in win32 environments is incapable of - fixing these references at runtime without the additional - information supplied by dllimport/dllexport decorations. The - standard auto-import feature described above is unable to resolve - these references. - - The '--enable-runtime-pseudo-relocs' switch allows these references - to be resolved without error, while leaving the task of adjusting - the references themselves (with their non-zero addends) to - specialized code provided by the runtime environment. Recent - versions of the cygwin and mingw environments and compilers provide - this runtime support; older versions do not. However, the support - is only necessary on the developer's platform; the compiled result - will run without error on an older system. - - '--enable-runtime-pseudo-relocs' is not the default; it must be - explicitly enabled as needed. - -_direct linking to a dll_ - The cygwin/mingw ports of 'ld' support the direct linking, - including data symbols, to a dll without the usage of any import - libraries. This is much faster and uses much less memory than does - the traditional import library method, especially when linking - large libraries or applications. When 'ld' creates an import lib, - each function or variable exported from the dll is stored in its - own bfd, even though a single bfd could contain many exports. The - overhead involved in storing, loading, and processing so many bfd's - is quite large, and explains the tremendous time, memory, and - storage needed to link against particularly large or complex - libraries when using import libs. - - Linking directly to a dll uses no extra command-line switches other - than '-L' and '-l', because 'ld' already searches for a number of - names to match each library. All that is needed from the - developer's perspective is an understanding of this search, in - order to force ld to select the dll instead of an import library. - - For instance, when ld is called with the argument '-lxxx' it will - attempt to find, in the first directory of its search path, - - libxxx.dll.a - xxx.dll.a - libxxx.a - xxx.lib - cygxxx.dll (*) - libxxx.dll - xxx.dll - - before moving on to the next directory in the search path. - - (*) Actually, this is not 'cygxxx.dll' but in fact is - '<prefix>xxx.dll', where '<prefix>' is set by the 'ld' option - '--dll-search-prefix=<prefix>'. In the case of cygwin, the - standard gcc spec file includes '--dll-search-prefix=cyg', so in - effect we actually search for 'cygxxx.dll'. - - Other win32-based unix environments, such as mingw or pw32, may use - other '<prefix>'es, although at present only cygwin makes use of - this feature. It was originally intended to help avoid name - conflicts among dll's built for the various win32/un*x - environments, so that (for example) two versions of a zlib dll - could coexist on the same machine. - - The generic cygwin/mingw path layout uses a 'bin' directory for - applications and dll's and a 'lib' directory for the import - libraries (using cygwin nomenclature): - - bin/ - cygxxx.dll - lib/ - libxxx.dll.a (in case of dll's) - libxxx.a (in case of static archive) - - Linking directly to a dll without using the import library can be - done two ways: - - 1. Use the dll directly by adding the 'bin' path to the link line - gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx - - However, as the dll's often have version numbers appended to their - names ('cygncurses-5.dll') this will often fail, unless one - specifies '-L../bin -lncurses-5' to include the version. Import - libs are generally not versioned, and do not have this difficulty. - - 2. Create a symbolic link from the dll to a file in the 'lib' - directory according to the above mentioned search pattern. This - should be used to avoid unwanted changes in the tools needed for - making the app/dll. - - ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] - - Then you can link without any make environment changes. - - gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx - - This technique also avoids the version number problems, because the - following is perfectly legal - - bin/ - cygxxx-5.dll - lib/ - libxxx.dll.a -> ../bin/cygxxx-5.dll - - Linking directly to a dll without using an import lib will work - even when auto-import features are exercised, and even when - '--enable-runtime-pseudo-relocs' is used. - - Given the improvements in speed and memory usage, one might - justifiably wonder why import libraries are used at all. There are - three reasons: - - 1. Until recently, the link-directly-to-dll functionality did - _not_ work with auto-imported data. - - 2. Sometimes it is necessary to include pure static objects within - the import library (which otherwise contains only bfd's for - indirection symbols that point to the exports of a dll). Again, - the import lib for the cygwin kernel makes use of this ability, and - it is not possible to do this without an import lib. - - 3. Symbol aliases can only be resolved using an import lib. This - is critical when linking against OS-supplied dll's (eg, the win32 - API) in which symbols are usually exported as undecorated aliases - of their stdcall-decorated assembly names. - - So, import libs are not going away. But the ability to replace - true import libs with a simple symbolic link to (or a copy of) a - dll, in many cases, is a useful addition to the suite of tools - binutils makes available to the win32 developer. Given the massive - improvements in memory requirements during linking, storage - requirements, and linking speed, we expect that many developers - will soon begin to use this feature whenever possible. - -_symbol aliasing_ - _adding additional names_ - Sometimes, it is useful to export symbols with additional - names. A symbol 'foo' will be exported as 'foo', but it can - also be exported as '_foo' by using special directives in the - DEF file when creating the dll. This will affect also the - optional created import library. Consider the following DEF - file: - - LIBRARY "xyz.dll" BASE=0x61000000 - - EXPORTS - foo - _foo = foo - - The line '_foo = foo' maps the symbol 'foo' to '_foo'. - - Another method for creating a symbol alias is to create it in - the source code using the "weak" attribute: - - void foo () { /* Do something. */; } - void _foo () __attribute__ ((weak, alias ("foo"))); - - See the gcc manual for more information about attributes and - weak symbols. - - _renaming symbols_ - Sometimes it is useful to rename exports. For instance, the - cygwin kernel does this regularly. A symbol '_foo' can be - exported as 'foo' but not as '_foo' by using special - directives in the DEF file. (This will also affect the import - library, if it is created). In the following example: - - LIBRARY "xyz.dll" BASE=0x61000000 - - EXPORTS - _foo = foo - - The line '_foo = foo' maps the exported symbol 'foo' to - '_foo'. - - Note: using a DEF file disables the default auto-export behavior, - unless the '--export-all-symbols' command line option is used. If, - however, you are trying to rename symbols, then you should list - _all_ desired exports in the DEF file, including the symbols that - are not being renamed, and do _not_ use the '--export-all-symbols' - option. If you list only the renamed symbols in the DEF file, and - use '--export-all-symbols' to handle the other symbols, then the - both the new names _and_ the original names for the renamed symbols - will be exported. In effect, you'd be aliasing those symbols, not - renaming them, which is probably not what you wanted. - -_weak externals_ - The Windows object format, PE, specifies a form of weak symbols - called weak externals. When a weak symbol is linked and the symbol - is not defined, the weak symbol becomes an alias for some other - symbol. There are three variants of weak externals: - * Definition is searched for in objects and libraries, - historically called lazy externals. - * Definition is searched for only in other objects, not in - libraries. This form is not presently implemented. - * No search; the symbol is an alias. This form is not presently - implemented. - As a GNU extension, weak symbols that do not specify an alternate - symbol are supported. If the symbol is undefined when linking, the - symbol uses a default value. - -4.13 'ld' and Xtensa Processors -=============================== - -The default 'ld' behavior for Xtensa processors is to interpret -'SECTIONS' commands so that lists of explicitly named sections in a -specification with a wildcard file will be interleaved when necessary to -keep literal pools within the range of PC-relative load offsets. For -example, with the command: - - SECTIONS - { - .text : { - *(.literal .text) - } - } - -'ld' may interleave some of the '.literal' and '.text' sections from -different object files to ensure that the literal pools are within the -range of PC-relative load offsets. A valid interleaving might place the -'.literal' sections from an initial group of files followed by the -'.text' sections of that group of files. Then, the '.literal' sections -from the rest of the files and the '.text' sections from the rest of the -files would follow. - - Relaxation is enabled by default for the Xtensa version of 'ld' and -provides two important link-time optimizations. The first optimization -is to combine identical literal values to reduce code size. A redundant -literal will be removed and all the 'L32R' instructions that use it will -be changed to reference an identical literal, as long as the location of -the replacement literal is within the offset range of all the 'L32R' -instructions. The second optimization is to remove unnecessary overhead -from assembler-generated "longcall" sequences of 'L32R'/'CALLXN' when -the target functions are within range of direct 'CALLN' instructions. - - For each of these cases where an indirect call sequence can be -optimized to a direct call, the linker will change the 'CALLXN' -instruction to a 'CALLN' instruction, remove the 'L32R' instruction, and -remove the literal referenced by the 'L32R' instruction if it is not -used for anything else. Removing the 'L32R' instruction always reduces -code size but can potentially hurt performance by changing the alignment -of subsequent branch targets. By default, the linker will always -preserve alignments, either by switching some instructions between -24-bit encodings and the equivalent density instructions or by inserting -a no-op in place of the 'L32R' instruction that was removed. If code -size is more important than performance, the '--size-opt' option can be -used to prevent the linker from widening density instructions or -inserting no-ops, except in a few cases where no-ops are required for -correctness. - - The following Xtensa-specific command-line options can be used to -control the linker: - -'--no-relax' - Since the Xtensa version of 'ld' enables the '--relax' option by - default, the '--no-relax' option is provided to disable relaxation. - -'--size-opt' - When optimizing indirect calls to direct calls, optimize for code - size more than performance. With this option, the linker will not - insert no-ops or widen density instructions to preserve branch - target alignment. There may still be some cases where no-ops are - required to preserve the correctness of the code. - -5 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. To conserve runtime memory, however, the linker and -associated tools are usually configured to support only a subset of the -object file formats available. You can use 'objdump -i' (*note objdump: -(binutils.info)objdump.) to list all the formats available for your -configuration. - - 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::. - -5.1 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 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. - -5.1.1 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. - -5.1.2 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). - -6 Reporting Bugs -**************** - -Your bug reports play an essential role in making 'ld' reliable. - - Reporting a bug may help you by bringing a solution to your problem, -or it may not. But in any case the principal function of a bug report -is to help the entire community by making the next version of 'ld' work -better. Bug reports are your contribution to the maintenance of 'ld'. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -6.1 Have You Found a Bug? -========================= - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the linker gets a fatal signal, for any input whatever, that is - a 'ld' bug. Reliable linkers never crash. - - * If 'ld' produces an error message for valid input, that is a bug. - - * If 'ld' does not produce an error message for invalid input, that - may be a bug. In the general case, the linker can not verify that - object files are correct. - - * If you are an experienced user of linkers, your suggestions for - improvement of 'ld' are welcome in any case. - -6.2 How to Report Bugs -====================== - -A number of companies and individuals offer support for GNU products. -If you obtained 'ld' from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. - - The fundamental principle of reporting bugs usefully is this: *report -all the facts*. If you are not sure whether to state a fact or leave it -out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of a symbol you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is -a stray memory reference which happens to fetch from the location where -that name is stored in memory; perhaps, if the name were different, the -contents of that location would fool the linker into doing the right -thing despite the bug. Play it safe and give a specific, complete -example. That is the easiest thing for you to do, and the most helpful. - - Keep in mind that the purpose of a bug report is to enable us to fix -the bug if it is new to us. Therefore, always write your bug reports on -the assumption that the bug has not been reported previously. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" This cannot help us fix a bug, so it is basically useless. We -respond by asking for enough details to enable us to investigate. You -might as well expedite matters by sending them to begin with. - - To enable us to fix the bug, you should include all these things: - - * The version of 'ld'. 'ld' announces it if you start it with the - '--version' argument. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of 'ld'. - - * Any patches you may have applied to the 'ld' source, including any - patches made to the 'BFD' library. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile 'ld'--e.g. - "'gcc-2.7'". - - * The command arguments you gave the linker to link your example and - observe the bug. To guarantee you will not omit something - important, list them all. A copy of the Makefile (or the output - from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input file, or set of input files, that will reproduce - the bug. It is generally most helpful to send the actual object - files provided that they are reasonably small. Say no more than - 10K. For bigger files you can either make them available by FTP or - HTTP or else state that you are willing to send the object file(s) - to whomever requests them. (Note - your email will be going to a - mailing list, so we do not want to clog it up with large - attachments). But small attachments are best. - - If the source files were assembled using 'gas' or compiled using - 'gcc', then it may be OK to send the source files rather than the - object files. In this case, be sure to say exactly what version of - 'gas' or 'gcc' was used to produce the object files. Also say how - 'gas' or 'gcc' were configured. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that 'ld' gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - Even if the problem you experience is a fatal signal, you should - still say so explicitly. Suppose something strange is going on, - such as, your copy of 'ld' is out of sync, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the 'ld' source, send us context - diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. - Always send diffs from the old file to the new file. If you even - discuss something in the 'ld' source, refer to it by context, not - by line number. - - The line numbers in our development sources will not match those in - your sources. Your line numbers would convey no useful information - to us. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - Often people who encounter a bug spend a lot of time investigating - which changes to the input file will make the bug go away and which - changes will not affect it. - - This is often time consuming and not very useful, because the way - we will find the bug is by running a single example under the - debugger with breakpoints, not by pure deduction from a series of - examples. We recommend that you save your time for something else. - - Of course, if you can find a simpler example to report _instead_ of - the original one, that is a convenience for us. Errors in the - output will be easier to spot, running under the debugger will take - less time, and so on. - - However, simplification is not vital; if you do not want to do - this, report the bug anyway and send us the entire test case you - used. - - * A patch for the bug. - - A patch for the bug does help us if it is a good one. But do not - omit the necessary information, such as the test case, on the - assumption that a patch is all we need. We might see problems with - your patch and decide to fix the problem another way, or we might - not understand it at all. - - Sometimes with a program as complicated as 'ld' it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify that - the bug is fixed. - - And if we cannot understand what bug you are trying to fix, or why - your patch should be an improvement, we will not install it. A - test case will help us to understand. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - -Appendix A 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 Scripts::. -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. - -'ALIGN SECNAME = EXPRESSION' - Align the section called SECNAME to EXPRESSION. The EXPRESSION - should be a power of two. - -'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. - -Appendix B GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000, 2003 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. We - recommend this License principally for works whose purpose is - instruction or reference. - - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (For example, if the - Document is in part a textbook of mathematics, a Secondary Section - may not explain any mathematics.) The relationship could be a - matter of historical connection with the subject or with related - matters, or of legal, commercial, philosophical, ethical or - political position regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed to - thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque." - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and standard-conforming - simple HTML designed for human modification. Opaque formats - include PostScript, PDF, proprietary formats that can be read and - edited only by proprietary word processors, SGML or XML for which - the DTD and/or processing tools are not generally available, and - the machine-generated HTML produced by some word processors for - output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow the - conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies of the Document numbering more than - 100, and the Document's license notice requires Cover Texts, you - must enclose the copies in covers that carry, clearly and legibly, - all these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the title - equally prominent and visible. You may add other material on the - covers in addition. Copying with changes limited to the covers, as - long as they preserve the title of the Document and satisfy these - conditions, can be treated as verbatim copying in other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a machine-readable - Transparent copy along with each Opaque copy, or state in or with - each Opaque copy a publicly-accessible computer-network location - containing a complete Transparent copy of the Document, free of - added material, which the general network-using public has access - to download anonymously at no charge using public-standard network - protocols. If you use the latter option, you must take reasonably - prudent steps, when you begin distribution of Opaque copies in - quantity, to ensure that this Transparent copy will remain thus - accessible at the stated location until at least one year after the - last time you distribute an Opaque copy (directly or through your - agents or retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of copies, - to give them a chance to provide you with an updated version of the - Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus licensing - distribution and modification of the Modified Version to whoever - possesses a copy of it. In addition, you must do these things in - the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the History - section of the Document). You may use the same title as a previous - version if the original publisher of that version gives permission. - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in the - Modified Version, together with at least five of the principal - authors of the Document (all of its principal authors, if it has - less than five). - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - D. Preserve all the copyright notices of the Document. - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified Version - under the terms of this License, in the form shown in the Addendum - below. - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements." Such a section may - not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option designate - some or all of these sections as invariant. To do this, add their - titles to the list of Invariant Sections in the Modified Version's - license notice. These titles must be distinct from any other - section titles. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of - a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end of - the list of Cover Texts in the Modified Version. Only one passage - of Front-Cover Text and one of Back-Cover Text may be added by (or - through arrangements made by) any one entity. If the Document - already includes a cover text for the same cover, previously added - by you or by arrangement made by the same entity you are acting on - behalf of, you may not add another; but you may replace the old - one, on explicit permission from the previous publisher that added - the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination all - of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications." You - must delete all sections entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the documents - in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow this - License in all other respects regarding verbatim copying of that - document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation copyright - is claimed for the compilation. Such a compilation is called an - "aggregate", and this License does not apply to the other - self-contained works thus compiled with the Document, on account of - their being thus compiled, if they are not themselves derivative - works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document 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. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation 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. See - http://www.gnu.org/copyleft/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the GNU General Public License, to permit -their use in free software. - -LD Index -******** - -* Menu: - -* ": Symbols. (line 3620) -* -(: Options. (line 756) -* --accept-unknown-input-arch: Options. (line 774) -* --add-needed: Options. (line 796) -* --add-stdcall-alias: Options. (line 1532) -* --allow-multiple-definition: Options. (line 1004) -* --allow-shlib-undefined: Options. (line 1010) -* --architecture=ARCH: Options. (line 227) -* --as-needed: Options. (line 784) -* --auxiliary: Options. (line 328) -* --bank-window: Options. (line 1867) -* --base-file: Options. (line 1537) -* --be8: ARM. (line 4205) -* --bss-plt: PowerPC ELF32. (line 4376) -* --check-sections: Options. (line 877) -* --cref: Options. (line 887) -* --default-imported-symver: Options. (line 1038) -* --default-script=SCRIPT: Options. (line 601) -* --default-symver: Options. (line 1034) -* --defsym SYMBOL=EXP: Options. (line 915) -* --demangle[=STYLE]: Options. (line 928) -* --disable-auto-image-base: Options. (line 1682) -* --disable-auto-import: Options. (line 1810) -* --disable-new-dtags: Options. (line 1479) -* --disable-runtime-pseudo-reloc: Options. (line 1823) -* --disable-stdcall-fixup: Options. (line 1547) -* --discard-all: Options. (line 647) -* --discard-locals: Options. (line 651) -* --dll: Options. (line 1542) -* --dll-search-prefix: Options. (line 1688) -* --dotsyms: PowerPC64 ELF64. (line 4446) -* --dynamic-linker FILE: Options. (line 941) -* --dynamic-list-cpp-new: Options. (line 869) -* --dynamic-list-cpp-typeinfo: Options. (line 873) -* --dynamic-list-data: Options. (line 866) -* --dynamic-list=DYNAMIC-LIST-FILE: Options. (line 853) -* --eh-frame-hdr: Options. (line 1475) -* --emit-relocs: Options. (line 537) -* --emit-stack-syms: SPU ELF. (line 4541) -* --emit-stub-syms: PowerPC ELF32. (line 4407) -* --emit-stub-syms <1>: PowerPC64 ELF64. (line 4442) -* --emit-stub-syms <2>: SPU ELF. (line 4510) -* --enable-auto-image-base: Options. (line 1674) -* --enable-auto-import: Options. (line 1697) -* --enable-extra-pe-debug: Options. (line 1828) -* --enable-new-dtags: Options. (line 1479) -* --enable-runtime-pseudo-reloc: Options. (line 1815) -* --enable-stdcall-fixup: Options. (line 1547) -* --entry=ENTRY: Options. (line 281) -* --error-unresolved-symbols: Options. (line 1428) -* --exclude-libs: Options. (line 291) -* --exclude-symbols: Options. (line 1588) -* --export-all-symbols: Options. (line 1564) -* --export-dynamic: Options. (line 302) -* --extra-overlay-stubs: SPU ELF. (line 4514) -* --fatal-warnings: Options. (line 947) -* --file-alignment: Options. (line 1594) -* --filter: Options. (line 349) -* --fix-v4bx: ARM. (line 4224) -* --force-dynamic: Options. (line 546) -* --force-exe-suffix: Options. (line 950) -* --format=FORMAT: Options. (line 238) -* --format=VERSION: TI COFF. (line 4554) -* --gc-sections: Options. (line 960) -* --gpsize: Options. (line 381) -* --hash-size=NUMBER: Options. (line 1488) -* --hash-style=STYLE: Options. (line 1496) -* --heap: Options. (line 1600) -* --help: Options. (line 977) -* --image-base: Options. (line 1607) -* --just-symbols=FILE: Options. (line 568) -* --kill-at: Options. (line 1616) -* --large-address-aware: Options. (line 1621) -* --library-path=DIR: Options. (line 440) -* --library=NAMESPEC: Options. (line 407) -* --local-store=lo:hi: SPU ELF. (line 4519) -* --major-image-version: Options. (line 1630) -* --major-os-version: Options. (line 1635) -* --major-subsystem-version: Options. (line 1639) -* --minor-image-version: Options. (line 1644) -* --minor-os-version: Options. (line 1649) -* --minor-subsystem-version: Options. (line 1653) -* --mri-script=MRI-CMDFILE: Options. (line 262) -* --multi-subspace: HPPA ELF32. (line 4285) -* --nmagic: Options. (line 506) -* --no-accept-unknown-input-arch: Options. (line 774) -* --no-add-needed: Options. (line 796) -* --no-allow-shlib-undefined: Options. (line 1010) -* --no-as-needed: Options. (line 784) -* --no-check-sections: Options. (line 877) -* --no-define-common: Options. (line 899) -* --no-demangle: Options. (line 928) -* --no-dotsyms: PowerPC64 ELF64. (line 4446) -* --no-enum-size-warning: ARM. (line 4275) -* --no-gc-sections: Options. (line 960) -* --no-keep-memory: Options. (line 989) -* --no-multi-toc: PowerPC64 ELF64. (line 4487) -* --no-omagic: Options. (line 520) -* --no-opd-optimize: PowerPC64 ELF64. (line 4461) -* --no-overlays: SPU ELF. (line 4504) -* --no-print-gc-sections: Options. (line 968) -* --no-relax: Xtensa. (line 5005) -* --no-tls-optimize: PowerPC ELF32. (line 4411) -* --no-tls-optimize <1>: PowerPC64 ELF64. (line 4456) -* --no-toc-optimize: PowerPC64 ELF64. (line 4473) -* --no-trampoline: Options. (line 1861) -* --no-undefined: Options. (line 996) -* --no-undefined-version: Options. (line 1029) -* --no-warn-mismatch: Options. (line 1042) -* --no-warn-search-mismatch: Options. (line 1051) -* --no-whole-archive: Options. (line 1055) -* --noinhibit-exec: Options. (line 1059) -* --non-overlapping-opd: PowerPC64 ELF64. (line 4467) -* --oformat: Options. (line 1070) -* --omagic: Options. (line 511) -* --out-implib: Options. (line 1666) -* --output-def: Options. (line 1658) -* --output=OUTPUT: Options. (line 526) -* --pic-executable: Options. (line 1083) -* --pic-veneer: M68HC11/68HC12. (line 4180) -* --plugin: SPU ELF. (line 4501) -* --print-gc-sections: Options. (line 968) -* --print-map: Options. (line 472) -* --reduce-memory-overheads: Options. (line 1502) -* --relax: Options. (line 1099) -* '--relax' on i960: i960. (line 4138) -* --relax on PowerPC: PowerPC ELF32. (line 4369) -* '--relax' on Xtensa: Xtensa. (line 4977) -* --relocatable: Options. (line 550) -* --script=SCRIPT: Options. (line 592) -* --sdata-got: PowerPC ELF32. (line 4393) -* --section-alignment: Options. (line 1833) -* --section-start SECTIONNAME=ORG: Options. (line 1265) -* --secure-plt: PowerPC ELF32. (line 4386) -* --sort-common: Options. (line 1212) -* --sort-section alignment: Options. (line 1222) -* --sort-section name: Options. (line 1218) -* --split-by-file: Options. (line 1226) -* --split-by-reloc: Options. (line 1231) -* --stack: Options. (line 1839) -* --stack-analysis: SPU ELF. (line 4524) -* --stats: Options. (line 1244) -* --strip-all: Options. (line 579) -* --strip-debug: Options. (line 583) -* --stub-group-size: PowerPC64 ELF64. (line 4419) -* --stub-group-size=N: HPPA ELF32. (line 4291) -* --subsystem: Options. (line 1846) -* --support-old-code: ARM. (line 4188) -* --sysroot: Options. (line 1248) -* --target-help: Options. (line 981) -* --target1-abs: ARM. (line 4209) -* --target1-rel: ARM. (line 4209) -* --target2=TYPE: ARM. (line 4214) -* --thumb-entry=ENTRY: ARM. (line 4199) -* --trace: Options. (line 588) -* --trace-symbol=SYMBOL: Options. (line 657) -* --traditional-format: Options. (line 1253) -* --undefined=SYMBOL: Options. (line 614) -* --unique[=SECTION]: Options. (line 632) -* --unresolved-symbols: Options. (line 1280) -* --use-blx: ARM. (line 4237) -* --verbose: Options. (line 1309) -* --version: Options. (line 641) -* --version-script=VERSION-SCRIPTFILE: Options. (line 1315) -* --vfp11-denorm-fix: ARM. (line 4246) -* --warn-common: Options. (line 1322) -* --warn-constructors: Options. (line 1390) -* --warn-multiple-gp: Options. (line 1395) -* --warn-once: Options. (line 1409) -* --warn-section-align: Options. (line 1413) -* --warn-shared-textrel: Options. (line 1420) -* --warn-unresolved-symbols: Options. (line 1423) -* --whole-archive: Options. (line 1432) -* --wrap: Options. (line 1446) -* -AARCH: Options. (line 226) -* -aKEYWORD: Options. (line 219) -* -assert KEYWORD: Options. (line 806) -* -b FORMAT: Options. (line 238) -* -Bdynamic: Options. (line 809) -* -Bgroup: Options. (line 819) -* -Bshareable: Options. (line 1204) -* -Bstatic: Options. (line 826) -* -Bsymbolic: Options. (line 840) -* -Bsymbolic-functions: Options. (line 847) -* -c MRI-CMDFILE: Options. (line 262) -* -call_shared: Options. (line 809) -* -d: Options. (line 272) -* -dc: Options. (line 272) -* -dn: Options. (line 826) -* -dp: Options. (line 272) -* -dT SCRIPT: Options. (line 601) -* -dy: Options. (line 809) -* -E: Options. (line 302) -* -e ENTRY: Options. (line 281) -* -EB: Options. (line 321) -* -EL: Options. (line 324) -* -f: Options. (line 328) -* -F: Options. (line 349) -* -fini: Options. (line 372) -* -g: Options. (line 378) -* -G: Options. (line 381) -* -hNAME: Options. (line 389) -* -i: Options. (line 398) -* -IFILE: Options. (line 941) -* -init: Options. (line 401) -* -LDIR: Options. (line 440) -* -lNAMESPEC: Options. (line 407) -* -M: Options. (line 472) -* -m EMULATION: Options. (line 462) -* -Map: Options. (line 985) -* -n: Options. (line 506) -* -N: Options. (line 511) -* -non_shared: Options. (line 826) -* -nostdlib: Options. (line 1065) -* -O LEVEL: Options. (line 532) -* -o OUTPUT: Options. (line 526) -* -pie: Options. (line 1083) -* -q: Options. (line 537) -* -qmagic: Options. (line 1093) -* -Qy: Options. (line 1096) -* -r: Options. (line 550) -* -R FILE: Options. (line 568) -* -rpath: Options. (line 1134) -* -rpath-link: Options. (line 1156) -* -s: Options. (line 579) -* -S: Options. (line 583) -* -shared: Options. (line 1204) -* -soname=NAME: Options. (line 389) -* -static: Options. (line 826) -* -t: Options. (line 588) -* -T SCRIPT: Options. (line 592) -* -Tbss ORG: Options. (line 1274) -* -Tdata ORG: Options. (line 1274) -* -Ttext ORG: Options. (line 1274) -* -u SYMBOL: Options. (line 614) -* -Ur: Options. (line 622) -* -v: Options. (line 641) -* -V: Options. (line 641) -* -x: Options. (line 647) -* -X: Options. (line 651) -* -Y PATH: Options. (line 666) -* -y SYMBOL: Options. (line 657) -* -z defs: Options. (line 996) -* -z KEYWORD: Options. (line 670) -* -z muldefs: Options. (line 1004) -* .: Location Counter. (line 3650) -* /DISCARD/: Output Section Discarding. - (line 2932) -* :PHDR: Output Section Phdr. - (line 3065) -* =FILLEXP: Output Section Fill. - (line 3079) -* >REGION: Output Section Region. - (line 3055) -* [COMMON]: Input Section Common. - (line 2744) -* 'ABSOLUTE' (MRI): MRI. (line 5391) -* absolute and relocatable symbols: Expression Section. (line 3828) -* absolute expressions: Expression Section. (line 3828) -* ABSOLUTE(EXP): Builtin Functions. (line 3864) -* ADDR(SECTION): Builtin Functions. (line 3871) -* address, section: Output Section Address. - (line 2522) -* 'ALIAS' (MRI): MRI. (line 5402) -* 'ALIGN' (MRI): MRI. (line 5408) -* align expression: Builtin Functions. (line 3890) -* align location counter: Builtin Functions. (line 3890) -* ALIGN(ALIGN): Builtin Functions. (line 3890) -* ALIGN(EXP,ALIGN): Builtin Functions. (line 3890) -* ALIGN(SECTION_ALIGN): Forced Output Alignment. - (line 3043) -* ALIGNOF(SECTION): Builtin Functions. (line 3915) -* allocating memory: MEMORY. (line 3196) -* architecture: Miscellaneous Commands. - (line 2254) -* architectures: Options. (line 226) -* archive files, from cmd line: Options. (line 407) -* archive search path in linker script: File Commands. (line 2158) -* arithmetic: Expressions. (line 3591) -* arithmetic operators: Operators. (line 3773) -* ARM interworking support: ARM. (line 4188) -* ASSERT: Miscellaneous Commands. - (line 2217) -* assertion in linker script: Miscellaneous Commands. - (line 2217) -* assignment in scripts: Assignments. (line 2262) -* AS_NEEDED(FILES): File Commands. (line 2138) -* AT(LMA): Output Section LMA. (line 2983) -* AT>LMA_REGION: Output Section LMA. (line 2983) -* automatic data imports: WIN32. (line 4723) -* back end: BFD. (line 5019) -* 'BASE' (MRI): MRI. (line 5412) -* BE8: ARM. (line 4205) -* BFD canonical format: Canonical format. (line 5114) -* BFD requirements: BFD. (line 5029) -* big-endian objects: Options. (line 321) -* binary input format: Options. (line 238) -* BLOCK(EXP): Builtin Functions. (line 3928) -* bug criteria: Bug Criteria. (line 5201) -* bug reports: Bug Reporting. (line 5219) -* bugs in 'ld': Reporting Bugs. (line 5188) -* BYTE(EXPRESSION): Output Section Data. - (line 2788) -* C++ constructors, arranging in link: Output Section Keywords. - (line 2857) -* 'CHIP' (MRI): MRI. (line 5416) -* COLLECT_NO_DEMANGLE: Environment. (line 1899) -* combining symbols, warnings on: Options. (line 1322) -* command files: Scripts. (line 1908) -* command line: Options. (line 130) -* common allocation: Options. (line 272) -* common allocation <1>: Options. (line 899) -* common allocation in linker script: Miscellaneous Commands. - (line 2228) -* common allocation in linker script <1>: Miscellaneous Commands. - (line 2233) -* common symbol placement: Input Section Common. - (line 2721) -* compatibility, MRI: Options. (line 262) -* constants in linker scripts: Constants. (line 3604) -* constructors: Options. (line 622) -* CONSTRUCTORS: Output Section Keywords. - (line 2857) -* constructors, arranging in link: Output Section Keywords. - (line 2857) -* crash of linker: Bug Criteria. (line 5204) -* CREATE_OBJECT_SYMBOLS: Output Section Keywords. - (line 2847) -* creating a DEF file: WIN32. (line 4691) -* cross reference table: Options. (line 887) -* cross references: Miscellaneous Commands. - (line 2238) -* current output location: Location Counter. (line 3650) -* data: Output Section Data. - (line 2788) -* DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions. - (line 3933) -* DATA_SEGMENT_END(EXP): Builtin Functions. (line 3954) -* DATA_SEGMENT_RELRO_END(OFFSET, EXP): Builtin Functions. (line 3960) -* dbx: Options. (line 1258) -* DEF files, creating: Options. (line 1658) -* default emulation: Environment. (line 1891) -* default input format: Environment. (line 1879) -* DEFINED(SYMBOL): Builtin Functions. (line 3971) -* deleting local symbols: Options. (line 647) -* demangling, default: Environment. (line 1899) -* demangling, from command line: Options. (line 928) -* direct linking to a dll: WIN32. (line 4771) -* discarding sections: Output Section Discarding. - (line 2917) -* discontinuous memory: MEMORY. (line 3196) -* DLLs, creating: Options. (line 1564) -* DLLs, creating <1>: Options. (line 1658) -* DLLs, creating <2>: Options. (line 1666) -* DLLs, linking to: Options. (line 1688) -* dot: Location Counter. (line 3650) -* dot inside sections: Location Counter. (line 3680) -* dot outside sections: Location Counter. (line 3710) -* dynamic linker, from command line: Options. (line 941) -* dynamic symbol table: Options. (line 302) -* ELF program headers: PHDRS. (line 3293) -* emulation: Options. (line 462) -* emulation, default: Environment. (line 1891) -* 'END' (MRI): MRI. (line 5420) -* endianness: Options. (line 321) -* entry point: Entry Point. (line 2076) -* entry point, from command line: Options. (line 281) -* entry point, thumb: ARM. (line 4199) -* ENTRY(SYMBOL): Entry Point. (line 2076) -* error on valid input: Bug Criteria. (line 5207) -* example of linker script: Simple Example. (line 2005) -* exporting DLL symbols: WIN32. (line 4576) -* expression evaluation order: Evaluation. (line 3794) -* expression sections: Expression Section. (line 3828) -* expression, absolute: Builtin Functions. (line 3864) -* expressions: Expressions. (line 3591) -* EXTERN: Miscellaneous Commands. - (line 2221) -* fatal signal: Bug Criteria. (line 5204) -* file name wildcard patterns: Input Section Wildcards. - (line 2616) -* FILEHDR: PHDRS. (line 3348) -* filename symbols: Output Section Keywords. - (line 2847) -* fill pattern, entire section: Output Section Fill. - (line 3079) -* FILL(EXPRESSION): Output Section Data. - (line 2821) -* finalization function: Options. (line 372) -* first input file: File Commands. (line 2166) -* first instruction: Entry Point. (line 2076) -* FIX_V4BX: ARM. (line 4224) -* FORCE_COMMON_ALLOCATION: Miscellaneous Commands. - (line 2228) -* forcing input section alignment: Forced Input Alignment. - (line 3048) -* forcing output section alignment: Forced Output Alignment. - (line 3043) -* forcing the creation of dynamic sections: Options. (line 546) -* 'FORMAT' (MRI): MRI. (line 5424) -* functions in expressions: Builtin Functions. (line 3860) -* garbage collection: Options. (line 960) -* garbage collection <1>: Options. (line 968) -* garbage collection <2>: Input Section Keep. (line 2750) -* generating optimized output: Options. (line 532) -* GNU linker: Overview. (line 100) -* GNUTARGET: Environment. (line 1879) -* GROUP(FILES): File Commands. (line 2131) -* grouping input files: File Commands. (line 2131) -* groups of archives: Options. (line 756) -* H8/300 support: H8/300. (line 4078) -* header size: Builtin Functions. (line 4035) -* heap size: Options. (line 1600) -* help: Options. (line 977) -* holes: Location Counter. (line 3656) -* holes, filling: Output Section Data. - (line 2821) -* HPPA multiple sub-space stubs: HPPA ELF32. (line 4285) -* HPPA stub grouping: HPPA ELF32. (line 4291) -* i960 support: i960. (line 4112) -* image base: Options. (line 1607) -* implicit linker scripts: Implicit Linker Scripts. - (line 4054) -* import libraries: WIN32. (line 4567) -* INCLUDE FILENAME: File Commands. (line 2096) -* including a linker script: File Commands. (line 2096) -* including an entire archive: Options. (line 1432) -* incremental link: Options. (line 398) -* INHIBIT_COMMON_ALLOCATION: Miscellaneous Commands. - (line 2233) -* initialization function: Options. (line 401) -* initialized data in ROM: Output Section LMA. (line 3003) -* input file format in linker script: Format Commands. (line 2204) -* input filename symbols: Output Section Keywords. - (line 2847) -* input files in linker scripts: File Commands. (line 2103) -* input files, displaying: Options. (line 588) -* input format: Options. (line 238) -* input format <1>: Options. (line 238) -* input object files in linker scripts: File Commands. (line 2103) -* input section alignment: Forced Input Alignment. - (line 3048) -* input section basics: Input Section Basics. - (line 2568) -* input section wildcards: Input Section Wildcards. - (line 2616) -* input sections: Input Section. (line 2558) -* INPUT(FILES): File Commands. (line 2103) -* integer notation: Constants. (line 3604) -* integer suffixes: Constants. (line 3610) -* internal object-file format: Canonical format. (line 5114) -* invalid input: Bug Criteria. (line 5209) -* K and M integer suffixes: Constants. (line 3610) -* KEEP: Input Section Keep. (line 2750) -* l =: MEMORY. (line 3256) -* lazy evaluation: Evaluation. (line 3794) -* 'ld' bugs, reporting: Bug Reporting. (line 5219) -* LDEMULATION: Environment. (line 1891) -* len =: MEMORY. (line 3256) -* LENGTH =: MEMORY. (line 3256) -* LENGTH(MEMORY): Builtin Functions. (line 3988) -* library search path in linker script: File Commands. (line 2158) -* link map: Options. (line 472) -* link-time runtime library search path: Options. (line 1156) -* linker crash: Bug Criteria. (line 5204) -* linker script concepts: Basic Script Concepts. - (line 1935) -* linker script example: Simple Example. (line 2005) -* linker script file commands: File Commands. (line 2093) -* linker script format: Script Format. (line 1985) -* linker script input object files: File Commands. (line 2103) -* linker script simple commands: Simple Commands. (line 2071) -* linker scripts: Scripts. (line 1908) -* 'LIST' (MRI): MRI. (line 5435) -* little-endian objects: Options. (line 324) -* 'LOAD' (MRI): MRI. (line 5442) -* load address: Output Section LMA. (line 2983) -* LOADADDR(SECTION): Builtin Functions. (line 3991) -* loading, preventing: Output Section Type. - (line 2969) -* local symbols, deleting: Options. (line 651) -* location counter: Location Counter. (line 3650) -* LONG(EXPRESSION): Output Section Data. - (line 2788) -* M and K integer suffixes: Constants. (line 3610) -* M68HC11 and 68HC12 support: M68HC11/68HC12. (line 4148) -* machine architecture: Miscellaneous Commands. - (line 2254) -* machine dependencies: Machine Dependent. (line 4071) -* mapping input sections to output sections: Input Section. (line 2558) -* MAX: Builtin Functions. (line 3995) -* MEMORY: MEMORY. (line 3196) -* memory region attributes: MEMORY. (line 3222) -* memory regions: MEMORY. (line 3196) -* memory regions and sections: Output Section Region. - (line 3055) -* memory usage: Options. (line 989) -* MIN: Builtin Functions. (line 3998) -* MRI compatibility: MRI. (line 5365) -* MSP430 extra sections: MSP430. (line 4343) -* 'NAME' (MRI): MRI. (line 5448) -* name, section: Output Section Name. - (line 2506) -* names: Symbols. (line 3620) -* naming the output file: Options. (line 526) -* NEXT(EXP): Builtin Functions. (line 4002) -* NMAGIC: Options. (line 506) -* NOCROSSREFS(SECTIONS): Miscellaneous Commands. - (line 2238) -* NOLOAD: Output Section Type. - (line 2969) -* not enough room for program headers: Builtin Functions. (line 4040) -* NO_ENUM_SIZE_WARNING: ARM. (line 4275) -* o =: MEMORY. (line 3251) -* objdump -i: BFD. (line 5019) -* object file management: BFD. (line 5019) -* object files: Options. (line 153) -* object formats available: BFD. (line 5019) -* object size: Options. (line 381) -* OMAGIC: Options. (line 511) -* OMAGIC <1>: Options. (line 520) -* opening object files: BFD outline. (line 5045) -* operators for arithmetic: Operators. (line 3773) -* options: Options. (line 130) -* 'ORDER' (MRI): MRI. (line 5453) -* org =: MEMORY. (line 3251) -* ORIGIN =: MEMORY. (line 3251) -* ORIGIN(MEMORY): Builtin Functions. (line 4008) -* orphan: Orphan Sections. (line 3635) -* output file after errors: Options. (line 1059) -* output file format in linker script: Format Commands. (line 2179) -* output file name in linker script: File Commands. (line 2148) -* output section alignment: Forced Output Alignment. - (line 3043) -* output section attributes: Output Section Attributes. - (line 2939) -* output section data: Output Section Data. - (line 2788) -* OUTPUT(FILENAME): File Commands. (line 2148) -* OUTPUT_ARCH(BFDARCH): Miscellaneous Commands. - (line 2254) -* OUTPUT_FORMAT(BFDNAME): Format Commands. (line 2179) -* OVERLAY: Overlay Description. - (line 3101) -* overlays: Overlay Description. - (line 3101) -* partial link: Options. (line 550) -* PHDRS: PHDRS. (line 3293) -* PHDRS <1>: PHDRS. (line 3348) -* PIC_VENEER: M68HC11/68HC12. (line 4180) -* position independent executables: Options. (line 1085) -* PowerPC ELF32 options: PowerPC ELF32. (line 4376) -* PowerPC GOT: PowerPC ELF32. (line 4393) -* PowerPC long branches: PowerPC ELF32. (line 4369) -* PowerPC PLT: PowerPC ELF32. (line 4376) -* PowerPC stub symbols: PowerPC ELF32. (line 4407) -* PowerPC TLS optimization: PowerPC ELF32. (line 4411) -* PowerPC64 dot symbols: PowerPC64 ELF64. (line 4446) -* PowerPC64 ELF64 options: PowerPC64 ELF64. (line 4419) -* PowerPC64 multi-TOC: PowerPC64 ELF64. (line 4487) -* PowerPC64 OPD optimization: PowerPC64 ELF64. (line 4461) -* PowerPC64 OPD spacing: PowerPC64 ELF64. (line 4467) -* PowerPC64 stub grouping: PowerPC64 ELF64. (line 4419) -* PowerPC64 stub symbols: PowerPC64 ELF64. (line 4442) -* PowerPC64 TLS optimization: PowerPC64 ELF64. (line 4456) -* PowerPC64 TOC optimization: PowerPC64 ELF64. (line 4473) -* precedence in expressions: Operators. (line 3773) -* prevent unnecessary loading: Output Section Type. - (line 2969) -* program headers: PHDRS. (line 3293) -* program headers and sections: Output Section Phdr. - (line 3065) -* program headers, not enough room: Builtin Functions. (line 4040) -* program segments: PHDRS. (line 3293) -* PROVIDE: PROVIDE. (line 2321) -* PROVIDE_HIDDEN: PROVIDE_HIDDEN. (line 2350) -* 'PUBLIC' (MRI): MRI. (line 5461) -* QUAD(EXPRESSION): Output Section Data. - (line 2788) -* quoted symbol names: Symbols. (line 3620) -* read-only text: Options. (line 506) -* read/write from cmd line: Options. (line 511) -* regions of memory: MEMORY. (line 3196) -* relative expressions: Expression Section. (line 3828) -* relaxing addressing modes: Options. (line 1099) -* relaxing on H8/300: H8/300. (line 4081) -* relaxing on i960: i960. (line 4138) -* relaxing on M68HC11: M68HC11/68HC12. (line 4155) -* relaxing on Xtensa: Xtensa. (line 4977) -* relocatable and absolute symbols: Expression Section. (line 3828) -* relocatable output: Options. (line 550) -* removing sections: Output Section Discarding. - (line 2917) -* reporting bugs in 'ld': Reporting Bugs. (line 5188) -* requirements for BFD: BFD. (line 5029) -* retain relocations in final executable: Options. (line 537) -* retaining specified symbols: Options. (line 1120) -* ROM initialized data: Output Section LMA. (line 3003) -* round up expression: Builtin Functions. (line 3890) -* round up location counter: Builtin Functions. (line 3890) -* runtime library name: Options. (line 389) -* runtime library search path: Options. (line 1134) -* runtime pseudo-relocation: WIN32. (line 4749) -* scaled integers: Constants. (line 3610) -* scommon section: Input Section Common. - (line 2735) -* script files: Options. (line 592) -* script files <1>: Options. (line 601) -* scripts: Scripts. (line 1908) -* search directory, from cmd line: Options. (line 440) -* search path in linker script: File Commands. (line 2158) -* SEARCH_DIR(PATH): File Commands. (line 2158) -* 'SECT' (MRI): MRI. (line 5467) -* section address: Output Section Address. - (line 2522) -* section address in expression: Builtin Functions. (line 3871) -* section alignment: Builtin Functions. (line 3915) -* section alignment, warnings on: Options. (line 1413) -* section data: Output Section Data. - (line 2788) -* section fill pattern: Output Section Fill. - (line 3079) -* section load address: Output Section LMA. (line 2983) -* section load address in expression: Builtin Functions. (line 3991) -* section name: Output Section Name. - (line 2506) -* section name wildcard patterns: Input Section Wildcards. - (line 2616) -* section size: Builtin Functions. (line 4019) -* section, assigning to memory region: Output Section Region. - (line 3055) -* section, assigning to program header: Output Section Phdr. - (line 3065) -* SECTIONS: SECTIONS. (line 2443) -* sections, discarding: Output Section Discarding. - (line 2917) -* segment origins, cmd line: Options. (line 1274) -* segments, ELF: PHDRS. (line 3293) -* SEGMENT_START(SEGMENT, DEFAULT): Builtin Functions. (line 4011) -* shared libraries: Options. (line 1206) -* SHORT(EXPRESSION): Output Section Data. - (line 2788) -* SIZEOF(SECTION): Builtin Functions. (line 4019) -* SIZEOF_HEADERS: Builtin Functions. (line 4035) -* small common symbols: Input Section Common. - (line 2735) -* SORT: Input Section Wildcards. - (line 2665) -* SORT_BY_ALIGNMENT: Input Section Wildcards. - (line 2661) -* SORT_BY_NAME: Input Section Wildcards. - (line 2653) -* SPU: SPU ELF. (line 4524) -* SPU <1>: SPU ELF. (line 4541) -* SPU ELF options: SPU ELF. (line 4501) -* SPU extra overlay stubs: SPU ELF. (line 4514) -* SPU local store size: SPU ELF. (line 4519) -* SPU overlay stub symbols: SPU ELF. (line 4510) -* SPU overlays: SPU ELF. (line 4504) -* SPU plugins: SPU ELF. (line 4501) -* SQUAD(EXPRESSION): Output Section Data. - (line 2788) -* stack size: Options. (line 1839) -* standard Unix system: Options. (line 131) -* start of execution: Entry Point. (line 2076) -* STARTUP(FILENAME): File Commands. (line 2166) -* strip all symbols: Options. (line 579) -* strip debugger symbols: Options. (line 583) -* stripping all but some symbols: Options. (line 1120) -* SUBALIGN(SUBSECTION_ALIGN): Forced Input Alignment. - (line 3048) -* suffixes for integers: Constants. (line 3610) -* symbol defaults: Builtin Functions. (line 3971) -* symbol definition, scripts: Assignments. (line 2262) -* symbol names: Symbols. (line 3620) -* symbol tracing: Options. (line 657) -* symbol versions: VERSION. (line 3424) -* symbol-only input: Options. (line 568) -* symbols, from command line: Options. (line 915) -* symbols, relocatable and absolute: Expression Section. (line 3828) -* symbols, retaining selectively: Options. (line 1120) -* synthesizing linker: Options. (line 1099) -* synthesizing on H8/300: H8/300. (line 4086) -* TARGET(BFDNAME): Format Commands. (line 2204) -* TARGET1: ARM. (line 4209) -* TARGET2: ARM. (line 4214) -* thumb entry point: ARM. (line 4199) -* TI COFF versions: TI COFF. (line 4554) -* traditional format: Options. (line 1253) -* trampoline generation on M68HC11: M68HC11/68HC12. (line 4173) -* trampoline generation on M68HC12: M68HC11/68HC12. (line 4173) -* unallocated address, next: Builtin Functions. (line 4002) -* undefined symbol: Options. (line 614) -* undefined symbol in linker script: Miscellaneous Commands. - (line 2221) -* undefined symbols, warnings on: Options. (line 1409) -* uninitialized data placement: Input Section Common. - (line 2721) -* unspecified memory: Output Section Data. - (line 2821) -* usage: Options. (line 977) -* USE_BLX: ARM. (line 4237) -* using a DEF file: WIN32. (line 4596) -* using auto-export functionality: WIN32. (line 4579) -* Using decorations: WIN32. (line 4695) -* variables, defining: Assignments. (line 2262) -* verbose: Options. (line 1309) -* version: Options. (line 641) -* version script: VERSION. (line 3424) -* version script, symbol versions: Options. (line 1315) -* VERSION {script text}: VERSION. (line 3424) -* versions of symbols: VERSION. (line 3424) -* VFP11_DENORM_FIX: ARM. (line 4246) -* warnings, on combining symbols: Options. (line 1322) -* warnings, on section alignment: Options. (line 1413) -* warnings, on undefined symbols: Options. (line 1409) -* weak externals: WIN32. (line 4938) -* what is this?: Overview. (line 100) -* wildcard file name patterns: Input Section Wildcards. - (line 2616) -* Xtensa options: Xtensa. (line 5005) -* Xtensa processors: Xtensa. (line 4956) - diff --git a/contrib/binutils/ld/ldint.7 b/contrib/binutils/ld/ldint.7 new file mode 100644 index 000000000000..6c17af41d8a0 --- /dev/null +++ b/contrib/binutils/ld/ldint.7 @@ -0,0 +1,1277 @@ +.Dd 2015-03-02 +.Dt LDINT 7 +.Os +.Sh NAME +.Nm ldint +.Nd GNU Linker Internals +.Sh +This file documents the internals of the GNU linker +.Li ld . +It is a collection of miscellaneous information with little form at this point. +Mostly, it is a repository into which you can put information about GNU +.Li ld +as you discover it (or as you design changes to +.Li ld ) . +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled "GNU Free +Documentation License". +.Pp +.Sh The Pa README File +Check the +.Pa README +file; it often has useful information that does not appear anywhere else in +the directory. +.Pp +.Sh How linker emulations are generated +Each linker target has an +.Em emulation . +The emulation includes the default linker script, and certain emulations also +modify certain types of linker behaviour. +.Pp +Emulations are created during the build process by the shell script +.Pa genscripts.sh . +.Pp +The +.Pa genscripts.sh +script starts by reading a file in the +.Pa emulparams +directory. This is a shell script which sets various shell variables used +by +.Pa genscripts.sh +and the other shell scripts it invokes. +.Pp +The +.Pa genscripts.sh +script will invoke a shell script in the +.Pa scripttempl +directory in order to create default linker scripts written in the linker +command language. The +.Pa scripttempl +script will be invoked 5 (or, in some cases, 6) times, with different assignments +to shell variables, to create different default scripts. The choice of script +is made based on the command line options. +.Pp +After creating the scripts, +.Pa genscripts.sh +will invoke yet another shell script, this time in the +.Pa emultempl +directory. That shell script will create the emulation source file, which +contains C code. This C code permits the linker emulation to override various +linker behaviours. Most targets use the generic emulation code, which is in +.Pa emultempl/generic.em . +.Pp +To summarize, +.Pa genscripts.sh +reads three shell scripts: an emulation parameters script in the +.Pa emulparams +directory, a linker script generation script in the +.Pa scripttempl +directory, and an emulation source file generation script in the +.Pa emultempl +directory. +.Pp +For example, the Sun 4 linker sets up variables in +.Pa emulparams/sun4.sh , +creates linker scripts using +.Pa scripttempl/aout.sc , +and creates the emulation code using +.Pa emultempl/sunos.em . +.Pp +Note that the linker can support several emulations simultaneously, depending +upon how it is configured. An emulation can be selected with the +.Li -m +option. The +.Li -V +option will list all supported emulations. +.Pp +.Ss Pa emulparams scripts +Each target selects a particular file in the +.Pa emulparams +directory by setting the shell variable +.Li targ_emul +in +.Pa configure.tgt . +This shell variable is used by the +.Pa configure +script to control building an emulation source file. +.Pp +Certain conventions are enforced. Suppose the +.Li targ_emul +variable is set to +.Va emul +in +.Pa configure.tgt . +The name of the emulation shell script will be +.Pa emulparams/ Va emul.sh . +The +.Pa Makefile +must have a target named +.Pa e Va emul.c ; +this target must depend upon +.Pa emulparams/ Va emul.sh , +as well as the appropriate scripts in the +.Pa scripttempl +and +.Pa emultempl +directories. The +.Pa Makefile +target must invoke +.Li GENSCRIPTS +with two arguments: +.Va emul , +and the value of the make variable +.Li tdir_ Va emul . +The value of the latter variable will be set by the +.Pa configure +script, and is used to set the default target directory to search. +.Pp +By convention, the +.Pa emulparams/ Va emul.sh +shell script should only set shell variables. It may set shell variables which +are to be interpreted by the +.Pa scripttempl +and the +.Pa emultempl +scripts. Certain shell variables are interpreted directly by the +.Pa genscripts.sh +script. +.Pp +Here is a list of shell variables interpreted by +.Pa genscripts.sh , +as well as some conventional shell variables interpreted by the +.Pa scripttempl +and +.Pa emultempl +scripts. +.Pp +.Bl -tag -width Ds +.It SCRIPT_NAME +This is the name of the +.Pa scripttempl +script to use. If +.Li SCRIPT_NAME +is set to +.Va script , +.Pa genscripts.sh +will use the script +.Pa scripttempl/ Va script.sc . +.Pp +.It TEMPLATE_NAME +This is the name of the +.Pa emultempl +script to use. If +.Li TEMPLATE_NAME +is set to +.Va template , +.Pa genscripts.sh +will use the script +.Pa emultempl/ Va template.em . +If this variable is not set, the default value is +.Li generic . +.Pp +.It GENERATE_SHLIB_SCRIPT +If this is set to a nonempty string, +.Pa genscripts.sh +will invoke the +.Pa scripttempl +script an extra time to create a shared library script. linker scripts. +.Pp +.It OUTPUT_FORMAT +This is normally set to indicate the BFD output format use (e.g., +.Li "a.out-sunos-big" . +The +.Pa scripttempl +script will normally use it in an +.Li OUTPUT_FORMAT +expression in the linker script. +.Pp +.It ARCH +This is normally set to indicate the architecture to use (e.g., +.Li sparc ) . +The +.Pa scripttempl +script will normally use it in an +.Li OUTPUT_ARCH +expression in the linker script. +.Pp +.It ENTRY +Some +.Pa scripttempl +scripts use this to set the entry address, in an +.Li ENTRY +expression in the linker script. +.Pp +.It TEXT_START_ADDR +Some +.Pa scripttempl +scripts use this to set the start address of the +.Li .text +section. +.Pp +.It NONPAGED_TEXT_START_ADDR +If this is defined, the +.Pa genscripts.sh +script sets +.Li TEXT_START_ADDR +to its value before running the +.Pa scripttempl +script for the +.Li -n +and +.Li -N +options (see Section +.Dq linker scripts ) . +.Pp +.It SEGMENT_SIZE +The +.Pa genscripts.sh +script uses this to set the default value of +.Li DATA_ALIGNMENT +when running the +.Pa scripttempl +script. +.Pp +.It TARGET_PAGE_SIZE +If +.Li SEGMENT_SIZE +is not defined, the +.Pa genscripts.sh +script uses this to define it. +.Pp +.It ALIGNMENT +Some +.Pa scripttempl +scripts set this to a number to pass to +.Li ALIGN +to set the required alignment for the +.Li end +symbol. +.El +.Pp +.Ss Pa scripttempl scripts +Each linker target uses a +.Pa scripttempl +script to generate the default linker scripts. The name of the +.Pa scripttempl +script is set by the +.Li SCRIPT_NAME +variable in the +.Pa emulparams +script. If +.Li SCRIPT_NAME +is set to +.Va script , +.Li genscripts.sh +will invoke +.Pa scripttempl/ Va script.sc . +.Pp +The +.Pa genscripts.sh +script will invoke the +.Pa scripttempl +script 5 to 8 times. Each time it will set the shell variable +.Li LD_FLAG +to a different value. When the linker is run, the options used will direct +it to select a particular script. (Script selection is controlled by the +.Li get_script +emulation entry point; this describes the conventional behaviour). +.Pp +The +.Pa scripttempl +script should just write a linker script, written in the linker command language, +to standard output. If the emulation name--the name of the +.Pa emulparams +file without the +.Pa .sc +extension--is +.Va emul , +then the output will be directed to +.Pa ldscripts/ Va emul. Va extension +in the build directory, where +.Va extension +changes each time the +.Pa scripttempl +script is invoked. +.Pp +Here is the list of values assigned to +.Li LD_FLAG . +.Pp +.Bl -tag -width Ds +.It (empty) +The script generated is used by default (when none of the following cases +apply). The output has an extension of +.Pa .x . +.It n +The script generated is used when the linker is invoked with the +.Li -n +option. The output has an extension of +.Pa .xn . +.It N +The script generated is used when the linker is invoked with the +.Li -N +option. The output has an extension of +.Pa .xbn . +.It r +The script generated is used when the linker is invoked with the +.Li -r +option. The output has an extension of +.Pa .xr . +.It u +The script generated is used when the linker is invoked with the +.Li -Ur +option. The output has an extension of +.Pa .xu . +.It shared +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_SHLIB_SCRIPT +is defined in the +.Pa emulparams +file. The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -shared +option. The output has an extension of +.Pa .xs . +.It c +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_COMBRELOC_SCRIPT +is defined in the +.Pa emulparams +file or if +.Li SCRIPT_NAME +is +.Li elf . +The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -z combreloc +option. The output has an extension of +.Pa .xc . +.It cshared +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_COMBRELOC_SCRIPT +is defined in the +.Pa emulparams +file or if +.Li SCRIPT_NAME +is +.Li elf +and +.Li GENERATE_SHLIB_SCRIPT +is defined in the +.Pa emulparams +file. The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -shared -z combreloc +option. The output has an extension of +.Pa .xsc . +.El +.Pp +Besides the shell variables set by the +.Pa emulparams +script, and the +.Li LD_FLAG +variable, the +.Pa genscripts.sh +script will set certain variables for each run of the +.Pa scripttempl +script. +.Pp +.Bl -tag -width Ds +.It RELOCATING +This will be set to a non-empty string when the linker is doing a final relocation +(e.g., all scripts other than +.Li -r +and +.Li -Ur ) . +.Pp +.It CONSTRUCTING +This will be set to a non-empty string when the linker is building global +constructor and destructor tables (e.g., all scripts other than +.Li -r ) . +.Pp +.It DATA_ALIGNMENT +This will be set to an +.Li ALIGN +expression when the output should be page aligned, or to +.Li . +when generating the +.Li -N +script. +.Pp +.It CREATE_SHLIB +This will be set to a non-empty string when generating a +.Li -shared +script. +.Pp +.It COMBRELOC +This will be set to a non-empty string when generating +.Li -z combreloc +scripts to a temporary file name which can be used during script generation. +.El +.Pp +The conventional way to write a +.Pa scripttempl +script is to first set a few shell variables, and then write out a linker +script using +.Li cat +with a here document. The linker script will use variable substitutions, based +on the above variables and those set in the +.Pa emulparams +script, to control its behaviour. +.Pp +When there are parts of the +.Pa scripttempl +script which should only be run when doing a final relocation, they should +be enclosed within a variable substitution based on +.Li RELOCATING . +For example, on many targets special symbols such as +.Li _end +should be defined when doing a final link. Naturally, those symbols should +not be defined when doing a relocatable link using +.Li -r . +The +.Pa scripttempl +script could use a construct like this to define those symbols: +.Bd -literal -offset indent + ${RELOCATING+ _end = .;} +.Ed +This will do the symbol assignment only if the +.Li RELOCATING +variable is defined. +.Pp +The basic job of the linker script is to put the sections in the correct order, +and at the correct memory addresses. For some targets, the linker script may +have to do some other operations. +.Pp +For example, on most MIPS platforms, the linker is responsible for defining +the special symbol +.Li _gp , +used to initialize the +.Li $gp +register. It must be set to the start of the small data section plus +.Li 0x8000 . +Naturally, it should only be defined when doing a final relocation. This will +typically be done like this: +.Bd -literal -offset indent + ${RELOCATING+ _gp = ALIGN(16) + 0x8000;} +.Ed +This line would appear just before the sections which compose the small data +section ( +.Li .sdata , +.Li .sbss ) . +All those sections would be contiguous in memory. +.Pp +Many COFF systems build constructor tables in the linker script. The compiler +will arrange to output the address of each global constructor in a +.Li .ctor +section, and the address of each global destructor in a +.Li .dtor +section (this is done by defining +.Li ASM_OUTPUT_CONSTRUCTOR +and +.Li ASM_OUTPUT_DESTRUCTOR +in the +.Li gcc +configuration files). The +.Li gcc +runtime support routines expect the constructor table to be named +.Li __CTOR_LIST__ . +They expect it to be a list of words, with the first word being the count +of the number of entries. There should be a trailing zero word. (Actually, +the count may be -1 if the trailing word is present, and the trailing word +may be omitted if the count is correct, but, as the +.Li gcc +behaviour has changed slightly over the years, it is safest to provide both). +Here is a typical way that might be handled in a +.Pa scripttempl +file. +.Bd -literal -offset indent + ${CONSTRUCTING+ __CTOR_LIST__ = .;} + ${CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)} + ${CONSTRUCTING+ *(.ctors)} + ${CONSTRUCTING+ LONG(0)} + ${CONSTRUCTING+ __CTOR_END__ = .;} + ${CONSTRUCTING+ __DTOR_LIST__ = .;} + ${CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)} + ${CONSTRUCTING+ *(.dtors)} + ${CONSTRUCTING+ LONG(0)} + ${CONSTRUCTING+ __DTOR_END__ = .;} +.Ed +The use of +.Li CONSTRUCTING +ensures that these linker script commands will only appear when the linker +is supposed to be building the constructor and destructor tables. This example +is written for a target which uses 4 byte pointers. +.Pp +Embedded systems often need to set a stack address. This is normally best +done by using the +.Li PROVIDE +construct with a default stack address. This permits the user to easily override +the stack address using the +.Li --defsym +option. Here is an example: +.Bd -literal -offset indent + ${RELOCATING+ PROVIDE (__stack = 0x80000000);} +.Ed +The value of the symbol +.Li __stack +would then be used in the startup code to initialize the stack pointer. +.Pp +.Ss Pa emultempl scripts +Each linker target uses an +.Pa emultempl +script to generate the emulation code. The name of the +.Pa emultempl +script is set by the +.Li TEMPLATE_NAME +variable in the +.Pa emulparams +script. If the +.Li TEMPLATE_NAME +variable is not set, the default is +.Li generic . +If the value of +.Li TEMPLATE_NAME +is +.Va template , +.Pa genscripts.sh +will use +.Pa emultempl/ Va template.em . +.Pp +Most targets use the generic +.Pa emultempl +script, +.Pa emultempl/generic.em . +A different +.Pa emultempl +script is only needed if the linker must support unusual actions, such as +linking against shared libraries. +.Pp +The +.Pa emultempl +script is normally written as a simple invocation of +.Li cat +with a here document. The document will use a few variable substitutions. +Typically each function names uses a substitution involving +.Li EMULATION_NAME , +for ease of debugging when the linker supports multiple emulations. +.Pp +Every function and variable in the emitted file should be static. The only +globally visible object must be named +.Li ld_ Va EMULATION_NAME_emulation , +where +.Va EMULATION_NAME +is the name of the emulation set in +.Pa configure.tgt +(this is also the name of the +.Pa emulparams +file without the +.Pa .sh +extension). The +.Pa genscripts.sh +script will set the shell variable +.Li EMULATION_NAME +before invoking the +.Pa emultempl +script. +.Pp +The +.Li ld_ Va EMULATION_NAME_emulation +variable must be a +.Li struct ld_emulation_xfer_struct , +as defined in +.Pa ldemul.h . +It defines a set of function pointers which are invoked by the linker, as +well as strings for the emulation name (normally set from the shell variable +.Li EMULATION_NAME +and the default BFD target name (normally set from the shell variable +.Li OUTPUT_FORMAT +which is normally set by the +.Pa emulparams +file). +.Pp +The +.Pa genscripts.sh +script will set the shell variable +.Li COMPILE_IN +when it invokes the +.Pa emultempl +script for the default emulation. In this case, the +.Pa emultempl +script should include the linker scripts directly, and return them from the +.Li get_scripts +entry point. When the emulation is not the default, the +.Li get_scripts +entry point should just return a file name. See +.Pa emultempl/generic.em +for an example of how this is done. +.Pp +At some point, the linker emulation entry points should be documented. +.Pp +.Sh A Walkthrough of a Typical Emulation +This chapter is to help people who are new to the way emulations interact +with the linker, or who are suddenly thrust into the position of having to +work with existing emulations. It will discuss the files you need to be aware +of. It will tell you when the given "hooks" in the emulation will be called. +It will, hopefully, give you enough information about when and how things +happen that you'll be able to get by. As always, the source is the definitive +reference to this. +.Pp +The starting point for the linker is in +.Pa ldmain.c +where +.Li main +is defined. The bulk of the code that's emulation specific will initially +be in +.Li emultempl/ Va emulation.em +but will end up in +.Li e Va emulation.c +when the build is done. Most of the work to select and interface with emulations +is in +.Li ldemul.h +and +.Li ldemul.c . +Specifically, +.Li ldemul.h +defines the +.Li ld_emulation_xfer_struct +structure your emulation exports. +.Pp +Your emulation file exports a symbol +.Li ld_ Va EMULATION_NAME_emulation . +If your emulation is selected (it usually is, since usually there's only one), +.Li ldemul.c +sets the variable +.Va ld_emulation +to point to it. +.Li ldemul.c +also defines a number of API functions that interface to your emulation, like +.Li ldemul_after_parse +which simply calls your +.Li ld_ Va EMULATION_emulation.after_parse +function. For the rest of this section, the functions will be mentioned, but +you should assume the indirect reference to your emulation also. +.Pp +We will also skip or gloss over parts of the link process that don't relate +to emulations, like setting up internationalization. +.Pp +After initialization, +.Li main +selects an emulation by pre-scanning the command line arguments. It calls +.Li ldemul_choose_target +to choose a target. If you set +.Li choose_target +to +.Li ldemul_default_target , +it picks your +.Li target_name +by default. +.Pp +.Li main +calls +.Li ldemul_before_parse , +then +.Li parse_args . +.Li parse_args +calls +.Li ldemul_parse_args +for each arg, which must update the +.Li getopt +globals if it recognizes the argument. If the emulation doesn't recognize +it, then parse_args checks to see if it recognizes it. +.Pp +Now that the emulation has had access to all its command-line options, +.Li main +calls +.Li ldemul_set_symbols . +This can be used for any initialization that may be affected by options. It +is also supposed to set up any variables needed by the emulation script. +.Pp +.Li main +now calls +.Li ldemul_get_script +to get the emulation script to use (based on arguments, no doubt,see Section +.Dq Emulations ) +and runs it. While parsing, +.Li ldgram.y +may call +.Li ldemul_hll +or +.Li ldemul_syslib +to handle the +.Li HLL +or +.Li SYSLIB +commands. It may call +.Li ldemul_unrecognized_file +if you asked the linker to link a file it doesn't recognize. It will call +.Li ldemul_recognized_file +for each file it does recognize, in case the emulation wants to handle some +files specially. All the while, it's loading the files (possibly calling +.Li ldemul_open_dynamic_archive ) +and symbols and stuff. After it's done reading the script, +.Li main +calls +.Li ldemul_after_parse . +Use the after-parse hook to set up anything that depends on stuff the script +might have set up, like the entry point. +.Pp +.Li main +next calls +.Li lang_process +in +.Li ldlang.c . +This appears to be the main core of the linking itself, as far as emulation +hooks are concerned(*). It first opens the output file's BFD, calling +.Li ldemul_set_output_arch , +and calls +.Li ldemul_create_output_section_statements +in case you need to use other means to find or create object files (i.e. shared +libraries found on a path, or fake stub objects). Despite the name, nobody +creates output sections here. +.Pp +(*) In most cases, the BFD library does the bulk of the actual linking, handling +symbol tables, symbol resolution, relocations, and building the final output +file. See the BFD reference for all the details. Your emulation is usually +concerned more with managing things at the file and section level, like "put +this here, add this section", etc. +.Pp +Next, the objects to be linked are opened and BFDs created for them, and +.Li ldemul_after_open +is called. At this point, you have all the objects and symbols loaded, but +none of the data has been placed yet. +.Pp +Next comes the Big Linking Thingy (except for the parts BFD does). All input +sections are mapped to output sections according to the script. If a section +doesn't get mapped by default, +.Li ldemul_place_orphan +will get called to figure out where it goes. Next it figures out the offsets +for each section, calling +.Li ldemul_before_allocation +before and +.Li ldemul_after_allocation +after deciding where each input section ends up in the output sections. +.Pp +The last part of +.Li lang_process +is to figure out all the symbols' values. After assigning final values to +the symbols, +.Li ldemul_finish +is called, and after that, any undefined symbols are turned into fatal errors. +.Pp +OK, back to +.Li main , +which calls +.Li ldwrite +in +.Pa ldwrite.c . +.Li ldwrite +calls BFD's final_link, which does all the relocation fixups and writes the +output bfd to disk, and we're done. +.Pp +In summary, +.Pp +.Bl -bullet +.It +.Li main() +in +.Pa ldmain.c +.It +.Pa emultempl/ Va EMULATION.em +has your code +.It +.Li ldemul_choose_target +(defaults to your +.Li target_name ) +.It +.Li ldemul_before_parse +.It +Parse argv, calls +.Li ldemul_parse_args +for each +.It +.Li ldemul_set_symbols +.It +.Li ldemul_get_script +.It +parse script +.Pp +.Bl -bullet +.It +may call +.Li ldemul_hll +or +.Li ldemul_syslib +.It +may call +.Li ldemul_open_dynamic_archive +.El +.Pp +.It +.Li ldemul_after_parse +.It +.Li lang_process() +in +.Pa ldlang.c +.Pp +.Bl -bullet +.It +create +.Li output_bfd +.It +.Li ldemul_set_output_arch +.It +.Li ldemul_create_output_section_statements +.It +read objects, create input bfds - all symbols exist, but have no values +.It +may call +.Li ldemul_unrecognized_file +.It +will call +.Li ldemul_recognized_file +.It +.Li ldemul_after_open +.It +map input sections to output sections +.It +may call +.Li ldemul_place_orphan +for remaining sections +.It +.Li ldemul_before_allocation +.It +gives input sections offsets into output sections, places output sections +.It +.Li ldemul_after_allocation +- section addresses valid +.It +assigns values to symbols +.It +.Li ldemul_finish +- symbol values valid +.El +.Pp +.It +output bfd is written to disk +.Pp +.El +.Sh Some Architecture Specific Notes +This is the place for notes on the behavior of +.Li ld +on specific platforms. Currently, only Intel x86 is documented (and of that, +only the auto-import behavior for DLLs). +.Pp +.Ss Intel x86 +.Bl -tag -width Ds +.Li ld +can create DLLs that operate with various runtimes available on a common x86 +operating system. These runtimes include native (using the mingw "platform"), +cygwin, and pw. +.Pp +.It auto-import from DLLs +.Bl -enum +.It +With this feature on, DLL clients can import variables from DLL without any +concern from their side (for example, without any source code modifications). +Auto-import can be enabled using the +.Li --enable-auto-import +flag, or disabled via the +.Li --disable-auto-import +flag. Auto-import is disabled by default. +.Pp +.It +This is done completely in bounds of the PE specification (to be fair, there's +a minor violation of the spec at one point, but in practice auto-import works +on all known variants of that common x86 operating system) So, the resulting +DLL can be used with any other PE compiler/linker. +.Pp +.It +Auto-import is fully compatible with standard import method, in which variables +are decorated using attribute modifiers. Libraries of either type may be mixed +together. +.Pp +.It +Overhead (space): 8 bytes per imported symbol, plus 20 for each reference +to it; Overhead (load time): negligible; Overhead (virtual/physical memory): +should be less than effect of DLL relocation. +.El +.Pp +Motivation +.Pp +The obvious and only way to get rid of dllimport insanity is to make client +access variable directly in the DLL, bypassing the extra dereference imposed +by ordinary DLL runtime linking. I.e., whenever client contains something +like +.Pp +.Li mov dll_var,%eax, +.Pp +address of dll_var in the command should be relocated to point into loaded +DLL. The aim is to make OS loader do so, and than make ld help with that. +Import section of PE made following way: there's a vector of structures each +describing imports from particular DLL. Each such structure points to two +other parallel vectors: one holding imported names, and one which will hold +address of corresponding imported name. So, the solution is de-vectorize these +structures, making import locations be sparse and pointing directly into code. +.Pp +Implementation +.Pp +For each reference of data symbol to be imported from DLL (to set of which +belong symbols with name <sym>, if __imp_<sym> is found in implib), the import +fixup entry is generated. That entry is of type IMAGE_IMPORT_DESCRIPTOR and +stored in .idata$3 subsection. Each fixup entry contains pointer to symbol's +address within .text section (marked with __fuN_<sym> symbol, where N is integer), +pointer to DLL name (so, DLL name is referenced by multiple entries), and +pointer to symbol name thunk. Symbol name thunk is singleton vector (__nm_th_<symbol>) +pointing to IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing +imported name. Here comes that "om the edge" problem mentioned above: PE specification +rambles that name vector (OriginalFirstThunk) should run in parallel with +addresses vector (FirstThunk), i.e. that they should have same number of elements +and terminated with zero. We violate this, since FirstThunk points directly +into machine code. But in practice, OS loader implemented the sane way: it +goes thru OriginalFirstThunk and puts addresses to FirstThunk, not something +else. It once again should be noted that dll and symbol name structures are +reused across fixup entries and should be there anyway to support standard +import stuff, so sustained overhead is 20 bytes per reference. Other question +is whether having several IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. +Answer is yes, it is done even by native compiler/linker (libth32's functions +are in fact resident in windows9x kernel32.dll, so if you use it, you have +two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is whether +referencing the same PE structures several times is valid. The answer is why +not, prohibiting that (detecting violation) would require more work on behalf +of loader than not doing it. +.Pp +.El +.Sh GNU Free Documentation License +GNU Free Documentation License Version 1.1, March 2000 +.Pp +Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street, Fifth +Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute +verbatim copies of this license document, but changing it is not allowed. +.Pp +0. PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document "free" in the sense of freedom: to assure everyone the effective +freedom to copy and redistribute it, with or without modifying it, either +commercially or noncommercially. Secondarily, this License preserves for the +author and publisher a way to get credit for their work, while not being considered +responsible for modifications made by others. +.Pp +This License is a kind of "copyleft", which means that derivative works of +the document must themselves be free in the same sense. It complements the +GNU General Public License, which is a copyleft license designed for free +software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +1. APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The "Document", below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as "you". +.Pp +A "Modified Version" of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A "Secondary Section" is a named appendix or a front-matter section of the +Document that deals exclusively with the relationship of the publishers or +authors of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The "Invariant Sections" are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The "Cover Texts" are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A "Transparent" copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +"Transparent" is called "Opaque". +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The "Title Page" means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, "Title Page" means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +2. VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +3. COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +4. MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. E. +Add an appropriate copyright notice for your modifications adjacent to the +other copyright notices. F. Include, immediately after the copyright notices, +a license notice giving the public permission to use the Modified Version +under the terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections and +required Cover Texts given in the Document's license notice. H. Include an +unaltered copy of this License. I. Preserve the section entitled "History", +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled "History" in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the "History" section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", preserve the +section's title, and preserve in the section all the substance and tone of +each of the contributor acknowledgements and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, unaltered in their +text and in their titles. Section numbers or the equivalent are not considered +part of the section titles. M. Delete any section entitled "Endorsements". +Such a section may not be included in the Modified Version. N. Do not retitle +any existing section as "Endorsements" or to conflict in title with any Invariant +Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled "Endorsements", provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +5. COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled "History" in the +various original documents, forming one section entitled "History"; likewise +combine any sections entitled "Acknowledgements", and any sections entitled +"Dedications". You must delete all sections entitled "Endorsements." +.Pp +6. COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +7. AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an "aggregate", and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +8. TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +9. TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document 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. +.Pp +10. FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation 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. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License "or +any later version" applies to it, you have the option of following the terms +and conditions either of that specified version or of any later version that +has been published (not as a draft) by the Free Software Foundation. If the +Document does not specify a version number of this License, you may choose +any version ever published (not as a draft) by the Free Software Foundation. +.Pp +ADDENDUM: How to use this License for your documents +.Pp +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +.Ed +.Pp +If you have no Invariant Sections, write "with no Invariant Sections" instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +"no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise +for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp |