diff options
| author | Ken Raeburn <raeburn@cygnus> | 1993-11-05 20:35:15 +0000 |
|---|---|---|
| committer | Ken Raeburn <raeburn@cygnus> | 1993-11-05 20:35:15 +0000 |
| commit | 1a9f0c717fc302993f77bf56f61365b0c0f6f097 (patch) | |
| tree | e13c54128433b8b56436489950d71da03a8b88bf /ld | |
| parent | 46e695a7f8d847876ef18e6446dffd8ad4743fb5 (diff) | |
| download | fsf-binutils-gdb-1a9f0c717fc302993f77bf56f61365b0c0f6f097.zip fsf-binutils-gdb-1a9f0c717fc302993f77bf56f61365b0c0f6f097.tar.gz fsf-binutils-gdb-1a9f0c717fc302993f77bf56f61365b0c0f6f097.tar.bz2 | |
adjusting repository after cvs mixup
Diffstat (limited to 'ld')
| -rw-r--r-- | ld/ld.info | 65 | ||||
| -rw-r--r-- | ld/ld.info-1 | 1255 | ||||
| -rw-r--r-- | ld/ld.info-2 | 941 |
3 files changed, 0 insertions, 2261 deletions
diff --git a/ld/ld.info b/ld/ld.info deleted file mode 100644 index 91e4d7d..0000000 --- a/ld/ld.info +++ /dev/null @@ -1,65 +0,0 @@ -This is Info file ld.info, produced by Makeinfo-1.55 from the input -file ./ld.texinfo. - -START-INFO-DIR-ENTRY -* Ld:: The GNU linker. -END-INFO-DIR-ENTRY - - This file documents the GNU linker LD. - - Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -Indirect: -ld.info-1: 857 -ld.info-2: 49400 - -Tag Table: -(Indirect) -Node: Top857 -Node: Overview1330 -Node: Invocation2478 -Node: Options2886 -Node: Environment20209 -Node: Commands21154 -Node: Scripts22148 -Node: Expressions23246 -Node: Integers24173 -Node: Symbols25012 -Node: Location Counter25572 -Node: Operators26768 -Node: Evaluation27678 -Node: Assignment28373 -Node: Arithmetic Functions31454 -Node: MEMORY35234 -Node: SECTIONS37821 -Node: Section Definition39419 -Node: Section Placement40867 -Node: Section Data Expressions45560 -Node: Section Options49400 -Node: Entry Point51581 -Node: Option Commands53174 -Node: Machine Dependent56493 -Node: H8/30056913 -Node: i96057708 -Node: BFD58918 -Node: BFD outline62281 -Node: BFD information loss63566 -Node: Canonical format66074 -Node: MRI70420 -Node: Index74894 - -End Tag Table diff --git a/ld/ld.info-1 b/ld/ld.info-1 deleted file mode 100644 index 7613997..0000000 --- a/ld/ld.info-1 +++ /dev/null @@ -1,1255 +0,0 @@ -This is Info file ld.info, produced by Makeinfo-1.55 from the input -file ./ld.texinfo. - -START-INFO-DIR-ENTRY -* Ld:: The GNU linker. -END-INFO-DIR-ENTRY - - This file documents the GNU linker LD. - - Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -File: ld.info, Node: Top, Next: Overview, Prev: (DIR), Up: (DIR) - -Using ld -******** - - This file documents the GNU linker ld. - -* Menu: - -* Overview:: Overview -* Invocation:: Invocation -* Commands:: Command Language - -* Machine Dependent:: Machine Dependent Features - -* BFD:: BFD - -* MRI:: MRI Compatible Script Files -* Index:: Index - - -File: ld.info, Node: Overview, Next: Invocation, Prev: Top, Up: Top - -Overview -******** - - `ld' combines a number of object and archive files, relocates their -data and ties up symbol references. Usually the last step in compiling -a program is to run `ld'. - - `ld' accepts Linker Command Language files written in a superset of -AT&T's Link Editor Command Language syntax, to provide explicit and -total control over the linking process. - - This version of `ld' uses the general purpose BFD libraries to -operate on object files. This allows `ld' to read, combine, and write -object files in many different formats--for example, COFF or `a.out'. -Different formats may be linked together to produce any available kind -of object file. *Note BFD:: for a list of formats supported on various -architectures. - - Aside from its flexibility, the GNU linker is more helpful than other -linkers in providing diagnostic information. Many linkers abandon -execution immediately upon encountering an error; whenever possible, -`ld' continues executing, allowing you to identify other errors (or, in -some cases, to get an output file in spite of the error). - - -File: ld.info, Node: Invocation, Next: Commands, Prev: Overview, Up: Top - -Invocation -********** - - The GNU linker `ld' is meant to cover a broad range of situations, -and to be as compatible as possible with other linkers. As a result, -you have many choices to control its behavior. - -* Menu: - -* Options:: Command Line Options -* Environment:: Environment Variables - - -File: ld.info, Node: Options, Next: Environment, Up: Invocation - -Command Line Options -==================== - - Here is a summary of the options you can use on the `ld' command -line: - - ld [ -o OUTPUT ] OBJFILE... - [ -AARCHITECTURE ] [ -b INPUT-FORMAT ] [ -Bstatic ] - [ -c MRI-COMMANDFILE ] [ -d | -dc | -dp ] - [ -defsym SYMBOL=EXPRESSION ] - [ -e ENTRY ] [ -F ] [ -F FORMAT ] - [ -format INPUT-FORMAT ] [ -g ] [ -G SIZE ] [ --help ] [ -i ] - [ -lARCHIVE ] [ -LSEARCHDIR ] [ -M ] [ -Map MAPFILE ] - [ -m EMULATION ] [ -N | -n ] [ -noinhibit-exec ] - [ -oformat OUTPUT-FORMAT ] [ -R FILENAME ] [ -relax ] - [ -r | -Ur ] [ -S ] [ -s ] [ -sort-common ] [ -T COMMANDFILE ] - [ -Ttext ORG ] [ -Tdata ORG ] - [ -Tbss ORG ] [ -t ] [ -u SYMBOL] [-V] [-v] [ --version ] - [ -warn-common ] [ -ySYMBOL ] [ -X ] [-x ] - - This plethora of command-line options may seem intimidating, but in -actual practice few of them are used in any particular context. For -instance, a frequent use of `ld' is to link standard Unix object files -on a standard, supported Unix system. On such a system, to link a file -`hello.o': - - ld -o OUTPUT /lib/crt0.o hello.o -lc - - This tells `ld' to produce a file called OUTPUT as the result of -linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a', -which will come from the standard search directories. (See the -discussion of the `-l' option below.) - - The command-line options to `ld' may be specified in any order, and -may be repeated at will. Repeating most options with a different -argument will either have no further effect, or override prior -occurrences (those further to the left on the command line) of that -option. - - The exceptions--which may meaningfully be used more than once--are -`-A', `-b' (or its synonym `-format'), `-defsym', `-L', `-l', `-R', and -`-u'. - - The list of object files to be linked together, shown as OBJFILE..., -may follow, precede, or be mixed in with command-line options, except -that an OBJFILE argument may not be placed between an option and its -argument. - - Usually the linker is invoked with at least one object file, but you -can specify other forms of binary input files using `-l', `-R', and the -script command language. If *no* binary input files at all are -specified, the linker does not produce any output, and issues the -message `No input files'. - - Option arguments must either follow the option letter without -intervening whitespace, or be given as separate arguments immediately -following the option that requires them. - -`-AARCHITECTURE' - In the current release of `ld', this option is useful only for the - Intel 960 family of architectures. In that `ld' configuration, the - ARCHITECTURE argument identifies the particular architecture in - the 960 family, enabling some safeguards and modifying the - archive-library search path. *Note `ld' and the Intel 960 family: - i960, for details. - - Future releases of `ld' may support similar functionality for - other architecture families. - -`-b INPUT-FORMAT' - Specify the binary format for input object files that follow this - option on the command line. You don't usually need to specify - this, as `ld' is configured to expect as a default input format - the most usual format on each machine. INPUT-FORMAT is a text - string, the name of a particular format supported by the BFD - libraries. (You can list the available binary formats with - `objdump -i'.) `-format INPUT-FORMAT' has the same effect, as does - the script command `TARGET'. *Note BFD::. - - You may want to use this option if you are linking files with an - unusual binary format. You can also use `-b' to switch formats - explicitly (when linking object files of different formats), by - including `-b INPUT-FORMAT' before each group of object files in a - particular format. - - The default format is taken from the environment variable - `GNUTARGET'. *Note Environment::. You can also define the input - format from a script, using the command `TARGET'; see *Note Option - Commands::. - -`-Bstatic' - Ignored. This option is accepted for command-line compatibility - with the SunOS linker. - -`-c MRI-COMMANDFILE' - For compatibility with linkers produced by MRI, `ld' accepts script - files written in an alternate, restricted command language, - described in *Note MRI Compatible Script Files: MRI. Introduce - MRI script files with the option `-c'; use the `-T' option to run - linker scripts written in the general-purpose `ld' scripting - language. If MRI-CMDFILE does not exist, `ld' looks for it in the - directories specified by any `-L' options. - -`-d' -`-dc' -`-dp' - These three options are equivalent; multiple forms are supported - for compatibility with other linkers. They assign space to common - symbols even if a relocatable output file is specified (with - `-r'). The script command `FORCE_COMMON_ALLOCATION' has the same - effect. *Note Option Commands::. - -`-defsym SYMBOL=EXPRESSION' - Create a global symbol in the output file, containing the absolute - address given by EXPRESSION. You may use this option as many - times as necessary to define multiple symbols in the command line. - A limited form of arithmetic is supported for the EXPRESSION in - this context: you may give a hexadecimal constant or the name of - an existing symbol, or use `+' and `-' to add or subtract - hexadecimal constants or symbols. If you need more elaborate - expressions, consider using the linker command language from a - script (*note Assignment: Symbol Definitions: Assignment.). - *Note:* there should be no white space between SYMBOL, the equals - sign ("="), and EXPRESSION. - -`-e ENTRY' - Use ENTRY as the explicit symbol for beginning execution of your - program, rather than the default entry point. *Note Entry Point::, - for a discussion of defaults and other ways of specifying the - entry point. - -`-F' -`-FFORMAT' - Ignored. Some older linkers used this option throughout a - compilation toolchain for specifying object-file format for both - input and output object files. The mechanisms `ld' uses for this - purpose (the `-b' or `-format' options for input files, `-oformat' - option or the `TARGET' command in linker scripts for output files, - the `GNUTARGET' environment variable) are more flexible, but `ld' - accepts the `-F' option for compatibility with scripts written to - call the old linker. - -`-format INPUT-FORMAT' - Synonym for `-b INPUT-FORMAT'. - -`-g' - Ignored. Provided for compatibility with other tools. - -`-GVALUE' -`-G VALUE' - Set the maximum size of objects to be optimized using the GP - register to SIZE under MIPS ECOFF. Ignored for other object file - formats. - -`--help' - Print a summary of the command-line options on the standard output - and exit. This option and `--version' begin with two dashes - instead of one for compatibility with other GNU programs. The - other options start with only one dash for compatibility with - other linkers. - -`-i' - Perform an incremental link (same as option `-r'). - -`-lAR' - Add archive file ARCHIVE to the list of files to link. This - option may be used any number of times. `ld' will search its - path-list for occurrences of `libAR.a' for every ARCHIVE specified. - -`-LSEARCHDIR' -`-L SEARCHDIR' - Add path SEARCHDIR to the list of paths that `ld' will search for - archive libraries and `ld' control scripts. You may use this - option any number of times. - - The default set of paths searched (without being specified with - `-L') depends on which emulation mode `ld' is using, and in some - cases also on how it was configured. *Note Environment::. - - The paths can also be specified in a link script with the - `SEARCH_DIR' command. - -`-M' - Print (to the standard output) a link map--diagnostic information - about where symbols are mapped by `ld', and information on global - common storage allocation. - -`-Map MAPFILE' - Print to the file MAPFILE a link map--diagnostic information about - where symbols are mapped by `ld', and information on global common - storage allocation. - -`-mEMULATION' -`-m EMULATION' - Emulate the EMULATION linker. You can list the available - emulations with the `-V' option. The default is the system for - which you configured `ld'. - -`-N' - Set the text and data sections to be readable and writable. Also, - do not page-align the data segment. If the output format supports - Unix style magic numbers, mark the output as `OMAGIC'. - -`-n' - Set the text segment to be read only, and mark the output as - `NMAGIC' if possible. - -`-noinhibit-exec' - Retain the executable output file whenever it is still usable. - Normally, the linker will not produce an output file if it - encounters errors during the link process; it exits without - writing an output file when it issues any error whatsoever. - -`-o OUTPUT' - Use OUTPUT as the name for the program produced by `ld'; if this - option is not specified, the name `a.out' is used by default. The - script command `OUTPUT' can also specify the output file name. - -`-oformat OUTPUT-FORMAT' - Specify the binary format for the output object file. You don't - usually need to specify this, as `ld' is configured to produce as - a default output format the most usual format on each machine. - oUTPUT-FORMAT is a text string, the name of a particular format - supported by the BFD libraries. (You can list the available binary - formats with `objdump -i'.) The script command `OUTPUT_FORMAT' - can also specify the output format, but this option overrides it. - *Note BFD::. - -`-R FILENAME' - Read symbol names and their addresses from FILENAME, but do not - relocate it or include it in the output. This allows your output - file to refer symbolically to absolute locations of memory defined - in other programs. - -`-relax' - An option with machine dependent effects. Currently this option - is only supported on the H8/300. *Note `ld' and the H8/300: - H8/300. - - On some platforms, use option performs global optimizations that - become possible when the linker resolves addressing in the - program, such as relaxing address modes and synthesizing new - instructions in the output object file. - - On platforms where this is not supported, `-relax' is accepted, but - ignored. - -`-r' - Generate relocatable output--i.e., generate an output file that - can in turn serve as input to `ld'. This is often called "partial - linking". As a side effect, in environments that support standard - Unix magic numbers, this option also sets the output file's magic - number to `OMAGIC'. If this option is not specified, an absolute - file is produced. When linking C++ programs, this option *will - not* resolve references to constructors; to do that, use `-Ur'. - - This option does the same thing as `-i'. - -`-S' - Omit debugger symbol information (but not all symbols) from the - output file. - -`-s' - Omit all symbol information from the output file. - -`-sort-common' - Normally, when `ld' places the global common symbols in the - appropriate output sections, it sorts them by size. First come - all the one byte symbols, then all the two bytes, then all the - four bytes, and then everything else. This is to prevent gaps - between symbols due to alignment constraints. This option - disables that sorting. - -`-Tbss ORG' -`-Tdata ORG' -`-Ttext ORG' - Use ORG as the starting address for--respectively--the `bss', - `data', or the `text' segment of the output file. ORG must be a - single hexadecimal integer; for compatibility with other linkers, - you may omit the leading `0x' usually associated with hexadecimal - values. - -`-T COMMANDFILE' -`-TCOMMANDFILE' - Read link commands from the file COMMANDFILE. These commands - completely override `ld''s default link format (rather than adding - to it); COMMANDFILE must specify everything necessary to describe - the target format. *Note Commands::. If COMMANDFILE does not - exist, `ld' looks for it in the directories specified by any - preceding `-L' options. Multiple `-T' options accumulate. - -`-t' - Print the names of the input files as `ld' processes them. - -`-u SYMBOL' - Force SYMBOL to be entered in the output file as an undefined - symbol. Doing this may, for example, trigger linking of - additional modules from standard libraries. `-u' may be repeated - with different option arguments to enter additional undefined - symbols. - -`-Ur' - For anything other than C++ programs, this option is equivalent to - `-r': it generates relocatable output--i.e., an output file that - can in turn serve as input to `ld'. When linking C++ programs, - `-Ur' *will* resolve references to constructors, unlike `-r'. It - does not work to use `-Ur' on files that were themselves linked - with `-Ur'; once the constructor table has been built, it can not - be added to. Use `-Ur' only for the last partial link, and `-r' - for the others. - -`-V' - Display the version number for `ld' and list the supported - emulations. Display which input files can and can not be opened. - -`-v' - Display the version number for `ld'. - -`--version' - Display the version number for `ld' and exit. - -`-warn-common' - Warn when a common symbol is combined with another common symbol - or with a symbol definition. Unix linkers allow this somewhat - sloppy practice, but linkers on some other operating systems do - not. This option allows you to find potential problems from - combining global symbols. Unfortunately, some C libraries use - this practice, so you may get some warnings about symbols in the - libraries as well as in your programs. - - There are three kinds of global symbols, illustrated here by C - examples: - - `int i = 1;' - A definition, which goes in the initialized data section of - the output file. - - `extern int i;' - An undefined reference, which does not allocate space. There - must be either a definition or a common symbol for the - variable somewhere. - - `int i;' - A common symbol. If there are only (one or more) common - symbols for a variable, it goes in the uninitialized data - area of the output file. The linker merges multiple common - symbols for the same variable into a single symbol. If they - are of different sizes, it picks the largest size. The - linker turns a common symbol into a declaration, if there is - a definition of the same variable. - - The `-warn-common' option can produce five kinds of warnings. Each - warning consists of a pair of lines: the first describes the - symbol just encountered, and the second describes the previous - symbol encountered with the same name. One or both of the two - symbols will be a common symbol. - - 1. Turning a common symbol into a reference, because there is - already a definition for the symbol. - FILE(SECTION): warning: common of `SYMBOL' - overridden by definition - FILE(SECTION): warning: defined here - - 2. Turning a common symbol into a reference, because a later - definition for the symbol is encountered. This is the same - as the previous case, except that the symbols are encountered - in a different order. - FILE(SECTION): warning: definition of `SYMBOL' - overriding common - FILE(SECTION): warning: common is here - - 3. Merging a common symbol with a previous same-sized common - symbol. - FILE(SECTION): warning: multiple common - of `SYMBOL' - FILE(SECTION): warning: previous common is here - - 4. Merging a common symbol with a previous larger common symbol. - FILE(SECTION): warning: common of `SYMBOL' - overridden by larger common - FILE(SECTION): warning: larger common is here - - 5. Merging a common symbol with a previous smaller common - symbol. This is the same as the previous case, except that - the symbols are encountered in a different order. - FILE(SECTION): warning: common of `SYMBOL' - overriding smaller common - FILE(SECTION): warning: smaller common is here - -`-X' - If `-s' or `-S' is also specified, delete only local symbols - beginning with `L'. - -`-x' - If `-s' or `-S' is also specified, delete all local symbols, not - just those beginning with `L'. - -`-ySYMBOL' - Print the name of each linked file in which SYMBOL appears. This - option may be given any number of times. On many systems it is - necessary to prepend an underscore. - - This option is useful when you have an undefined symbol in your - link but don't know where the reference is coming from. - - -File: ld.info, Node: Environment, Prev: Options, Up: Invocation - -Environment Variables -===================== - - You can change the behavior of `ld' with the environment variable -`GNUTARGET'. - - `GNUTARGET' determines the input-file object format if you don't use -`-b' (or its synonym `-format'). Its value should be one of the BFD -names for an input format (*note BFD::.). If there is no `GNUTARGET' -in the environment, `ld' uses the natural format of the target. If -`GNUTARGET' is set to `default' then BFD attempts to discover the input -format by examining binary input files; this method often succeeds, but -there are potential ambiguities, since there is no method of ensuring -that the magic number used to specify object-file formats is unique. -However, the configuration procedure for BFD on each system places the -conventional format for that system first in the search-list, so -ambiguities are resolved in favor of convention. - - -File: ld.info, Node: Commands, Next: Machine Dependent, Prev: Invocation, Up: Top - -Command Language -**************** - - The command language provides explicit control over the link process, -allowing complete specification of the mapping between the linker's -input files and its output. It controls: - * input files - - * file formats - - * output file layout - - * addresses of sections - - * placement of common blocks - - You may supply a command file (also known as a link script) to the -linker either explicitly through the `-T' option, or implicitly as an -ordinary file. If the linker opens a file which it cannot recognize as -a supported object or archive format, it reports an error. - -* Menu: - -* Scripts:: Linker Scripts -* Expressions:: Expressions -* MEMORY:: MEMORY Command -* SECTIONS:: SECTIONS Command -* Entry Point:: The Entry Point -* Option Commands:: Option Commands - - -File: ld.info, Node: Scripts, Next: Expressions, Up: Commands - -Linker Scripts -============== - - The `ld' command language is a collection of statements; some are -simple keywords setting a particular option, some are used to select and -group input files or name output files; and two statement types have a -fundamental and pervasive impact on the linking process. - - The most fundamental command of the `ld' command language is the -`SECTIONS' command (*note SECTIONS::.). Every meaningful command -script must have a `SECTIONS' command: it specifies a "picture" of the -output file's layout, in varying degrees of detail. No other command -is required in all cases. - - The `MEMORY' command complements `SECTIONS' by describing the -available memory in the target architecture. This command is optional; -if you don't use a `MEMORY' command, `ld' assumes sufficient memory is -available in a contiguous block for all output. *Note MEMORY::. - - You may include comments in linker scripts just as in C: delimited -by `/*' and `*/'. As in C, comments are syntactically equivalent to -whitespace. - - -File: ld.info, Node: Expressions, Next: MEMORY, Prev: Scripts, Up: Commands - -Expressions -=========== - - Many useful commands involve arithmetic expressions. The syntax for -expressions in the command language is identical to that of C -expressions, with the following features: - * All expressions evaluated as integers and are of "long" or - "unsigned long" type. - - * All constants are integers. - - * All of the C arithmetic operators are provided. - - * You may reference, define, and create global variables. - - * You may call special purpose built-in functions. - -* Menu: - -* Integers:: Integers -* Symbols:: Symbol Names -* Location Counter:: The Location Counter -* Operators:: Operators -* Evaluation:: Evaluation -* Assignment:: Assignment: Defining Symbols -* Arithmetic Functions:: Built-In Functions - - -File: ld.info, Node: Integers, Next: Symbols, Up: Expressions - -Integers --------- - - An octal integer is `0' followed by zero or more of the octal digits -(`01234567'). - _as_octal = 0157255; - - A decimal integer starts with a non-zero digit followed by zero or -more digits (`0123456789'). - _as_decimal = 57005; - - A hexadecimal integer is `0x' or `0X' followed by one or more -hexadecimal digits chosen from `0123456789abcdefABCDEF'. - _as_hex = 0xdead; - - To write a negative integer, use the prefix operator `-'; *note -Operators::.. - _as_neg = -57005; - - Additionally the suffixes `K' and `M' may be used to scale a -constant by `1024' or `1024*1024' respectively. For example, the -following all refer to the same quantity: - - _fourk_1 = 4K; - _fourk_2 = 4096; - _fourk_3 = 0x1000; - - -File: ld.info, Node: Symbols, Next: Location Counter, Prev: Integers, Up: Expressions - -Symbol Names ------------- - - Unless quoted, symbol names start with a letter, underscore, point or -hyphen and may include any letters, underscores, digits, points, and -minus signs. Unquoted symbol names must not conflict with any -keywords. You can specify a symbol which contains odd characters or has -the same name as a keyword, by surrounding the symbol name in double -quotes: - "SECTION" = 9; - "with a space" = "also with a space" + 10; - - -File: ld.info, Node: Location Counter, Next: Operators, Prev: Symbols, Up: Expressions - -The Location Counter --------------------- - - The special linker variable "dot" `.' always contains the current -output location counter. Since the `.' always refers to a location in -an output section, it must always appear in an expression within a -`SECTIONS' command. The `.' symbol may appear anywhere that an ordinary -symbol is allowed in an expression, but its assignments have a side -effect. Assigning a value to the `.' symbol will cause the location -counter to be moved. This may be used to create holes in the output -section. The location counter may never be moved backwards. - SECTIONS - { - output : - { - file1(.text) - . = . + 1000; - file2(.text) - . += 1000; - file3(.text) - } = 0x1234; - } - -In the previous example, `file1' is located at the beginning of the -output section, then there is a 1000 byte gap. Then `file2' appears, -also with a 1000 byte gap following before `file3' is loaded. The -notation `= 0x1234' specifies what data to write in the gaps (*note -Section Options::.). - - -File: ld.info, Node: Operators, Next: Evaluation, Prev: Location Counter, Up: Expressions - -Operators ---------- - - The linker recognizes the standard C set of arithmetic operators, -with the standard bindings and precedence levels: - precedence associativity Operators Notes - (highest) - 1 left ! - ~ (1) - 2 left * / % - 3 left + - - 4 left >> << - 5 left == != > < <= >= - 6 left & - 7 left | - 8 left && - 9 left || - 10 right ? : - 11 right &= += -= *= /= (2) - (lowest) - Notes: (1) Prefix operators (2) *Note Assignment:: - - -File: ld.info, Node: Evaluation, Next: Assignment, Prev: Operators, Up: Expressions - -Evaluation ----------- - - The linker uses "lazy evaluation" for expressions; it only calculates -an expression when absolutely necessary. The linker needs the value of -the start address, and the lengths of memory regions, in order to do any -linking at all; these values are computed as soon as possible when the -linker reads in the command file. However, other values (such as symbol -values) are not known or needed until after storage allocation. Such -values are evaluated later, when other information (such as the sizes of -output sections) is available for use in the symbol assignment -expression. - - -File: ld.info, Node: Assignment, Next: Arithmetic Functions, Prev: Evaluation, Up: Expressions - -Assignment: Defining Symbols ----------------------------- - - You may create global symbols, and assign values (addresses) to -global symbols, using any of the C assignment operators: - -`SYMBOL = EXPRESSION ;' -`SYMBOL &= EXPRESSION ;' -`SYMBOL += EXPRESSION ;' -`SYMBOL -= EXPRESSION ;' -`SYMBOL *= EXPRESSION ;' -`SYMBOL /= EXPRESSION ;' - Two things distinguish assignment from other operators in `ld' -expressions. - * Assignment may only be used at the root of an expression; `a=b+3;' - is allowed, but `a+b=3;' is an error. - - * You must place a trailing semicolon (";") at the end of an - assignment statement. - - Assignment statements may appear: - * as commands in their own right in an `ld' script; or - - * as independent statements within a `SECTIONS' command; or - - * as part of the contents of a section definition in a `SECTIONS' - command. - - The first two cases are equivalent in effect--both define a symbol -with an absolute address. The last case defines a symbol whose address -is relative to a particular section (*note SECTIONS::.). - - When a linker expression is evaluated and assigned to a variable, it -is given either an absolute or a relocatable type. An absolute -expression type is one in which the symbol contains the value that it -will have in the output file; a relocatable expression type is one in -which the value is expressed as a fixed offset from the base of a -section. - - The type of the expression is controlled by its position in the -script file. A symbol assigned within a section definition is created -relative to the base of the section; a symbol assigned in any other -place is created as an absolute symbol. Since a symbol created within a -section definition is relative to the base of the section, it will -remain relocatable if relocatable output is requested. A symbol may be -created with an absolute value even when assigned to within a section -definition by using the absolute assignment function `ABSOLUTE'. For -example, to create an absolute symbol whose address is the last byte of -an output section named `.data': - SECTIONS{ ... - .data : - { - *(.data) - _edata = ABSOLUTE(.) ; - } - ... } - - The linker tries to put off the evaluation of an assignment until all -the terms in the source expression are known (*note Evaluation::.). For -instance, the sizes of sections cannot be known until after allocation, -so assignments dependent upon these are not performed until after -allocation. Some expressions, such as those depending upon the location -counter "dot", `.' must be evaluated during allocation. If the result -of an expression is required, but the value is not available, then an -error results. For example, a script like the following - SECTIONS { ... - text 9+this_isnt_constant : - { ... - } - ... } - -will cause the error message "`Non constant expression for initial -address'". - - -File: ld.info, Node: Arithmetic Functions, Prev: Assignment, Up: Expressions - -Arithmetic Functions --------------------- - - The command language includes a number of built-in functions for use -in link script expressions. -`ABSOLUTE(EXP)' - Return the absolute (non-relocatable, as opposed to non-negative) - value of the expression EXP. Primarily useful to assign an - absolute value to a symbol within a section definition, where - symbol values are normally section-relative. - -`ADDR(SECTION)' - Return the absolute address of the named SECTION. Your script must - previously have defined the location of that section. In the - following example, `symbol_1' and `symbol_2' are assigned identical - values: - SECTIONS{ ... - .output1 : - { - start_of_output_1 = ABSOLUTE(.); - ... - } - .output : - { - symbol_1 = ADDR(.output1); - symbol_2 = start_of_output_1; - } - ... } - -`ALIGN(EXP)' - Return the result of the current location counter (`.') aligned to - the next EXP boundary. EXP must be an expression whose value is a - power of two. This is equivalent to - (. + EXP - 1) & ~(EXP - 1) - - `ALIGN' doesn't change the value of the location counter--it just - does arithmetic on it. As an example, to align the output `.data' - section to the next `0x2000' byte boundary after the preceding - section and to set a variable within the section to the next - `0x8000' boundary after the input sections: - SECTIONS{ ... - .data ALIGN(0x2000): { - *(.data) - variable = ALIGN(0x8000); - } - ... } - - The first use of `ALIGN' in this example specifies the location of - a section because it is used as the optional START attribute of a - section definition (*note Section Options::.). The second use - simply defines the value of a variable. - - The built-in `NEXT' is closely related to `ALIGN'. - -`DEFINED(SYMBOL)' - Return 1 if SYMBOL is in the linker global symbol table and is - defined, otherwise return 0. You can use this function to provide - default values for symbols. For example, the following - command-file fragment shows how to set a global symbol `begin' to - the first location in the `.text' section--but if a symbol called - `begin' already existed, its value is preserved: - SECTIONS{ ... - .text : { - begin = DEFINED(begin) ? begin : . ; - ... - } - ... } - -`NEXT(EXP)' - Return the next unallocated address that is a multiple of EXP. - This function is closely related to `ALIGN(EXP)'; unless you use - the `MEMORY' command to define discontinuous memory for the output - file, the two functions are equivalent. - -`SIZEOF(SECTION)' - Return the size in bytes of the named SECTION, if that section has - been allocated. In the following example, `symbol_1' and - `symbol_2' are assigned identical values: - SECTIONS{ ... - .output { - .start = . ; - ... - .end = . ; - } - symbol_1 = .end - .start ; - symbol_2 = SIZEOF(.output); - ... } - -`SIZEOF_HEADERS' -`sizeof_headers' - Return the size in bytes of the output file's headers. You can - use this number as the start address of the first section, if you - choose, to facilitate paging. - - -File: ld.info, Node: MEMORY, Next: SECTIONS, Prev: Expressions, Up: Commands - -Memory Layout -============= - - The linker's default configuration permits allocation of all -available memory. You can override this configuration by using the -`MEMORY' command. The `MEMORY' command describes the location and size -of blocks of memory in the target. By using it carefully, you can -describe which memory regions may be used by the linker, and which -memory regions it must avoid. The linker does not shuffle sections to -fit into the available regions, but does move the requested sections -into the correct regions and issue errors when the regions become too -full. - - A command file may contain at most one use of the `MEMORY' command; -however, you can define as many blocks of memory within it as you wish. -The syntax is: - - MEMORY - { - NAME (ATTR) : ORIGIN = ORIGIN, LENGTH = LEN - ... - } - -`NAME' - is a name used internally by the linker to refer to the region. Any - symbol name may be used. The region names are stored in a separate - name space, and will not conflict with symbols, file names or - section names. Use distinct names to specify multiple regions. - -`(ATTR)' - is an optional list of attributes, permitted for compatibility - with the AT&T linker but not used by `ld' beyond checking that the - attribute list is valid. Valid attribute lists must be made up of - the characters "`LIRWX'". If you omit the attribute list, you may - omit the parentheses around it as well. - -`ORIGIN' - is the start address of the region in physical memory. It is an - expression that must evaluate to a constant before memory - allocation is performed. The keyword `ORIGIN' may be abbreviated - to `org' or `o' (but not, for example, `ORG'). - -`LEN' - is the size in bytes of the region (an expression). The keyword - `LENGTH' may be abbreviated to `len' or `l'. - - For example, to specify that memory has two regions available for -allocation--one starting at 0 for 256 kilobytes, and the other starting -at `0x40000000' for four megabytes: - - MEMORY - { - rom : ORIGIN = 0, LENGTH = 256K - ram : org = 0x40000000, l = 4M - } - - Once you have defined a region of memory named MEM, you can direct -specific output sections there by using a command ending in `>MEM' -within the `SECTIONS' command (*note Section Options::.). If the -combined output sections directed to a region are too big for the -region, the linker will issue an error message. - - -File: ld.info, Node: SECTIONS, Next: Entry Point, Prev: MEMORY, Up: Commands - -Specifying Output Sections -========================== - - The `SECTIONS' command controls exactly where input sections are -placed into output sections, their order in the output file, and to -which output sections they are allocated. - - You may use at most one `SECTIONS' command in a script file, but you -can have as many statements within it as you wish. Statements within -the `SECTIONS' command can do one of three things: - * define the entry point; - - * assign a value to a symbol; - - * describe the placement of a named output section, and which input - sections go into it. - - You can also use the first two operations--defining the entry point -and defining symbols--outside the `SECTIONS' command: *note Entry -Point::., and *note Assignment::.. They are permitted here as well for -your convenience in reading the script, so that symbols and the entry -point can be defined at meaningful points in your output-file layout. - - When no `SECTIONS' command is given, the linker places each input -section into an identically named output section in the order that the -sections are first encountered in the input files. If all input -sections are present in the first file, for example, the order of -sections in the output file will match the order in the first input -file. - -* Menu: - -* Section Definition:: Section Definitions -* Section Placement:: Section Placement -* Section Data Expressions:: Section Data Expressions -* Section Options:: Optional Section Attributes - - -File: ld.info, Node: Section Definition, Next: Section Placement, Up: SECTIONS - -Section Definitions -------------------- - - The most frequently used statement in the `SECTIONS' command is the -"section definition", which specifies the properties of an output -section: its location, alignment, contents, fill pattern, and target -memory region. Most of these specifications are optional; the simplest -form of a section definition is - SECTIONS { ... - SECNAME : { - CONTENTS - } - ... } - -SECNAME is the name of the output section, and CONTENTS a specification -of what goes there--for example, a list of input files or sections of -input files (*note Section Placement::.). As you might assume, the -whitespace shown is optional. You do need the colon `:' and the braces -`{}', however. - - SECNAME must meet the constraints of your output format. In formats -which only support a limited number of sections, such as `a.out', the -name must be one of the names supported by the format (`a.out', for -example, allows only `.text', `.data' or `.bss'). If the output format -supports any number of sections, but with numbers and not names (as is -the case for Oasys), the name should be supplied as a quoted numeric -string. A section name may consist of any sequence of characters, but -any name which does not conform to the standard `ld' symbol name syntax -must be quoted. *Note Symbol Names: Symbols. - - -File: ld.info, Node: Section Placement, Next: Section Data Expressions, Prev: Section Definition, Up: SECTIONS - -Section Placement ------------------ - - In a section definition, you can specify the contents of an output -section by listing particular input files, by listing particular -input-file sections, or by a combination of the two. You can also -place arbitrary data in the section, and define symbols relative to the -beginning of the section. - - The CONTENTS of a section definition may include any of the -following kinds of statement. You can include as many of these as you -like in a single section definition, separated from one another by -whitespace. - -`FILENAME' - You may simply name a particular input file to be placed in the - current output section; *all* sections from that file are placed - in the current section definition. If the file name has already - been mentioned in another section definition, with an explicit - section name list, then only those sections which have not yet - been allocated are used. - - To specify a list of particular files by name: - .data : { afile.o bfile.o cfile.o } - - The example also illustrates that multiple statements can be - included in the contents of a section definition, since each file - name is a separate statement. - -`FILENAME( SECTION )' -`FILENAME( SECTION, SECTION, ... )' -`FILENAME( SECTION SECTION ... )' - You can name one or more sections from your input files, for - insertion in the current output section. If you wish to specify a - list of input-file sections inside the parentheses, you may - separate the section names by either commas or whitespace. - -`* (SECTION)' -`* (SECTION, SECTION, ...)' -`* (SECTION SECTION ...)' - Instead of explicitly naming particular input files in a link - control script, you can refer to *all* files from the `ld' command - line: use `*' instead of a particular file name before the - parenthesized input-file section list. - - If you have already explicitly included some files by name, `*' - refers to all *remaining* files--those whose places in the output - file have not yet been defined. - - For example, to copy sections `1' through `4' from an Oasys file - into the `.text' section of an `a.out' file, and sections `13' and - `14' into the `.data' section: - SECTIONS { - .text :{ - *("1" "2" "3" "4") - } - - .data :{ - *("13" "14") - } - } - - `[ SECTION ... ]' used to be accepted as an alternate way to - specify named sections from all unallocated input files. Because - some operating systems (VMS) allow brackets in file names, that - notation is no longer supported. - -`FILENAME`( COMMON )'' -`*( COMMON )' - Specify where in your output file to place uninitialized data with - this notation. `*(COMMON)' by itself refers to all uninitialized - data from all input files (so far as it is not yet allocated); - FILENAME`(COMMON)' refers to uninitialized data from a particular - file. Both are special cases of the general mechanisms for - specifying where to place input-file sections: `ld' permits you to - refer to uninitialized data as if it were in an input-file section - named `COMMON', regardless of the input file's format. - - For example, the following command script arranges the output file -into three consecutive sections, named `.text', `.data', and `.bss', -taking the input for each from the correspondingly named sections of -all the input files: - SECTIONS { - .text : { *(.text) } - .data : { *(.data) } - .bss : { *(.bss) *(COMMON) } - } - - The following example reads all of the sections from file `all.o' -and places them at the start of output section `outputa' which starts -at location `0x10000'. All of section `.input1' from file `foo.o' -follows immediately, in the same output section. All of section -`.input2' from `foo.o' goes into output section `outputb', followed by -section `.input1' from `foo1.o'. All of the remaining `.input1' and -`.input2' sections from any files are written to output section -`outputc'. - - SECTIONS { - outputa 0x10000 : - { - all.o - foo.o (.input1) - } - outputb : - { - foo.o (.input2) - foo1.o (.input1) - } - outputc : - { - *(.input1) - *(.input2) - } - } - - -File: ld.info, Node: Section Data Expressions, Next: Section Options, Prev: Section Placement, Up: SECTIONS - -Section Data Expressions ------------------------- - - The foregoing statements arrange, in your output file, data -originating from your input files. You can also place data directly in -an output section from the link command script. Most of these -additional statements involve expressions; *note Expressions::.. -Although these statements are shown separately here for ease of -presentation, no such segregation is needed within a section definition -in the `SECTIONS' command; you can intermix them freely with any of the -statements we've just described. - -`CREATE_OBJECT_SYMBOLS' - Create a symbol for each input file in the current section, set to - the address of the first byte of data written from that input - file. For instance, with `a.out' files it is conventional to have - a symbol for each input file. You can accomplish this by defining - the output `.text' section as follows: - SECTIONS { - .text 0x2020 : - { - CREATE_OBJECT_SYMBOLS - *(.text) - _etext = ALIGN(0x2000); - } - ... - } - - If `sample.ld' is a file containing this script, and `a.o', `b.o', - `c.o', and `d.o' are four input files with contents like the - following-- - /* a.c */ - - afunction() { } - int adata=1; - int abss; - - `ld -M -T sample.ld a.o b.o c.o d.o' would create a map like this, - containing symbols matching the object file names: - 00000000 A __DYNAMIC - 00004020 B _abss - 00004000 D _adata - 00002020 T _afunction - 00004024 B _bbss - 00004008 D _bdata - 00002038 T _bfunction - 00004028 B _cbss - 00004010 D _cdata - 00002050 T _cfunction - 0000402c B _dbss - 00004018 D _ddata - 00002068 T _dfunction - 00004020 D _edata - 00004030 B _end - 00004000 T _etext - 00002020 t a.o - 00002038 t b.o - 00002050 t c.o - 00002068 t d.o - -`SYMBOL = EXPRESSION ;' -`SYMBOL F= EXPRESSION ;' - SYMBOL is any symbol name (*note Symbols::.). "F=" refers to any - of the operators `&= += -= *= /=' which combine arithmetic and - assignment. - - When you assign a value to a symbol within a particular section - definition, the value is relative to the beginning of the section - (*note Assignment::.). If you write - SECTIONS { - abs = 14 ; - ... - .data : { ... rel = 14 ; ... } - abs2 = 14 + ADDR(.data); - ... - } - - `abs' and `rel' do not have the same value; `rel' has the same - value as `abs2'. - -`BYTE(EXPRESSION)' -`SHORT(EXPRESSION)' -`LONG(EXPRESSION)' - By including one of these three statements in a section - definition, you can explicitly place one, two, or four bytes - (respectively) at the current address of that section. - - Multiple-byte quantities are represented in whatever byte order is - appropriate for the output file format (*note BFD::.). - -`FILL(EXPRESSION)' - Specify the "fill pattern" for the current section. Any otherwise - unspecified regions of memory within the section (for example, - regions you skip over by assigning a new value to the location - counter `.') are filled with the two least significant bytes from - the EXPRESSION argument. A `FILL' statement covers memory - locations *after* the point it occurs in the section definition; by - including more than one `FILL' statement, you can have different - fill patterns in different parts of an output section. - diff --git a/ld/ld.info-2 b/ld/ld.info-2 deleted file mode 100644 index 5a93f63..0000000 --- a/ld/ld.info-2 +++ /dev/null @@ -1,941 +0,0 @@ -This is Info file ld.info, produced by Makeinfo-1.55 from the input -file ./ld.texinfo. - -START-INFO-DIR-ENTRY -* Ld:: The GNU linker. -END-INFO-DIR-ENTRY - - This file documents the GNU linker LD. - - Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -File: ld.info, Node: Section Options, Prev: Section Data Expressions, Up: SECTIONS - -Optional Section Attributes ---------------------------- - - Here is the full syntax of a section definition, including all the -optional portions: - - SECTIONS { - ... - SECNAME START BLOCK(ALIGN) (NOLOAD) : { CONTENTS } =FILL >REGION - ... - } - - SECNAME and CONTENTS are required. *Note Section Definition::, and -*note Section Placement::. for details on CONTENTS. The remaining -elements--START, `BLOCK(ALIGN)', `(NOLOAD)' `=FILL', and `>REGION'--are -all optional. - -`START' - You can force the output section to be loaded at a specified - address by specifying START immediately following the section name. - sTART can be represented as any expression. The following example - generates section OUTPUT at location `0x40000000': - SECTIONS { - ... - output 0x40000000: { - ... - } - ... - } - -`BLOCK(ALIGN)' - You can include `BLOCK()' specification to advance the location - counter `.' prior to the beginning of the section, so that the - section will begin at the specified alignment. ALIGN is an - expression. - -`(NOLOAD)' - Use `(NOLOAD)' to prevent a section from being loaded into memory - each time it is accessed. For example, in the script sample - below, the `ROM' segment is addressed at memory location `0' and - does not need to be loaded into each object file: - SECTIONS { - ROM 0 (NOLOAD) : { ... } - ... - } - -`=FILL' - Including `=FILL' in a section definition specifies the initial - fill value for that section. You may use any expression to - specify FILL. Any unallocated holes in the current output section - when written to the output file will be filled with the two least - significant bytes of the value, repeated as necessary. You can - also change the fill value with a `FILL' statement in the CONTENTS - of a section definition. - -`>REGION' - Assign this section to a previously defined region of memory. - *Note MEMORY::. - - -File: ld.info, Node: Entry Point, Next: Option Commands, Prev: SECTIONS, Up: Commands - -The Entry Point -=============== - - The linker command language includes a command specifically for -defining the first executable instruction in an output file (its "entry -point"). Its argument is a symbol name: - ENTRY(SYMBOL) - - Like symbol assignments, the `ENTRY' command may be placed either as -an independent command in the command file, or among the section -definitions within the `SECTIONS' command--whatever makes the most -sense for your layout. - - `ENTRY' is only one of several ways of choosing the entry point. -You may indicate it in any of the following ways (shown in descending -order of priority: methods higher in the list override methods lower -down). - * the `-e' ENTRY command-line option; - - * the `ENTRY(SYMBOL' command in a linker control script; - - * the value of the symbol `start', if present; - - * the value of the symbol `_main', if present; - - * the address of the first byte of the `.text' section, if present; - - * The address `0'. - - For example, you can use these rules to generate an entry point with -an assignment statement: if no symbol `start' is defined within your -input files, you can simply define it, assigning it an appropriate -value-- - start = 0x2020; - -The example shows an absolute address, but you can use any expression. -For example, if your input object files use some other symbol-name -convention for the entry point, you can just assign the value of -whatever symbol contains the start address to `start': - start = other_symbol ; - - -File: ld.info, Node: Option Commands, Prev: Entry Point, Up: Commands - -Option Commands -=============== - - The command language includes a number of other commands that you can -use for specialized purposes. They are similar in purpose to -command-line options. - -`FLOAT' -`NOFLOAT' - These keywords were used in some older linkers to request a - particular math subroutine library. `ld' doesn't use the - keywords, assuming instead that any necessary subroutines are in - libraries specified using the general mechanisms for linking to - archives; but to permit the use of scripts that were written for - the older linkers, the keywords `FLOAT' and `NOFLOAT' are accepted - and ignored. - -`FORCE_COMMON_ALLOCATION' - This command has the same effect as the `-d' command-line option: - to make `ld' assign space to common symbols even if a relocatable - output file is specified (`-r'). - -`INPUT ( FILE, FILE, ... )' -`INPUT ( FILE FILE ... )' - Use this command to include binary input files in the link, without - including them in a particular section definition. Specify the - full name for each FILE, including `.a' if required. - - `ld' searches for each FILE through the archive-library search - path, just as for files you specify on the command line. See the - description of `-L' in *Note Command Line Options: Options. - -`OUTPUT ( FILENAME )' - Use this command to name the link output file FILENAME. The - effect of `OUTPUT(FILENAME)' is identical to the effect of - `-o FILENAME', which overrides it. You can use this command to - supply a default output-file name other than `a.out'. - -`OUTPUT_ARCH ( BFDNAME )' - Specify a particular output machine architecture, with one of the - names used by the BFD back-end routines (*note BFD::.). This - command is often unnecessary; the architecture is most often set - implicitly by either the system BFD configuration or as a side - effect of the `OUTPUT_FORMAT' command. - -`OUTPUT_FORMAT ( BFDNAME )' - Specify a particular output format, with one of the names used by - the BFD back-end routines (*note BFD::.). The effect is identical - to the effect of the `-oformat' command-line option. This - selection will only affect the output file; the related command - `TARGET' affects primarily input files. - -`SEARCH_DIR ( PATH )' - Add PATH to the list of paths where `ld' looks for archive - libraries. `SEARCH_DIR(PATH)' has the same effect as `-LPATH' on - the command line. - -`STARTUP ( FILENAME )' - Ensure that FILENAME is the first input file used in the link - process. - -`TARGET ( FORMAT )' - Change the input-file object code format (like the command-line - option `-b' or its synonym `-format'). The argument FORMAT is one - of the strings used by BFD to name binary formats. If `TARGET' is - specified but `OUTPUT_FORMAT' is not, the last `TARGET' argument - is also used as the default format for the `ld' output file. - *Note BFD::. - - If you don't use the `TARGET' command, `ld' uses the value of the - environment variable `GNUTARGET', if available, to select the - output file format. If that variable is also absent, `ld' uses - the default format configured for your machine in the BFD - libraries. - - -File: ld.info, Node: Machine Dependent, Next: BFD, Prev: Commands, Up: Top - -Machine Dependent Features -************************** - - `ld' has additional features on some platforms; the following -sections describe them. Machines where `ld' has no additional -functionality are not listed. - -* Menu: - -* H8/300:: `ld' and the H8/300 -* i960:: `ld' and the Intel 960 family - - -File: ld.info, Node: H8/300, Next: i960, Up: Machine Dependent - -`ld' and the H8/300 -=================== - - For the H8/300, `ld' can perform these global optimizations when you -specify the `-relax' command-line option. - -*relaxing address modes* - `ld' finds all `jsr' and `jmp' instructions whose targets are - within eight bits, and turns them into eight-bit program-counter - relative `bsr' and `bra' instructions, respectively. - -*synthesizing instructions* - `ld' finds all `mov.b' instructions which use the sixteen-bit - absolute address form, but refer to the top page of memory, and - changes them to use the eight-bit address form. (That is: the - linker turns `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the - address AA is in the top page of memory). - - -File: ld.info, Node: i960, Prev: H8/300, Up: Machine Dependent - -`ld' and the Intel 960 family -============================= - - You can use the `-AARCHITECTURE' command line option to specify one -of the two-letter names identifying members of the 960 family; the -option specifies the desired output target, and warns of any -incompatible instructions in the input files. It also modifies the -linker's search strategy for archive libraries, to support the use of -libraries specific to each particular architecture, by including in the -search loop names suffixed with the string identifying the architecture. - - For example, if your `ld' command line included `-ACA' as well as -`-ltry', the linker would look (in its built-in search paths, and in -any paths you specify with `-L') for a library with the names - - try - libtry.a - tryca - libtryca.a - -The first two possibilities would be considered in any event; the last -two are due to the use of `-ACA'. - - You can meaningfully use `-A' more than once on a command line, since -the 960 architecture family allows combination of target architectures; -each use will add another pair of name variants to search for when `-l' -specifies a library. - - -File: ld.info, Node: BFD, Next: MRI, Prev: Machine Dependent, Up: Top - -BFD -*** - - The linker accesses object and archive files using the BFD libraries. -These libraries allow the linker to use the same routines to operate on -object files whatever the object file format. A different object file -format can be supported simply by creating a new BFD back end and adding -it to the library. You can use `objdump -i' (*note objdump: -(binutils.info)objdump.) to list all the formats available for each -architecture under BFD. This was the list of formats, and of -architectures supported for each format, as of the time this manual was -prepared: - BFD header file version 0.18 - a.out-i386 - (header big endian, data big endian) - m68k:68020 - a29k - sparc - i386 - a.out-sunos-big - (header big endian, data big endian) - m68k:68020 - a29k - sparc - i386 - b.out.big - (header big endian, data little endian) - i960:core - b.out.little - (header little endian, data little endian) - i960:core - coff-a29k-big - (header big endian, data big endian) - a29k - coff-h8300 - (header big endian, data big endian) - H8/300 - coff-i386 - (header little endian, data little endian) - i386 - coff-Intel-big - (header big endian, data little endian) - i960:core - coff-Intel-little - (header little endian, data little endian) - i960:core - coff-m68k - (header big endian, data big endian) - m68k:68020 - coff-m88kbcs - (header big endian, data big endian) - m88k:88100 - ecoff-bigmips - (header big endian, data big endian) - mips - ecoff-littlemips - (header little endian, data little endian) - mips - elf-big - (header big endian, data big endian) - m68k:68020 - vax - i960:core - a29k - sparc - mips - i386 - m88k:88100 - H8/300 - rs6000:6000 - elf-little - (header little endian, data little endian) - m68k:68020 - vax - i960:core - a29k - sparc - mips - i386 - m88k:88100 - H8/300 - rs6000:6000 - ieee - (header big endian, data big endian) - m68k:68020 - vax - i960:core - a29k - sparc - mips - i386 - m88k:88100 - H8/300 - rs6000:6000 - srec - (header big endian, data big endian) - m68k:68020 - vax - i960:core - a29k - sparc - mips - i386 - m88k:88100 - H8/300 - rs6000:6000 - - As with most implementations, BFD is a compromise between several -conflicting requirements. The major factor influencing BFD design was -efficiency: any time used converting between formats is time which -would not have been spent had BFD not been involved. This is partly -offset by abstraction payback; since BFD simplifies applications and -back ends, more time and care may be spent optimizing algorithms for a -greater speed. - - One minor artifact of the BFD solution which you should bear in mind -is the potential for information loss. There are two places where -useful information can be lost using the BFD mechanism: during -conversion and during output. *Note BFD information loss::. - -* Menu: - -* BFD outline:: How it works: an outline of BFD - - -File: ld.info, Node: BFD outline, Up: BFD - -How it works: an outline of BFD -=============================== - - When an object file is opened, BFD subroutines automatically -determine the format of the input object file. They then build a -descriptor in memory with pointers to routines that will be used to -access elements of the object file's data structures. - - As different information from the the object files is required, BFD -reads from different sections of the file and processes them. For -example, a very common operation for the linker is processing symbol -tables. Each BFD back end provides a routine for converting between -the object file's representation of symbols and an internal canonical -format. When the linker asks for the symbol table of an object file, it -calls through a memory pointer to the routine from the relevant BFD -back end which reads and converts the table into a canonical form. The -linker then operates upon the canonical form. When the link is finished -and the linker writes the output file's symbol table, another BFD back -end routine is called to take the newly created symbol table and -convert it into the chosen output format. - -* Menu: - -* BFD information loss:: Information Loss -* Canonical format:: The BFD canonical object-file format - - -File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline - -Information Loss ----------------- - - *Information can be lost during output.* The output formats -supported by BFD do not provide identical facilities, and information -which can be described in one form has nowhere to go in another format. -One example of this is alignment information in `b.out'. There is -nowhere in an `a.out' format file to store alignment information on the -contained data, so when a file is linked from `b.out' and an `a.out' -image is produced, alignment information will not propagate to the -output file. (The linker will still use the alignment information -internally, so the link is performed correctly). - - Another example is COFF section names. COFF files may contain an -unlimited number of sections, each one with a textual section name. If -the target of the link is a format which does not have many sections -(e.g., `a.out') or has sections without names (e.g., the Oasys format), -the link cannot be done simply. You can circumvent this problem by -describing the desired input-to-output section mapping with the linker -command language. - - *Information can be lost during canonicalization.* The BFD internal -canonical form of the external formats is not exhaustive; there are -structures in input formats for which there is no direct representation -internally. This means that the BFD back ends cannot maintain all -possible data richness through the transformation between external to -internal and back to external formats. - - This limitation is only a problem when an application reads one -format and writes another. Each BFD back end is responsible for -maintaining as much data as possible, and the internal BFD canonical -form has structures which are opaque to the BFD core, and exported only -to the back ends. When a file is read in one format, the canonical form -is generated for BFD and the application. At the same time, the back -end saves away any information which may otherwise be lost. If the data -is then written back in the same format, the back end routine will be -able to use the canonical form provided by the BFD core as well as the -information it prepared earlier. Since there is a great deal of -commonality between back ends, there is no information lost when -linking or copying big endian COFF to little endian COFF, or `a.out' to -`b.out'. When a mixture of formats is linked, the information is only -lost from the files whose format differs from the destination. - - -File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline - -The BFD canonical object-file format ------------------------------------- - - The greatest potential for loss of information occurs when there is -the least overlap between the information provided by the source -format, that stored by the canonical format, and that needed by the -destination format. A brief description of the canonical form may help -you understand which kinds of data you can count on preserving across -conversions. - -*files* - Information stored on a per-file basis includes target machine - architecture, particular implementation format type, a demand - pageable bit, and a write protected bit. Information like Unix - magic numbers is not stored here--only the magic numbers' meaning, - so a `ZMAGIC' file would have both the demand pageable bit and the - write protected text bit set. The byte order of the target is - stored on a per-file basis, so that big- and little-endian object - files may be used with one another. - -*sections* - Each section in the input file contains the name of the section, - the section's original address in the object file, size and - alignment information, various flags, and pointers into other BFD - data structures. - -*symbols* - Each symbol contains a pointer to the information for the object - file which originally defined it, its name, its value, and various - flag bits. When a BFD back end reads in a symbol table, it - relocates all symbols to make them relative to the base of the - section where they were defined. Doing this ensures that each - symbol points to its containing section. Each symbol also has a - varying amount of hidden private data for the BFD back end. Since - the symbol points to the original file, the private data format - for that symbol is accessible. `ld' can operate on a collection - of symbols of wildly different formats without problems. - - Normal global and simple local symbols are maintained on output, - so an output file (no matter its format) will retain symbols - pointing to functions and to global, static, and common variables. - Some symbol information is not worth retaining; in `a.out', type - information is stored in the symbol table as long symbol names. - This information would be useless to most COFF debuggers; the - linker has command line switches to allow users to throw it away. - - There is one word of type information within the symbol, so if the - format supports symbol type information within symbols (for - example, COFF, IEEE, Oasys) and the type is simple enough to fit - within one word (nearly everything but aggregates), the - information will be preserved. - -*relocation level* - Each canonical BFD relocation record contains a pointer to the - symbol to relocate to, the offset of the data to relocate, the - section the data is in, and a pointer to a relocation type - descriptor. Relocation is performed by passing messages through - the relocation type descriptor and the symbol pointer. Therefore, - relocations can be performed on output data using a relocation - method that is only available in one of the input formats. For - instance, Oasys provides a byte relocation format. A relocation - record requesting this relocation type would point indirectly to a - routine to perform this, so the relocation may be performed on a - byte being written to a 68k COFF file, even though 68k COFF has no - such relocation type. - -*line numbers* - Object formats can contain, for debugging purposes, some form of - mapping between symbols, source line numbers, and addresses in the - output file. These addresses have to be relocated along with the - symbol information. Each symbol with an associated list of line - number records points to the first record of the list. The head - of a line number list consists of a pointer to the symbol, which - allows finding out the address of the function whose line number - is being described. The rest of the list is made up of pairs: - offsets into the section and line numbers. Any format which can - simply derive this information can pass it successfully between - formats (COFF, IEEE and Oasys). - - -File: ld.info, Node: MRI, Next: Index, Prev: BFD, Up: Top - -MRI Compatible Script Files -*************************** - - To aid users making the transition to GNU `ld' from the MRI linker, -`ld' can use MRI compatible linker scripts as an alternative to the -more general-purpose linker scripting language described in *Note -Command Language: Commands. MRI compatible linker scripts have a much -simpler command set than the scripting language otherwise used with -`ld'. GNU `ld' supports the most commonly used MRI linker commands; -these commands are described here. - - In general, MRI scripts aren't of much use with the `a.out' object -file format, since it only has three sections and MRI scripts lack some -features to make use of them. - - You can specify a file containing an MRI-compatible script using the -`-c' command-line option. - - Each command in an MRI-compatible script occupies its own line; each -command line starts with the keyword that identifies the command (though -blank lines are also allowed for punctuation). If a line of an -MRI-compatible script begins with an unrecognized keyword, `ld' issues -a warning message, but continues processing the script. - - Lines beginning with `*' are comments. - - You can write these commands using all upper-case letters, or all -lower case; for example, `chip' is the same as `CHIP'. The following -list shows only the upper-case form of each command. - -`ABSOLUTE SECNAME' -`ABSOLUTE SECNAME, SECNAME, ... SECNAME' - Normally, `ld' includes in the output file all sections from all - the input files. However, in an MRI-compatible script, you can - use the `ABSOLUTE' command to restrict the sections that will be - present in your output program. If the `ABSOLUTE' command is used - at all in a script, then only the sections named explicitly in - `ABSOLUTE' commands will appear in the linker output. You can - still use other input sections (whatever you select on the command - line, or using `LOAD') to resolve addresses in the output file. - -`ALIAS OUT-SECNAME, IN-SECNAME' - Use this command to place the data from input section IN-SECNAME - in a section called OUT-SECNAME in the linker output file. - - IN-SECNAME may be an integer. - -`BASE EXPRESSION' - Use the value of EXPRESSION as the lowest address (other than - absolute addresses) in the output file. - -`CHIP EXPRESSION' -`CHIP EXPRESSION, EXPRESSION' - This command does nothing; it is accepted only for compatibility. - -`END' - This command does nothing whatever; it's only accepted for - compatibility. - -`FORMAT OUTPUT-FORMAT' - Similar to the `OUTPUT_FORMAT' command in the more general linker - language, but restricted to one of these output formats: - 1. S-records, if OUTPUT-FORMAT is `S' - - 2. IEEE, if OUTPUT-FORMAT is `IEEE' - - 3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is - `COFF' - -`LIST ANYTHING...' - Print (to the standard output file) a link map, as produced by the - `ld' command-line option `-M'. - - The keyword `LIST' may be followed by anything on the same line, - with no change in its effect. - -`LOAD FILENAME' -`LOAD FILENAME, FILENAME, ... FILENAME' - Include one or more object file FILENAME in the link; this has the - same effect as specifying FILENAME directly on the `ld' command - line. - -`NAME OUTPUT-NAME' - OUTPUT-NAME is the name for the program produced by `ld'; the - MRI-compatible command `NAME' is equivalent to the command-line - option `-o' or the general script language command `OUTPUT'. - -`ORDER SECNAME, SECNAME, ... SECNAME' -`ORDER SECNAME SECNAME SECNAME' - Normally, `ld' orders the sections in its output file in the order - in which they first appear in the input files. In an - MRI-compatible script, you can override this ordering with the - `ORDER' command. The sections you list with `ORDER' will appear - first in your output file, in the order specified. - -`PUBLIC NAME=EXPRESSION' -`PUBLIC NAME,EXPRESSION' -`PUBLIC NAME EXPRESSION' - Supply a value (EXPRESSION) for external symbol NAME used in the - linker input files. - -`SECT SECNAME, EXPRESSION' -`SECT SECNAME=EXPRESSION' -`SECT SECNAME EXPRESSION' - You can use any of these three forms of the `SECT' command to - specify the start address (EXPRESSION) for section SECNAME. If - you have more than one `SECT' statement for the same SECNAME, only - the *first* sets the start address. - - -File: ld.info, Node: Index, Prev: MRI, Up: Top - -Index -***** - -* Menu: - -* ": Symbols. -* *( COMMON ): Section Placement. -* *(SECTION): Section Placement. -* -help: Options. -* -version: Options. -* -AARCH: Options. -* -b FORMAT: Options. -* -Bstatic: Options. -* -c MRI-CMDFILE: Options. -* -d: Options. -* -dc: Options. -* -defsym SYMBOL=EXP: Options. -* -dp: Options. -* -e ENTRY: Options. -* -F: Options. -* -format: Options. -* -g: Options. -* -G: Options. -* -i: Options. -* -lARCHIVE: Options. -* -LDIR: Options. -* -M: Options. -* -m EMULATION: Options. -* -Map: Options. -* -N: Options. -* -n: Options. -* -noinhibit-exec: Options. -* -o OUTPUT: Options. -* -oformat: Options. -* -r: Options. -* -R FILE: Options. -* -relax: Options. -* -s: Options. -* -S: Options. -* -t: Options. -* -T SCRIPT: Options. -* -Tbss ORG: Options. -* -Tdata ORG: Options. -* -Ttext ORG: Options. -* -u SYMBOL: Options. -* -Ur: Options. -* -v: Options. -* -V: Options. -* -warn-comon: Options. -* -x: Options. -* -X: Options. -* -ySYMBOL: Options. -* .: Location Counter. -* 0x: Integers. -* ;: Assignment. -* =FILL: Section Options. -* >REGION: Section Options. -* ABSOLUTE (MRI): MRI. -* ALIAS (MRI): MRI. -* BASE (MRI): MRI. -* CHIP (MRI): MRI. -* END (MRI): MRI. -* FORMAT (MRI): MRI. -* LIST (MRI): MRI. -* LOAD (MRI): MRI. -* NAME (MRI): MRI. -* ORDER (MRI): MRI. -* PUBLIC (MRI): MRI. -* SECT (MRI): MRI. -* FILENAME: Section Placement. -* FILENAME(SECTION): Section Placement. -* SYMBOL = EXPRESSION ;: Section Data Expressions. -* SYMBOL F= EXPRESSION ;: Section Data Expressions. -* absolute and relocatable symbols: Assignment. -* ABSOLUTE(EXP): Arithmetic Functions. -* ADDR(SECTION): Arithmetic Functions. -* ALIGN(EXP): Arithmetic Functions. -* aligning sections: Section Options. -* allocating memory: MEMORY. -* architectures: Options. -* architectures available: BFD. -* archive files, from cmd line: Options. -* arithmetic: Expressions. -* arithmetic operators: Operators. -* assignment in scripts: Assignment. -* assignment, in section defn: Section Data Expressions. -* back end: BFD. -* BFD canonical format: Canonical format. -* BFD requirements: BFD. -* binary input files: Option Commands. -* binary input format: Options. -* BLOCK(ALIGN): Section Options. -* BYTE(EXPRESSION): Section Data Expressions. -* combining symbols, warnings on: Options. -* command files: Commands. -* command line: Options. -* commands, fundamental: Scripts. -* comments: Scripts. -* common allocation: Option Commands. -* common allocation: Options. -* commons in output: Section Placement. -* compatibility, MRI: Options. -* constructors: Options. -* contents of a section: Section Placement. -* CREATE_OBJECT_SYMBOLS: Section Data Expressions. -* current output location: Location Counter. -* decimal integers: Integers. -* default input format: Environment. -* DEFINED(SYMBOL): Arithmetic Functions. -* deleting local symbols: Options. -* direct output: Section Data Expressions. -* discontinuous memory: MEMORY. -* dot: Location Counter. -* emulation: Options. -* entry point, defaults: Entry Point. -* entry point, from command line: Options. -* ENTRY(SYMBOL): Entry Point. -* expression evaluation order: Evaluation. -* expression syntax: Expressions. -* expression, absolute: Arithmetic Functions. -* expressions in a section: Section Data Expressions. -* filename symbols: Section Data Expressions. -* files and sections, section defn: Section Placement. -* files, including in output sections: Section Placement. -* fill pattern, entire section: Section Options. -* FILL(EXPRESSION): Section Data Expressions. -* first input file: Option Commands. -* first instruction: Entry Point. -* FLOAT: Option Commands. -* FORCE_COMMON_ALLOCATION: Option Commands. -* format, output file: Option Commands. -* formats available: BFD. -* functions in expression language: Arithmetic Functions. -* fundamental script commands: Scripts. -* GNU linker: Overview. -* GNUTARGET: Option Commands. -* GNUTARGET: Environment. -* H8/300 support: H8/300. -* header size: Arithmetic Functions. -* help: Options. -* hexadecimal integers: Integers. -* holes: Location Counter. -* holes, filling: Section Data Expressions. -* i960 support: i960. -* incremental link: Options. -* INPUT ( FILES ): Option Commands. -* input file format: Option Commands. -* input filename symbols: Section Data Expressions. -* input files, displaying: Options. -* input files, section defn: Section Placement. -* input format: Options. -* input format: Options. -* input sections to output section: Section Placement. -* integer notation: Integers. -* integer suffixes: Integers. -* internal object-file format: Canonical format. -* K and M integer suffixes: Integers. -* l =: MEMORY. -* L, deleting symbols beginning: Options. -* layout of output file: Scripts. -* lazy evaluation: Evaluation. -* len =: MEMORY. -* LENGTH =: MEMORY. -* link map: Options. -* link map: Options. -* local symbols, deleting: Options. -* location counter: Location Counter. -* LONG(EXPRESSION): Section Data Expressions. -* M and K integer suffixes: Integers. -* machine architecture, output: Option Commands. -* machine dependencies: Machine Dependent. -* MEMORY: MEMORY. -* memory region attributes: MEMORY. -* memory regions and sections: Section Options. -* MRI compatibility: MRI. -* names: Symbols. -* naming memory regions: MEMORY. -* naming output sections: Section Definition. -* naming the output file: Options. -* naming the output file: Option Commands. -* negative integers: Integers. -* NEXT(EXP): Arithmetic Functions. -* NMAGIC: Options. -* NOFLOAT: Option Commands. -* NOLOAD: Section Options. -* Non constant expression: Assignment. -* o =: MEMORY. -* object file management: BFD. -* object files: Options. -* object size: Options. -* octal integers: Integers. -* OMAGIC: Options. -* opening object files: BFD outline. -* Operators for arithmetic: Operators. -* options: Options. -* org =: MEMORY. -* ORIGIN =: MEMORY. -* OUTPUT ( FILENAME ): Option Commands. -* output file after errors: Options. -* output file layout: Scripts. -* OUTPUT_ARCH ( BFDNAME ): Option Commands. -* OUTPUT_FORMAT ( BFDNAME ): Option Commands. -* partial link: Options. -* path for libraries: Option Commands. -* precedence in expressions: Operators. -* prevent unnecessary loading: Section Options. -* quoted symbol names: Symbols. -* read-only text: Options. -* read/write from cmd line: Options. -* regions of memory: MEMORY. -* relaxing addressing modes: Options. -* relaxing on H8/300: H8/300. -* relocatable and absolute symbols: Assignment. -* relocatable output: Options. -* requirements for BFD: BFD. -* rounding up location counter: Arithmetic Functions. -* scaled integers: Integers. -* script files: Options. -* search directory, from cmd line: Options. -* search path, libraries: Option Commands. -* SEARCH_DIR ( PATH ): Option Commands. -* section address: Arithmetic Functions. -* section address: Section Options. -* section alignment: Section Options. -* section definition: Section Definition. -* section defn, full syntax: Section Options. -* section fill pattern: Section Options. -* section size: Arithmetic Functions. -* section start: Section Options. -* section, assigning to memory region: Section Options. -* SECTIONS: SECTIONS. -* segment origins, cmd line: Options. -* semicolon: Assignment. -* SHORT(EXPRESSION): Section Data Expressions. -* SIZEOF(SECTION): Arithmetic Functions. -* SIZEOF_HEADERS: Arithmetic Functions. -* sizeof_headers: Arithmetic Functions. -* standard Unix system: Options. -* start address, section: Section Options. -* start of execution: Entry Point. -* STARTUP ( FILENAME ): Option Commands. -* strip all symbols: Options. -* strip debugger symbols: Options. -* suffixes for integers: Integers. -* symbol defaults: Arithmetic Functions. -* symbol definition, scripts: Assignment. -* symbol names: Symbols. -* symbol tracing: Options. -* symbol-only input: Options. -* symbols, from command line: Options. -* symbols, relocatable and absolute: Assignment. -* synthesizing linker: Options. -* synthesizing on H8/300: H8/300. -* TARGET ( FORMAT ): Option Commands. -* unallocated address, next: Arithmetic Functions. -* undefined symbol: Options. -* uninitialized data: Section Placement. -* unspecified memory: Section Data Expressions. -* usage: Options. -* variables, defining: Assignment. -* verbose: Options. -* version: Options. -* version: Options. -* warnings, on combining symbols: Options. -* what is this?: Overview. - - |