X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=ld%2Fld.texinfo;h=ad6cfa535ec791a6c3068526bde8ef2ea0f36398;hb=d1b6db76f052bf11333568276cf426484e812302;hp=e2a971bc71c18a9bdda6e95ec45170df5eb491cb;hpb=fc0e6df64dd2d64f16469008668ccea697291758;p=deliverable%2Fbinutils-gdb.git diff --git a/ld/ld.texinfo b/ld/ld.texinfo index e2a971bc71..ad6cfa535e 100644 --- a/ld/ld.texinfo +++ b/ld/ld.texinfo @@ -1,7 +1,7 @@ \input texinfo @setfilename ld.info @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, -@c 2001, 2002, 2003, 2004 Free Software Foundation, Inc. +@c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @syncodeindex ky cp @include configdoc.texi @c (configdoc.texi is generated by the Makefile) @@ -675,12 +675,40 @@ information about the link, including the following: @itemize @bullet @item -Where object files and symbols are mapped into memory. +Where object files are mapped into memory. @item How common symbols are allocated. @item All archive members included in the link, with a mention of the symbol which caused the archive member to be brought in. +@item +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: + +@smallexample + foo = 1 + foo = foo * 4 + foo = foo + 8 +@end smallexample + +will produce the following output in the link map if the @option{-M} +option is used: + +@smallexample + 0x00000001 foo = 0x1 + [0x0000000c] foo = (foo * 0x4) + [0x0000000c] foo = (foo + 0x8) +@end smallexample + +See @ref{Expressions} for more information about expressions in linker +scripts. @end itemize @kindex -n @@ -994,8 +1022,9 @@ This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on the command line after the @option{--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. @option{--as-needed} causes DT_NEEDED tags to only be emitted -for libraries that satisfy some reference from regular objects. +needed. @option{--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. @option{--no-as-needed} restores the default behaviour. @kindex --add-needed @@ -1504,6 +1533,12 @@ many relocations. @var{count} defaults to a value of 32768. Compute and display statistics about the operation of the linker, such as execution time and memory usage. +@kindex --sysroot +@item --sysroot=@var{directory} +Use @var{directory} as the location of the sysroot, overriding the +configure-time default. This option is only supported by linkers +that were configured using @option{--with-sysroot}. + @kindex --traditional-format @cindex traditional format @item --traditional-format @@ -1788,6 +1823,7 @@ created. By default, the new dynamic tags are not created. Note that those options are only available for ELF systems. @kindex --hash-size=@var{number} +@item --hash-size=@var{number} Set the default size of the linker's hash tables to a prime number close to @var{number}. Increasing this value can reduce the length of time it takes the linker to perform its tasks, at the expense of @@ -2197,8 +2233,9 @@ committed. @itemx --subsystem @var{which}:@var{major}.@var{minor} Specifies the subsystem under which your program will execute. The legal values for @var{which} are @code{native}, @code{windows}, -@code{console}, and @code{posix}. You may optionally set the -subsystem version also. +@code{console}, @code{posix}, and @code{xbox}. You may optionally set +the subsystem version also. Numeric values are also accepted for +@var{which}. [This option is specific to the i386 PE targeted port of the linker] @end table @@ -2569,6 +2606,18 @@ files should all be archives, and they are searched repeatedly until no new undefined references are created. See the description of @samp{-(} in @ref{Options,,Command Line Options}. +@item AS_NEEDED(@var{file}, @var{file}, @dots{}) +@itemx AS_NEEDED(@var{file} @var{file} @dots{}) +@kindex AS_NEEDED(@var{files}) +This construct can appear only inside of the @code{INPUT} or @code{GROUP} +commands, among other filenames. The files listed will be handled +as if they appear directly in the @code{INPUT} or @code{GROUP} commands, +with the exception of ELF shared libraries, that will be added only +when they are actually needed. This construct essentially enables +@option{--as-needed} option for all the files listed inside of it +and restores previous @option{--as-needed} resp. @option{--no-as-needed} +setting afterwards. + @item OUTPUT(@var{filename}) @kindex OUTPUT(@var{filename}) @cindex output file name in linker scripot @@ -2721,11 +2770,12 @@ the @samp{-f} option. @cindex symbol definition, scripts @cindex variables, defining You may assign a value to a symbol in a linker script. This will define -the symbol as a global symbol. +the symbol and place it into the symbol table with a global scope. @menu * Simple Assignments:: Simple Assignments * PROVIDE:: PROVIDE +* Source Code Reference:: How to use a linker script defined symbol in source code @end menu @node Simple Assignments @@ -2750,7 +2800,7 @@ The first case will define @var{symbol} to the value of defined, and the value will be adjusted accordingly. The special symbol name @samp{.} indicates the location counter. You -may only use this within a @code{SECTIONS} command. +may only use this within a @code{SECTIONS} command. @xref{Location Counter}. The semicolon after @var{expression} is required. @@ -2818,6 +2868,113 @@ underscore), the linker will silently use the definition in the program. If the program references @samp{etext} but does not define it, the linker will use the definition in the linker script. +@node Source Code Reference +@subsection 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 @samp{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: + +@smallexample + extern int foo; +@end smallexample + +But in the linker script it might be defined as: + +@smallexample + _foo = 1000; +@end smallexample + +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 @emph{value} of the symbol. The +second is that the compiler creates an entry in the program's symbol +table which holds the symbol's @emph{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: + +@smallexample + int foo = 1000; +@end smallexample + +creates a entry called @samp{foo} in the symbol table. This entry +holds the address of an @samp{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: + +@smallexample + foo = 1; +@end smallexample + +looks up the symbol @samp{foo} in the symbol table, gets the address +associated with this symbol and then writes the value 1 into that +address. Whereas: + +@smallexample + int * a = & foo; +@end smallexample + +looks up the symbol @samp{foo} in the symbol table, gets it address +and then copies this address into the block of memory associated with +the variable @samp{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: + +@smallexample + foo = 1000; +@end smallexample + +creates an entry in the symbol table called @samp{foo} which holds +the address of memory location 1000, but nothing special is stored at +address 1000. This means that you cannot access the @emph{value} of a +linker script defined symbol - it has no value - all you can do is +access the @emph{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: + +@smallexample +@group + start_of_ROM = .ROM; + end_of_ROM = .ROM + sizeof (.ROM) - 1; + start_of_FLASH = .FLASH; +@end group +@end smallexample + +Then the C source code to perform the copy would be: + +@smallexample +@group + extern char start_of_ROM, end_of_ROM, start_of_FLASH; + + memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); +@end group +@end smallexample + +Note the use of the @samp{&} operators. These are correct. + @node SECTIONS @section SECTIONS Command @kindex SECTIONS @@ -3377,7 +3534,9 @@ linker to place constructor information in the output section where the ignored for other object file formats. The symbol @w{@code{__CTOR_LIST__}} marks the start of the global -constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The +constructors, and the symbol @w{@code{__CTOR_END__}} marks the end. +Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__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 @@ -3843,19 +4002,19 @@ attributes. @kindex ORIGIN = @kindex o = @kindex org = -The @var{origin} is an expression for the start address of the memory -region. The expression must evaluate to a constant before memory -allocation is performed, which means that you may not use any section -relative symbols. The keyword @code{ORIGIN} may be abbreviated to -@code{org} or @code{o} (but not, for example, @code{ORG}). +The @var{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 @code{ORIGIN} may be +abbreviated to @code{org} or @code{o} (but not, for example, +@code{ORG}). @kindex LENGTH = @kindex len = @kindex l = The @var{len} is an expression for the size in bytes of the memory region. As with the @var{origin} expression, the expression must -evaluate to a constant before memory allocation is performed. The -keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}. +be numerical only and must evaluate to a constant. The keyword +@code{LENGTH} may be abbreviated to @code{len} or @code{l}. In the following example, we specify that there are two memory regions available for allocation: one starting at @samp{0} for 256 kilobytes, @@ -3886,6 +4045,16 @@ 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 @code{ORIGIN(@var{memory})} and +@code{LENGTH(@var{memory})} functions: + +@smallexample +@group + _fstack = ORIGIN(ram) + LENGTH(ram) - 4; +@end group +@end smallexample + @node PHDRS @section PHDRS Command @kindex PHDRS @@ -4352,6 +4521,74 @@ and it will have an extra 0x600 bytes worth of space after the end of the values from the @samp{.data} input sections and before the end of the @samp{.data} output section itself. +@cindex dot outside sections +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: + +@smallexample +SECTIONS +@{ + start_of_text = . ; + .text: @{ *(.text) @} + end_of_text = . ; + + start_of_data = . ; + .data: @{ *(.data) @} + end_of_data = . ; +@} +@end smallexample + +If the linker needs to place some input section, e.g. @code{.rodata}, +not mentioned in the script, it might choose to place that section +between @code{.text} and @code{.data}. You might think the linker +should place @code{.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 @code{.}. I.e., the linker will +place the orphan @code{.rodata} section as if the script was written +as follows: + +@smallexample +SECTIONS +@{ + start_of_text = . ; + .text: @{ *(.text) @} + end_of_text = . ; + + start_of_data = . ; + .rodata: @{ *(.rodata) @} + .data: @{ *(.data) @} + end_of_data = . ; +@} +@end smallexample + +This may or may not be the script author's intention for the value of +@code{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 @code{.} is setting the start address of +a following output section and thus should be grouped with that +section. So you could write: + +@smallexample +SECTIONS +@{ + start_of_text = . ; + .text: @{ *(.text) @} + end_of_text = . ; + + . = . ; + start_of_data = . ; + .data: @{ *(.data) @} + end_of_data = . ; +@} +@end smallexample + +Now, the orphan @code{.rodata} section will be placed between +@code{end_of_text} and @code{start_of_data}. + @need 2000 @node Operators @subsection Operators @@ -4661,6 +4898,10 @@ SECTIONS @{ @dots{} @end group @end smallexample +@item LENGTH(@var{memory}) +@kindex LENGTH(@var{memory}) +Return the length of the memory region named @var{memory}. + @item LOADADDR(@var{section}) @kindex LOADADDR(@var{section}) @cindex section load address in expression @@ -4685,6 +4926,10 @@ This function is closely related to @code{ALIGN(@var{exp})}; unless you use the @code{MEMORY} command to define discontinuous memory for the output file, the two functions are equivalent. +@item ORIGIN(@var{memory}) +@kindex ORIGIN(@var{memory}) +Return the origin of the memory region named @var{memory}. + @item SEGMENT_START(@var{segment}, @var{default}) @kindex SEGMENT_START(@var{segment}, @var{default}) Return the base address of the named @var{segment}. If an explicit @@ -5032,6 +5277,31 @@ meanings, and target defaults are as follows: @samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd) @end table +@cindex FIX_V4BX +@kindex --fix-v4bx +The @samp{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 @option{--fix-v4bx} must be passed to the +linker, which causes v4t @code{BX rM} instructions to be rewritten as +@code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction. + +In the former case, the switch should not be used, and @samp{R_ARM_V4BX} +relocations are ignored. + +@cindex USE_BLX +@kindex --use-blx +The @samp{--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. + @ifclear GENERIC @lowersections @end ifclear