2129 lines
68 KiB
HTML
2129 lines
68 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<!-- This HTML file has been created by texi2html 1.52
|
|
from ../texi/ld.texinfo on 7 November 1998 -->
|
|
|
|
<TITLE>Using LD, the GNU linker - Command Language</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
Go to the <A HREF="ld_1.html">first</A>, <A HREF="ld_2.html">previous</A>, <A HREF="ld_4.html">next</A>, <A HREF="ld_8.html">last</A> section, <A HREF="ld_toc.html">table of contents</A>.
|
|
<P><HR><P>
|
|
|
|
|
|
<H1><A NAME="SEC5" HREF="ld_toc.html#TOC5">Command Language</A></H1>
|
|
|
|
<P>
|
|
<A NAME="IDX189"></A>
|
|
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:
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
input files
|
|
<LI>
|
|
|
|
file formats
|
|
<LI>
|
|
|
|
output file layout
|
|
<LI>
|
|
|
|
addresses of sections
|
|
<LI>
|
|
|
|
placement of common blocks
|
|
</UL>
|
|
|
|
<P>
|
|
You may supply a command file (also known as a linker script) to the
|
|
linker either explicitly through the <SAMP>`-T'</SAMP> option, or implicitly as
|
|
an ordinary file. Normally you should use the <SAMP>`-T'</SAMP> option. An
|
|
implicit linker script should only be used when you want to augment,
|
|
rather than replace, the default linker script; typically an implicit
|
|
linker script would consist only of <CODE>INPUT</CODE> or <CODE>GROUP</CODE>
|
|
commands.
|
|
|
|
</P>
|
|
<P>
|
|
If the linker opens a file which it cannot recognize as a supported
|
|
object or archive format, nor as a linker script, it reports an error.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC6" HREF="ld_toc.html#TOC6">Linker Scripts</A></H2>
|
|
<P>
|
|
The <CODE>ld</CODE> 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.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX190"></A>
|
|
<A NAME="IDX191"></A>
|
|
<A NAME="IDX192"></A>
|
|
<A NAME="IDX193"></A>
|
|
The most fundamental command of the <CODE>ld</CODE> command language is the
|
|
<CODE>SECTIONS</CODE> command (see section <A HREF="ld_3.html#SEC17">Specifying Output Sections</A>). Every meaningful command
|
|
script must have a <CODE>SECTIONS</CODE> command: it specifies a
|
|
"picture" of the output file's layout, in varying degrees of detail.
|
|
No other command is required in all cases.
|
|
|
|
</P>
|
|
<P>
|
|
The <CODE>MEMORY</CODE> command complements <CODE>SECTIONS</CODE> by describing the
|
|
available memory in the target architecture. This command is optional;
|
|
if you don't use a <CODE>MEMORY</CODE> command, <CODE>ld</CODE> assumes sufficient
|
|
memory is available in a contiguous block for all output.
|
|
See section <A HREF="ld_3.html#SEC16">Memory Layout</A>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX194"></A>
|
|
You may include comments in linker scripts just as in C: delimited
|
|
by <SAMP>`/*'</SAMP> and <SAMP>`*/'</SAMP>. As in C, comments are syntactically
|
|
equivalent to whitespace.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC7" HREF="ld_toc.html#TOC7">Expressions</A></H2>
|
|
<P>
|
|
<A NAME="IDX195"></A>
|
|
<A NAME="IDX196"></A>
|
|
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:
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
All expressions evaluated as integers and
|
|
are of "long" or "unsigned long" type.
|
|
<LI>
|
|
|
|
All constants are integers.
|
|
<LI>
|
|
|
|
All of the C arithmetic operators are provided.
|
|
<LI>
|
|
|
|
You may reference, define, and create global variables.
|
|
<LI>
|
|
|
|
You may call special purpose built-in functions.
|
|
</UL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC8" HREF="ld_toc.html#TOC8">Integers</A></H3>
|
|
<P>
|
|
<A NAME="IDX197"></A>
|
|
<A NAME="IDX198"></A>
|
|
An octal integer is <SAMP>`0'</SAMP> followed by zero or more of the octal
|
|
digits (<SAMP>`01234567'</SAMP>).
|
|
|
|
<PRE>
|
|
_as_octal = 0157255;
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX199"></A>
|
|
A decimal integer starts with a non-zero digit followed by zero or
|
|
more digits (<SAMP>`0123456789'</SAMP>).
|
|
|
|
<PRE>
|
|
_as_decimal = 57005;
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX200"></A>
|
|
<A NAME="IDX201"></A>
|
|
A hexadecimal integer is <SAMP>`0x'</SAMP> or <SAMP>`0X'</SAMP> followed by one or
|
|
more hexadecimal digits chosen from <SAMP>`0123456789abcdefABCDEF'</SAMP>.
|
|
|
|
<PRE>
|
|
_as_hex = 0xdead;
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX202"></A>
|
|
To write a negative integer, use
|
|
the prefix operator <SAMP>`-'</SAMP> (see section <A HREF="ld_3.html#SEC11">Operators</A>).
|
|
|
|
<PRE>
|
|
_as_neg = -57005;
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX203"></A>
|
|
<A NAME="IDX204"></A>
|
|
<A NAME="IDX205"></A>
|
|
<A NAME="IDX206"></A>
|
|
<A NAME="IDX207"></A>
|
|
Additionally the suffixes <CODE>K</CODE> and <CODE>M</CODE> may be used to scale a
|
|
constant by
|
|
respectively. For example, the following all refer to the same quantity:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
_fourk_1 = 4K;
|
|
_fourk_2 = 4096;
|
|
_fourk_3 = 0x1000;
|
|
</PRE>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC9" HREF="ld_toc.html#TOC9">Symbol Names</A></H3>
|
|
<P>
|
|
<A NAME="IDX208"></A>
|
|
<A NAME="IDX209"></A>
|
|
<A NAME="IDX210"></A>
|
|
<A NAME="IDX211"></A>
|
|
Unless quoted, symbol names start with a letter, underscore, or point
|
|
and may include any letters, underscores, digits, points,
|
|
and hyphens. Unquoted symbol names must not conflict with any
|
|
keywords. You can specify a symbol which contains odd characters or has
|
|
the same name as a keyword, by surrounding the symbol name in double quotes:
|
|
|
|
<PRE>
|
|
"SECTION" = 9;
|
|
"with a space" = "also with a space" + 10;
|
|
</PRE>
|
|
|
|
<P>
|
|
Since symbols can contain many non-alphabetic characters, it is safest
|
|
to delimit symbols with spaces. For example, <SAMP>`A-B'</SAMP> is one symbol,
|
|
whereas <SAMP>`A - B'</SAMP> is an expression involving subtraction.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC10" HREF="ld_toc.html#TOC10">The Location Counter</A></H3>
|
|
<P>
|
|
<A NAME="IDX212"></A>
|
|
<A NAME="IDX213"></A>
|
|
<A NAME="IDX214"></A>
|
|
<A NAME="IDX215"></A>
|
|
The special linker variable <EM>dot</EM> <SAMP>`.'</SAMP> always contains the
|
|
current output location counter. Since the <CODE>.</CODE> always refers to
|
|
a location in an output section, it must always appear in an
|
|
expression within a <CODE>SECTIONS</CODE> command. The <CODE>.</CODE> 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 <CODE>.</CODE> symbol will cause the location counter to be moved.
|
|
<A NAME="IDX216"></A>
|
|
This may be used to create holes in the output section. The location
|
|
counter may never be moved backwards.
|
|
|
|
<PRE>
|
|
SECTIONS
|
|
{
|
|
output :
|
|
{
|
|
file1(.text)
|
|
. = . + 1000;
|
|
file2(.text)
|
|
. += 1000;
|
|
file3(.text)
|
|
} = 0x1234;
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
In the previous example, <CODE>file1</CODE> is located at the beginning of the
|
|
output section, then there is a 1000 byte gap. Then <CODE>file2</CODE>
|
|
appears, also with a 1000 byte gap following before <CODE>file3</CODE> is
|
|
loaded. The notation <SAMP>`= 0x1234'</SAMP> specifies what data to write in
|
|
the gaps (see section <A HREF="ld_3.html#SEC21">Optional Section Attributes</A>).
|
|
|
|
</P>
|
|
<P>
|
|
@vfill
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC11" HREF="ld_toc.html#TOC11">Operators</A></H3>
|
|
<P>
|
|
<A NAME="IDX217"></A>
|
|
<A NAME="IDX218"></A>
|
|
<A NAME="IDX219"></A>
|
|
The linker recognizes the standard C set of arithmetic operators, with
|
|
the standard bindings and precedence levels:
|
|
{
|
|
@obeylines@parskip=0pt@parindent=0pt
|
|
@dag@quad Prefix operators.
|
|
@ddag@quad See section <A HREF="ld_3.html#SEC13">Assignment: Defining Symbols</A>.
|
|
}
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC12" HREF="ld_toc.html#TOC12">Evaluation</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX220"></A>
|
|
<A NAME="IDX221"></A>
|
|
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.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC13" HREF="ld_toc.html#TOC13">Assignment: Defining Symbols</A></H3>
|
|
<P>
|
|
<A NAME="IDX222"></A>
|
|
<A NAME="IDX223"></A>
|
|
<A NAME="IDX224"></A>
|
|
You may create global symbols, and assign values (addresses) to global
|
|
symbols, using any of the C assignment operators:
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>symbol</VAR> = <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>symbol</VAR> &= <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>symbol</VAR> += <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>symbol</VAR> -= <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>symbol</VAR> *= <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>symbol</VAR> /= <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
Two things distinguish assignment from other operators in <CODE>ld</CODE>
|
|
expressions.
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
Assignment may only be used at the root of an expression;
|
|
<SAMP>`a=b+3;'</SAMP> is allowed, but <SAMP>`a+b=3;'</SAMP> is an error.
|
|
|
|
<A NAME="IDX225"></A>
|
|
<A NAME="IDX226"></A>
|
|
<LI>
|
|
|
|
You must place a trailing semicolon ("<KBD>;</KBD>") at the end of an
|
|
assignment statement.
|
|
</UL>
|
|
|
|
<P>
|
|
Assignment statements may appear:
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
as commands in their own right in an <CODE>ld</CODE> script; or
|
|
<LI>
|
|
|
|
as independent statements within a <CODE>SECTIONS</CODE> command; or
|
|
<LI>
|
|
|
|
as part of the contents of a section definition in a
|
|
<CODE>SECTIONS</CODE> command.
|
|
</UL>
|
|
|
|
<P>
|
|
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 (see section <A HREF="ld_3.html#SEC17">Specifying Output Sections</A>).
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX227"></A>
|
|
<A NAME="IDX228"></A>
|
|
<A NAME="IDX229"></A>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
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
|
|
<CODE>ABSOLUTE</CODE>. For example, to create an absolute symbol whose address
|
|
is the last byte of an output section named <CODE>.data</CODE>:
|
|
|
|
<PRE>
|
|
SECTIONS{ ...
|
|
.data :
|
|
{
|
|
*(.data)
|
|
_edata = ABSOLUTE(.) ;
|
|
}
|
|
... }
|
|
</PRE>
|
|
|
|
<P>
|
|
The linker tries to put off the evaluation of an assignment until all
|
|
the terms in the source expression are known (see section <A HREF="ld_3.html#SEC12">Evaluation</A>). 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 <EM>dot</EM>, <SAMP>`.'</SAMP> 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
|
|
|
|
<PRE>
|
|
SECTIONS { ...
|
|
text 9+this_isnt_constant :
|
|
{ ...
|
|
}
|
|
... }
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX230"></A>
|
|
will cause the error message "<CODE>Non constant expression for initial
|
|
address</CODE>".
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX231"></A>
|
|
In some cases, it is desirable for a linker script to define a symbol
|
|
only if it is referenced, and only if it is not defined by any object
|
|
included in the link. For example, traditional linkers defined the
|
|
symbol <SAMP>`etext'</SAMP>. However, ANSI C requires that the user be able to
|
|
use <SAMP>`etext'</SAMP> as a function name without encountering an error.
|
|
The <CODE>PROVIDE</CODE> keyword may be used to define a symbol, such as
|
|
<SAMP>`etext'</SAMP>, only if it is referenced but not defined. The syntax is
|
|
<CODE>PROVIDE(<VAR>symbol</VAR> = <VAR>expression</VAR>)</CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC14" HREF="ld_toc.html#TOC14">Arithmetic Functions</A></H3>
|
|
<P>
|
|
<A NAME="IDX232"></A>
|
|
The command language includes a number of built-in
|
|
functions for use in link script expressions.
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>ABSOLUTE(<VAR>exp</VAR>)</CODE>
|
|
<DD>
|
|
<A NAME="IDX233"></A>
|
|
<A NAME="IDX234"></A>
|
|
|
|
Return the absolute (non-relocatable, as opposed to non-negative) value
|
|
of the expression <VAR>exp</VAR>. Primarily useful to assign an absolute
|
|
value to a symbol within a section definition, where symbol values are
|
|
normally section-relative.
|
|
|
|
<A NAME="IDX235"></A>
|
|
<A NAME="IDX236"></A>
|
|
<DT><CODE>ADDR(<VAR>section</VAR>)</CODE>
|
|
<DD>
|
|
Return the absolute address of the named <VAR>section</VAR>. Your script must
|
|
previously have defined the location of that section. In the following
|
|
example, <CODE>symbol_1</CODE> and <CODE>symbol_2</CODE> are assigned identical
|
|
values:
|
|
|
|
<PRE>
|
|
SECTIONS{ ...
|
|
.output1 :
|
|
{
|
|
start_of_output_1 = ABSOLUTE(.);
|
|
...
|
|
}
|
|
.output :
|
|
{
|
|
symbol_1 = ADDR(.output1);
|
|
symbol_2 = start_of_output_1;
|
|
}
|
|
... }
|
|
</PRE>
|
|
|
|
<A NAME="IDX237"></A>
|
|
<A NAME="IDX238"></A>
|
|
<DT><CODE>LOADADDR(<VAR>section</VAR>)</CODE>
|
|
<DD>
|
|
Return the absolute load address of the named <VAR>section</VAR>. This is
|
|
normally the same as <CODE>ADDR</CODE>, but it may be different if the
|
|
<CODE>AT</CODE> keyword is used in the section definition (see section <A HREF="ld_3.html#SEC21">Optional Section Attributes</A>).
|
|
|
|
<A NAME="IDX239"></A>
|
|
<A NAME="IDX240"></A>
|
|
<DT><CODE>ALIGN(<VAR>exp</VAR>)</CODE>
|
|
<DD>
|
|
Return the result of the current location counter (<CODE>.</CODE>) aligned to
|
|
the next <VAR>exp</VAR> boundary. <VAR>exp</VAR> must be an expression whose
|
|
value is a power of two. This is equivalent to
|
|
|
|
<PRE>
|
|
(. + <VAR>exp</VAR> - 1) & ~(<VAR>exp</VAR> - 1)
|
|
</PRE>
|
|
|
|
<CODE>ALIGN</CODE> doesn't change the value of the location counter--it just
|
|
does arithmetic on it. As an example, to align the output <CODE>.data</CODE>
|
|
section to the next <CODE>0x2000</CODE> byte boundary after the preceding
|
|
section and to set a variable within the section to the next
|
|
<CODE>0x8000</CODE> boundary after the input sections:
|
|
|
|
<PRE>
|
|
SECTIONS{ ...
|
|
.data ALIGN(0x2000): {
|
|
*(.data)
|
|
variable = ALIGN(0x8000);
|
|
}
|
|
... }
|
|
</PRE>
|
|
|
|
The first use of <CODE>ALIGN</CODE> in this example specifies the location of
|
|
a section because it is used as the optional <VAR>start</VAR> attribute of a
|
|
section definition (see section <A HREF="ld_3.html#SEC21">Optional Section Attributes</A>). The second use simply
|
|
defines the value of a variable.
|
|
|
|
The built-in <CODE>NEXT</CODE> is closely related to <CODE>ALIGN</CODE>.
|
|
|
|
<A NAME="IDX241"></A>
|
|
<A NAME="IDX242"></A>
|
|
<DT><CODE>DEFINED(<VAR>symbol</VAR>)</CODE>
|
|
<DD>
|
|
Return 1 if <VAR>symbol</VAR> 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 <CODE>begin</CODE> to the first location in the
|
|
<CODE>.text</CODE> section--but if a symbol called <CODE>begin</CODE> already
|
|
existed, its value is preserved:
|
|
|
|
|
|
<PRE>
|
|
SECTIONS{ ...
|
|
.text : {
|
|
begin = DEFINED(begin) ? begin : . ;
|
|
...
|
|
}
|
|
... }
|
|
</PRE>
|
|
|
|
<A NAME="IDX243"></A>
|
|
<A NAME="IDX244"></A>
|
|
<DT><CODE>NEXT(<VAR>exp</VAR>)</CODE>
|
|
<DD>
|
|
Return the next unallocated address that is a multiple of <VAR>exp</VAR>.
|
|
This function is closely related to <CODE>ALIGN(<VAR>exp</VAR>)</CODE>; unless you
|
|
use the <CODE>MEMORY</CODE> command to define discontinuous memory for the
|
|
output file, the two functions are equivalent.
|
|
|
|
<A NAME="IDX245"></A>
|
|
<A NAME="IDX246"></A>
|
|
<DT><CODE>SIZEOF(<VAR>section</VAR>)</CODE>
|
|
<DD>
|
|
Return the size in bytes of the named <VAR>section</VAR>, if that section has
|
|
been allocated. In the following example, <CODE>symbol_1</CODE> and
|
|
<CODE>symbol_2</CODE> are assigned identical values:
|
|
|
|
<PRE>
|
|
SECTIONS{ ...
|
|
.output {
|
|
.start = . ;
|
|
...
|
|
.end = . ;
|
|
}
|
|
symbol_1 = .end - .start ;
|
|
symbol_2 = SIZEOF(.output);
|
|
... }
|
|
</PRE>
|
|
|
|
<A NAME="IDX247"></A>
|
|
<A NAME="IDX248"></A>
|
|
<A NAME="IDX249"></A>
|
|
<DT><CODE>SIZEOF_HEADERS</CODE>
|
|
<DD>
|
|
<DT><CODE>sizeof_headers</CODE>
|
|
<DD>
|
|
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.
|
|
|
|
<A NAME="IDX250"></A>
|
|
<DT><CODE>MAX(<VAR>exp1</VAR>, <VAR>exp2</VAR>)</CODE>
|
|
<DD>
|
|
Returns the maximum of <VAR>exp1</VAR> and <VAR>exp2</VAR>.
|
|
|
|
<A NAME="IDX251"></A>
|
|
<DT><CODE>MIN(<VAR>exp1</VAR>, <VAR>exp2</VAR>)</CODE>
|
|
<DD>
|
|
Returns the minimum of <VAR>exp1</VAR> and <VAR>exp2</VAR>.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC15" HREF="ld_toc.html#TOC15">Semicolons</A></H3>
|
|
|
|
<P>
|
|
Semicolons ("<KBD>;</KBD>") are required in the following places. In all
|
|
other places they can appear for aesthetic reasons but are otherwise ignored.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>Assignment</CODE>
|
|
<DD>
|
|
Semicolons must appear at the end of assignment expressions.
|
|
See section <A HREF="ld_3.html#SEC13">Assignment: Defining Symbols</A>
|
|
|
|
<DT><CODE>PHDRS</CODE>
|
|
<DD>
|
|
Semicolons must appear at the end of a <CODE>PHDRS</CODE> statement.
|
|
See section <A HREF="ld_3.html#SEC23">ELF Program Headers</A>
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC16" HREF="ld_toc.html#TOC16">Memory Layout</A></H2>
|
|
<P>
|
|
<A NAME="IDX252"></A>
|
|
<A NAME="IDX253"></A>
|
|
<A NAME="IDX254"></A>
|
|
<A NAME="IDX255"></A>
|
|
The linker's default configuration permits allocation of all available memory.
|
|
You can override this configuration by using the <CODE>MEMORY</CODE> command. The
|
|
<CODE>MEMORY</CODE> 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.
|
|
|
|
</P>
|
|
<P>
|
|
A command file may contain at most one use of the <CODE>MEMORY</CODE>
|
|
command; however, you can define as many blocks of memory within it as
|
|
you wish. The syntax is:
|
|
|
|
|
|
<PRE>
|
|
MEMORY
|
|
{
|
|
<VAR>name</VAR> (<VAR>attr</VAR>) : ORIGIN = <VAR>origin</VAR>, LENGTH = <VAR>len</VAR>
|
|
...
|
|
}
|
|
</PRE>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>name</VAR></CODE>
|
|
<DD>
|
|
<A NAME="IDX256"></A>
|
|
|
|
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.
|
|
|
|
<A NAME="IDX257"></A>
|
|
<DT><CODE>(<VAR>attr</VAR>)</CODE>
|
|
<DD>
|
|
is an optional list of attributes that specify whether to use a
|
|
particular memory to place sections that are not listed in the linker
|
|
script. Valid attribute lists must be made up of the characters
|
|
"<CODE>ALIRWX</CODE>" that match section attributes. If you omit the
|
|
attribute list, you may omit the parentheses around it as well. The
|
|
attributes currently supported are:
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`<CODE>Letter</CODE>'</SAMP>
|
|
<DD>
|
|
<CODE>Section Attribute</CODE>
|
|
|
|
<DT><SAMP>`<CODE>R</CODE>'</SAMP>
|
|
<DD>
|
|
Read-only sections.
|
|
|
|
<DT><SAMP>`<CODE>W</CODE>'</SAMP>
|
|
<DD>
|
|
Read/write sections.
|
|
|
|
<DT><SAMP>`<CODE>X</CODE>'</SAMP>
|
|
<DD>
|
|
Sections containing executable code.
|
|
|
|
<DT><SAMP>`<CODE>A</CODE>'</SAMP>
|
|
<DD>
|
|
Allocated sections.
|
|
|
|
<DT><SAMP>`<CODE>I</CODE>'</SAMP>
|
|
<DD>
|
|
Initialized sections.
|
|
|
|
<DT><SAMP>`<CODE>L</CODE>'</SAMP>
|
|
<DD>
|
|
Same as <CODE>I</CODE>.
|
|
|
|
<DT><SAMP>`<CODE>!</CODE>'</SAMP>
|
|
<DD>
|
|
Invert the sense of any of the following attributes.
|
|
</DL>
|
|
|
|
<A NAME="IDX258"></A>
|
|
<A NAME="IDX259"></A>
|
|
<A NAME="IDX260"></A>
|
|
<DT><CODE><VAR>origin</VAR></CODE>
|
|
<DD>
|
|
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 <CODE>ORIGIN</CODE> may be
|
|
abbreviated to <CODE>org</CODE> or <CODE>o</CODE> (but not, for example, <SAMP>`ORG'</SAMP>).
|
|
|
|
<A NAME="IDX261"></A>
|
|
<A NAME="IDX262"></A>
|
|
<A NAME="IDX263"></A>
|
|
<DT><CODE><VAR>len</VAR></CODE>
|
|
<DD>
|
|
is the size in bytes of the region (an expression).
|
|
The keyword <CODE>LENGTH</CODE> may be abbreviated to <CODE>len</CODE> or <CODE>l</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
For example, to specify that memory has two regions available for
|
|
allocation--one starting at 0 for 256 kilobytes, and the other starting
|
|
at <CODE>0x40000000</CODE> for four megabytes. The <CODE>rom</CODE> memory region
|
|
will get all sections without an explicit memory register that are
|
|
either read-only or contain code, while the <CODE>ram</CODE> memory region
|
|
will get the sections.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
MEMORY
|
|
{
|
|
rom (rx) : ORIGIN = 0, LENGTH = 256K
|
|
ram (!rx) : org = 0x40000000, l = 4M
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
Once you have defined a region of memory named <VAR>mem</VAR>, you can direct
|
|
specific output sections there by using a command ending in
|
|
<SAMP>`><VAR>mem</VAR>'</SAMP> within the <CODE>SECTIONS</CODE> command (see section <A HREF="ld_3.html#SEC21">Optional Section Attributes</A>). If the combined output sections directed to a region are too
|
|
big for the region, the linker will issue an error message.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC17" HREF="ld_toc.html#TOC17">Specifying Output Sections</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX264"></A>
|
|
The <CODE>SECTIONS</CODE> 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.
|
|
|
|
</P>
|
|
<P>
|
|
You may use at most one <CODE>SECTIONS</CODE> command in a script file,
|
|
but you can have as many statements within it as you wish. Statements
|
|
within the <CODE>SECTIONS</CODE> command can do one of three things:
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
define the entry point;
|
|
|
|
<LI>
|
|
|
|
assign a value to a symbol;
|
|
|
|
<LI>
|
|
|
|
describe the placement of a named output section, and which input
|
|
sections go into it.
|
|
</UL>
|
|
|
|
<P>
|
|
You can also use the first two operations--defining the entry point and
|
|
defining symbols--outside the <CODE>SECTIONS</CODE> command: see section <A HREF="ld_3.html#SEC24">The Entry Point</A>, and section <A HREF="ld_3.html#SEC13">Assignment: Defining Symbols</A>. 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.
|
|
|
|
</P>
|
|
<P>
|
|
If you do not use a <CODE>SECTIONS</CODE> command, 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.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC18" HREF="ld_toc.html#TOC18">Section Definitions</A></H3>
|
|
<P>
|
|
<A NAME="IDX265"></A>
|
|
The most frequently used statement in the <CODE>SECTIONS</CODE> command is
|
|
the <EM>section definition</EM>, 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
|
|
|
|
<PRE>
|
|
SECTIONS { ...
|
|
<VAR>secname</VAR> : {
|
|
<VAR>contents</VAR>
|
|
}
|
|
... }
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX266"></A>
|
|
<VAR>secname</VAR> is the name of the output section, and <VAR>contents</VAR> a
|
|
specification of what goes there--for example, a list of input files or
|
|
sections of input files (see section <A HREF="ld_3.html#SEC19">Section Placement</A>). The whitespace
|
|
around <VAR>secname</VAR> is required, so that the section name is
|
|
unambiguous. The other whitespace shown is optional. You do need the
|
|
colon <SAMP>`:'</SAMP> and the braces <SAMP>`{}'</SAMP>, however.
|
|
|
|
</P>
|
|
<P>
|
|
<VAR>secname</VAR> must meet the constraints of your output format. In
|
|
formats which only support a limited number of sections, such as
|
|
<CODE>a.out</CODE>, the name must be one of the names supported by the format
|
|
(<CODE>a.out</CODE>, for example, allows only <CODE>.text</CODE>, <CODE>.data</CODE> or
|
|
<CODE>.bss</CODE>). 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
|
|
<CODE>ld</CODE> symbol name syntax must be quoted.
|
|
See section <A HREF="ld_3.html#SEC9">Symbol Names</A>.
|
|
|
|
</P>
|
|
<P>
|
|
The special <VAR>secname</VAR> <SAMP>`/DISCARD/'</SAMP> may be used to discard input
|
|
sections. Any sections which are assigned to an output section named
|
|
<SAMP>`/DISCARD/'</SAMP> are not included in the final link output.
|
|
|
|
</P>
|
|
<P>
|
|
The linker will not create output sections which do not have any
|
|
contents. This is for convenience when referring to input sections that
|
|
may or may not exist. For example,
|
|
|
|
<PRE>
|
|
.foo { *(.foo) }
|
|
</PRE>
|
|
|
|
<P>
|
|
will only create a <SAMP>`.foo'</SAMP> section in the output file if there is a
|
|
<SAMP>`.foo'</SAMP> section in at least one input file.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC19" HREF="ld_toc.html#TOC19">Section Placement</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX267"></A>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
The <VAR>contents</VAR> 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.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>filename</VAR></CODE>
|
|
<DD>
|
|
<A NAME="IDX268"></A>
|
|
<A NAME="IDX269"></A>
|
|
<A NAME="IDX270"></A>
|
|
|
|
You may simply name a particular input file to be placed in the current
|
|
output section; <EM>all</EM> 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:
|
|
|
|
<PRE>
|
|
.data : { afile.o bfile.o cfile.o }
|
|
</PRE>
|
|
|
|
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.
|
|
|
|
<A NAME="IDX271"></A>
|
|
<A NAME="IDX272"></A>
|
|
<DT><CODE><VAR>filename</VAR>( <VAR>section</VAR> )</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>filename</VAR>( <VAR>section</VAR> , <VAR>section</VAR>, ... )</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>filename</VAR>( <VAR>section</VAR> <VAR>section</VAR> ... )</CODE>
|
|
<DD>
|
|
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, separate the section names
|
|
with whitespace.
|
|
|
|
<A NAME="IDX273"></A>
|
|
<A NAME="IDX274"></A>
|
|
<DT><CODE>* (<VAR>section</VAR>)</CODE>
|
|
<DD>
|
|
<DT><CODE>* (<VAR>section</VAR>, <VAR>section</VAR>, ...)</CODE>
|
|
<DD>
|
|
<DT><CODE>* (<VAR>section</VAR> <VAR>section</VAR> ...)</CODE>
|
|
<DD>
|
|
Instead of explicitly naming particular input files in a link control
|
|
script, you can refer to <EM>all</EM> files from the <CODE>ld</CODE> command
|
|
line: use <SAMP>`*'</SAMP> instead of a particular file name before the
|
|
parenthesized input-file section list.
|
|
|
|
If you have already explicitly included some files by name, <SAMP>`*'</SAMP>
|
|
refers to all <EM>remaining</EM> files--those whose places in the output
|
|
file have not yet been defined.
|
|
|
|
For example, to copy sections <CODE>1</CODE> through <CODE>4</CODE> from an Oasys file
|
|
into the <CODE>.text</CODE> section of an <CODE>a.out</CODE> file, and sections <CODE>13</CODE>
|
|
and <CODE>14</CODE> into the <CODE>.data</CODE> section:
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
.text :{
|
|
*("1" "2" "3" "4")
|
|
}
|
|
|
|
.data :{
|
|
*("13" "14")
|
|
}
|
|
}
|
|
</PRE>
|
|
|
|
<A NAME="IDX275"></A>
|
|
<SAMP>`[ <VAR>section</VAR> ... ]'</SAMP> 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.
|
|
|
|
<A NAME="IDX276"></A>
|
|
<A NAME="IDX277"></A>
|
|
<A NAME="IDX278"></A>
|
|
<DT><CODE><VAR>filename</VAR><CODE>( COMMON )</CODE></CODE>
|
|
<DD>
|
|
<DT><CODE>*( COMMON )</CODE>
|
|
<DD>
|
|
Specify where in your output file to place uninitialized data
|
|
with this notation. <CODE>*(COMMON)</CODE> by itself refers to all
|
|
uninitialized data from all input files (so far as it is not yet
|
|
allocated); <VAR>filename</VAR><CODE>(COMMON)</CODE> refers to uninitialized data
|
|
from a particular file. Both are special cases of the general
|
|
mechanisms for specifying where to place input-file sections:
|
|
<CODE>ld</CODE> permits you to refer to uninitialized data as if it
|
|
were in an input-file section named <CODE>COMMON</CODE>, regardless of the
|
|
input file's format.
|
|
</DL>
|
|
|
|
<P>
|
|
In any place where you may use a specific file or section name, you may
|
|
also use a wildcard pattern. The linker handles wildcards much as the
|
|
Unix shell does. A <SAMP>`*'</SAMP> character matches any number of characters.
|
|
A <SAMP>`?'</SAMP> character matches any single character. The sequence
|
|
<SAMP>`[<VAR>chars</VAR>]'</SAMP> will match a single instance of any of the
|
|
<VAR>chars</VAR>; the <SAMP>`-'</SAMP> character may be used to specify a range of
|
|
characters, as in <SAMP>`[a-z]'</SAMP> to match any lower case letter. A
|
|
<SAMP>`\'</SAMP> character may be used to quote the following character.
|
|
|
|
</P>
|
|
<P>
|
|
When a file name is matched with a wildcard, the wildcard characters
|
|
will not match a <SAMP>`/'</SAMP> character (used to separate directory names on
|
|
Unix). A pattern consisting of a single <SAMP>`*'</SAMP> character is an
|
|
exception; it will always match any file name. In a section name, the
|
|
wildcard characters will match a <SAMP>`/'</SAMP> character.
|
|
|
|
</P>
|
|
<P>
|
|
Wildcards only match files which are explicitly specified on the command
|
|
line. The linker does not search directories to expand wildcards.
|
|
However, if you specify a simple file name--a name with no wildcard
|
|
characters--in a linker script, and the file name is not also specified
|
|
on the command line, the linker will attempt to open the file as though
|
|
it appeared on the command line.
|
|
|
|
</P>
|
|
<P>
|
|
In the following example, the command script arranges the output file
|
|
into three consecutive sections, named <CODE>.text</CODE>, <CODE>.data</CODE>, and
|
|
<CODE>.bss</CODE>, taking the input for each from the correspondingly named
|
|
sections of all the input files:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
.text : { *(.text) }
|
|
.data : { *(.data) }
|
|
.bss : { *(.bss) *(COMMON) }
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
The following example reads all of the sections from file <CODE>all.o</CODE>
|
|
and places them at the start of output section <CODE>outputa</CODE> which
|
|
starts at location <CODE>0x10000</CODE>. All of section <CODE>.input1</CODE> from
|
|
file <CODE>foo.o</CODE> follows immediately, in the same output section. All
|
|
of section <CODE>.input2</CODE> from <CODE>foo.o</CODE> goes into output section
|
|
<CODE>outputb</CODE>, followed by section <CODE>.input1</CODE> from <CODE>foo1.o</CODE>.
|
|
All of the remaining <CODE>.input1</CODE> and <CODE>.input2</CODE> sections from any
|
|
files are written to output section <CODE>outputc</CODE>.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
outputa 0x10000 :
|
|
{
|
|
all.o
|
|
foo.o (.input1)
|
|
}
|
|
outputb :
|
|
{
|
|
foo.o (.input2)
|
|
foo1.o (.input1)
|
|
}
|
|
outputc :
|
|
{
|
|
*(.input1)
|
|
*(.input2)
|
|
}
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
This example shows how wildcard patterns might be used to partition
|
|
files. All <CODE>.text</CODE> sections are placed in <CODE>.text</CODE>, and all
|
|
<CODE>.bss</CODE> sections are placed in <CODE>.bss</CODE>. For all files beginning
|
|
with an upper case character, the <CODE>.data</CODE> section is placed into
|
|
<CODE>.DATA</CODE>; for all other files, the <CODE>.data</CODE> section is placed
|
|
into <CODE>.data</CODE>.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
.text : { *(.text) }
|
|
.DATA : { [A-Z]*(.data) }
|
|
.data : { *(.data) }
|
|
.bss : { *(.bss) }
|
|
}
|
|
</PRE>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC20" HREF="ld_toc.html#TOC20">Section Data Expressions</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX279"></A>
|
|
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 (see section <A HREF="ld_3.html#SEC7">Expressions</A>). Although these
|
|
statements are shown separately here for ease of presentation, no such
|
|
segregation is needed within a section definition in the <CODE>SECTIONS</CODE>
|
|
command; you can intermix them freely with any of the statements we've
|
|
just described.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>CREATE_OBJECT_SYMBOLS</CODE>
|
|
<DD>
|
|
<A NAME="IDX280"></A>
|
|
<A NAME="IDX281"></A>
|
|
<A NAME="IDX282"></A>
|
|
|
|
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 <CODE>a.out</CODE>
|
|
files it is conventional to have a symbol for each input file. You can
|
|
accomplish this by defining the output <CODE>.text</CODE> section as follows:
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
.text 0x2020 :
|
|
{
|
|
CREATE_OBJECT_SYMBOLS
|
|
*(.text)
|
|
_etext = ALIGN(0x2000);
|
|
}
|
|
...
|
|
}
|
|
</PRE>
|
|
|
|
If <CODE>sample.ld</CODE> is a file containing this script, and <CODE>a.o</CODE>,
|
|
<CODE>b.o</CODE>, <CODE>c.o</CODE>, and <CODE>d.o</CODE> are four input files with
|
|
contents like the following---
|
|
|
|
<PRE>
|
|
/* a.c */
|
|
|
|
afunction() { }
|
|
int adata=1;
|
|
int abss;
|
|
</PRE>
|
|
|
|
<SAMP>`ld -M -T sample.ld a.o b.o c.o d.o'</SAMP> would create a map like this,
|
|
containing symbols matching the object file names:
|
|
|
|
<PRE>
|
|
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
|
|
</PRE>
|
|
|
|
<A NAME="IDX283"></A>
|
|
<A NAME="IDX284"></A>
|
|
<DT><CODE><VAR>symbol</VAR> = <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>symbol</VAR> <VAR>f</VAR>= <VAR>expression</VAR> ;</CODE>
|
|
<DD>
|
|
<VAR>symbol</VAR> is any symbol name (see section <A HREF="ld_3.html#SEC9">Symbol Names</A>). "<VAR>f</VAR>="
|
|
refers to any of the operators <CODE>&= += -= *= /=</CODE> which combine
|
|
arithmetic and assignment.
|
|
|
|
<A NAME="IDX285"></A>
|
|
When you assign a value to a symbol within a particular section
|
|
definition, the value is relative to the beginning of the section
|
|
(see section <A HREF="ld_3.html#SEC13">Assignment: Defining Symbols</A>). If you write
|
|
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
abs = 14 ;
|
|
...
|
|
.data : { ... rel = 14 ; ... }
|
|
abs2 = 14 + ADDR(.data);
|
|
...
|
|
}
|
|
</PRE>
|
|
|
|
<CODE>abs</CODE> and <CODE>rel</CODE> do not have the same value; <CODE>rel</CODE> has the
|
|
same value as <CODE>abs2</CODE>.
|
|
|
|
<A NAME="IDX286"></A>
|
|
<A NAME="IDX287"></A>
|
|
<A NAME="IDX288"></A>
|
|
<A NAME="IDX289"></A>
|
|
<A NAME="IDX290"></A>
|
|
<A NAME="IDX291"></A>
|
|
<DT><CODE>BYTE(<VAR>expression</VAR>)</CODE>
|
|
<DD>
|
|
<DT><CODE>SHORT(<VAR>expression</VAR>)</CODE>
|
|
<DD>
|
|
<DT><CODE>LONG(<VAR>expression</VAR>)</CODE>
|
|
<DD>
|
|
<DT><CODE>QUAD(<VAR>expression</VAR>)</CODE>
|
|
<DD>
|
|
<DT><CODE>SQUAD(<VAR>expression</VAR>)</CODE>
|
|
<DD>
|
|
By including one of these four statements in a section definition, you
|
|
can explicitly place one, two, four, eight unsigned, or eight signed
|
|
bytes (respectively) at the current address of that section. When using
|
|
a 64 bit host or target, <CODE>QUAD</CODE> and <CODE>SQUAD</CODE> are the same.
|
|
When both host and target are 32 bits, <CODE>QUAD</CODE> uses an unsigned 32
|
|
bit value, and <CODE>SQUAD</CODE> sign extends the value. Both will use the
|
|
correct endianness when writing out the value.
|
|
|
|
Multiple-byte quantities are represented in whatever byte order is
|
|
appropriate for the output file format (see section <A HREF="ld_5.html#SEC30">BFD</A>).
|
|
|
|
<A NAME="IDX292"></A>
|
|
<A NAME="IDX293"></A>
|
|
<A NAME="IDX294"></A>
|
|
<DT><CODE>FILL(<VAR>expression</VAR>)</CODE>
|
|
<DD>
|
|
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 <SAMP>`.'</SAMP>)
|
|
are filled with the two least significant bytes from the
|
|
<VAR>expression</VAR> argument. A <CODE>FILL</CODE> statement covers memory
|
|
locations <EM>after</EM> the point it occurs in the section definition; by
|
|
including more than one <CODE>FILL</CODE> statement, you can have different
|
|
fill patterns in different parts of an output section.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC21" HREF="ld_toc.html#TOC21">Optional Section Attributes</A></H3>
|
|
<P>
|
|
<A NAME="IDX295"></A>
|
|
Here is the full syntax of a section definition, including all the
|
|
optional portions:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
...
|
|
<VAR>secname</VAR> <VAR>start</VAR> BLOCK(<VAR>align</VAR>) (NOLOAD) : AT ( <VAR>ldadr</VAR> )
|
|
{ <VAR>contents</VAR> } ><VAR>region</VAR> :<VAR>phdr</VAR> =<VAR>fill</VAR>
|
|
...
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
<VAR>secname</VAR> and <VAR>contents</VAR> are required. See section <A HREF="ld_3.html#SEC18">Section Definitions</A>, and section <A HREF="ld_3.html#SEC19">Section Placement</A>, for details on
|
|
<VAR>contents</VAR>. The remaining elements---<VAR>start</VAR>,
|
|
<CODE>BLOCK(<VAR>align)</VAR></CODE>, <CODE>(NOLOAD)</CODE>, <CODE>AT ( <VAR>ldadr</VAR> )</CODE>,
|
|
<CODE>><VAR>region</VAR></CODE>, <CODE>:<VAR>phdr</VAR></CODE>, and <CODE>=<VAR>fill</VAR></CODE>---are
|
|
all optional.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>start</VAR></CODE>
|
|
<DD>
|
|
<A NAME="IDX296"></A>
|
|
<A NAME="IDX297"></A>
|
|
<A NAME="IDX298"></A>
|
|
|
|
You can force the output section to be loaded at a specified address by
|
|
specifying <VAR>start</VAR> immediately following the section name.
|
|
<VAR>start</VAR> can be represented as any expression. The following
|
|
example generates section <VAR>output</VAR> at location
|
|
<CODE>0x40000000</CODE>:
|
|
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
...
|
|
output 0x40000000: {
|
|
...
|
|
}
|
|
...
|
|
}
|
|
</PRE>
|
|
|
|
<A NAME="IDX299"></A>
|
|
<A NAME="IDX300"></A>
|
|
<A NAME="IDX301"></A>
|
|
<DT><CODE>BLOCK(<VAR>align</VAR>)</CODE>
|
|
<DD>
|
|
You can include <CODE>BLOCK()</CODE> specification to advance
|
|
the location counter <CODE>.</CODE> prior to the beginning of the section, so
|
|
that the section will begin at the specified alignment. <VAR>align</VAR> is
|
|
an expression.
|
|
|
|
<A NAME="IDX302"></A>
|
|
<A NAME="IDX303"></A>
|
|
<A NAME="IDX304"></A>
|
|
<DT><CODE>(NOLOAD)</CODE>
|
|
<DD>
|
|
The <SAMP>`(NOLOAD)'</SAMP> directive will mark a section to not be loaded at
|
|
run time. The linker will process the section normally, but will mark
|
|
it so that a program loader will not load it into memory. For example,
|
|
in the script sample below, the <CODE>ROM</CODE> section is addressed at
|
|
memory location <SAMP>`0'</SAMP> and does not need to be loaded when the program
|
|
is run. The contents of the <CODE>ROM</CODE> section will appear in the
|
|
linker output file as usual.
|
|
|
|
|
|
<PRE>
|
|
SECTIONS {
|
|
ROM 0 (NOLOAD) : { ... }
|
|
...
|
|
}
|
|
</PRE>
|
|
|
|
<A NAME="IDX305"></A>
|
|
<A NAME="IDX306"></A>
|
|
<A NAME="IDX307"></A>
|
|
<DT><CODE>AT ( <VAR>ldadr</VAR> )</CODE>
|
|
<DD>
|
|
The expression <VAR>ldadr</VAR> that follows the <CODE>AT</CODE> keyword specifies
|
|
the load address of the section. The default (if you do not use the
|
|
<CODE>AT</CODE> keyword) is to make the load address the same as the
|
|
relocation address. This feature is designed to make it easy to build a
|
|
ROM image. For example, this <CODE>SECTIONS</CODE> definition creates two
|
|
output sections: one called <SAMP>`.text'</SAMP>, which starts at <CODE>0x1000</CODE>,
|
|
and one called <SAMP>`.mdata'</SAMP>, which is loaded at the end of the
|
|
<SAMP>`.text'</SAMP> section even though its relocation address is
|
|
<CODE>0x2000</CODE>. The symbol <CODE>_data</CODE> is defined with the value
|
|
<CODE>0x2000</CODE>:
|
|
|
|
|
|
<PRE>
|
|
SECTIONS
|
|
{
|
|
.text 0x1000 : { *(.text) _etext = . ; }
|
|
.mdata 0x2000 :
|
|
AT ( ADDR(.text) + SIZEOF ( .text ) )
|
|
{ _data = . ; *(.data); _edata = . ; }
|
|
.bss 0x3000 :
|
|
{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;}
|
|
}
|
|
</PRE>
|
|
|
|
The run-time initialization code (for C programs, usually <CODE>crt0</CODE>)
|
|
for use with a ROM generated this way has to include something like
|
|
the following, to copy the initialized data from the ROM image to its runtime
|
|
address:
|
|
|
|
|
|
<PRE>
|
|
char *src = _etext;
|
|
char *dst = _data;
|
|
|
|
/* ROM has data at end of text; copy it. */
|
|
while (dst < _edata) {
|
|
*dst++ = *src++;
|
|
}
|
|
|
|
/* Zero bss */
|
|
for (dst = _bstart; dst< _bend; dst++)
|
|
*dst = 0;
|
|
</PRE>
|
|
|
|
<A NAME="IDX308"></A>
|
|
<A NAME="IDX309"></A>
|
|
<A NAME="IDX310"></A>
|
|
<DT><CODE>><VAR>region</VAR></CODE>
|
|
<DD>
|
|
Assign this section to a previously defined region of memory.
|
|
See section <A HREF="ld_3.html#SEC16">Memory Layout</A>.
|
|
|
|
<A NAME="IDX311"></A>
|
|
<A NAME="IDX312"></A>
|
|
<A NAME="IDX313"></A>
|
|
<DT><CODE>:<VAR>phdr</VAR></CODE>
|
|
<DD>
|
|
Assign this section to a segment described by a program header.
|
|
See section <A HREF="ld_3.html#SEC23">ELF Program Headers</A>. If a section is assigned to one or more segments, then
|
|
all subsequent allocated sections will be assigned to those segments as
|
|
well, unless they use an explicitly <CODE>:<VAR>phdr</VAR></CODE> modifier. To
|
|
prevent a section from being assigned to a segment when it would
|
|
normally default to one, use <CODE>:NONE</CODE>.
|
|
|
|
<A NAME="IDX314"></A>
|
|
<A NAME="IDX315"></A>
|
|
<A NAME="IDX316"></A>
|
|
<DT><CODE>=<VAR>fill</VAR></CODE>
|
|
<DD>
|
|
Including <CODE>=<VAR>fill</VAR></CODE> in a section definition specifies the
|
|
initial fill value for that section. You may use any expression to
|
|
specify <VAR>fill</VAR>. 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 <CODE>FILL</CODE> statement in the <VAR>contents</VAR>
|
|
of a section definition.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC22" HREF="ld_toc.html#TOC22">Overlays</A></H3>
|
|
<P>
|
|
<A NAME="IDX317"></A>
|
|
<A NAME="IDX318"></A>
|
|
|
|
</P>
|
|
<P>
|
|
The <CODE>OVERLAY</CODE> command provides an easy way to describe sections
|
|
which are to be loaded as part of a single memory image but are to be
|
|
run at the same memory address. At run time, some sort of overlay
|
|
manager will copy the overlaid sections in and out of the runtime memory
|
|
address as required, perhaps by simply manipulating addressing bits.
|
|
This approach can be useful, for example, when a certain region of
|
|
memory is faster than another.
|
|
|
|
</P>
|
|
<P>
|
|
The <CODE>OVERLAY</CODE> command is used within a <CODE>SECTIONS</CODE> command. It
|
|
appears as follows:
|
|
|
|
<PRE>
|
|
OVERLAY <VAR>start</VAR> : [ NOCROSSREFS ] AT ( <VAR>ldaddr</VAR> )
|
|
{
|
|
<VAR>secname1</VAR> { <VAR>contents</VAR> } :<VAR>phdr</VAR> =<VAR>fill</VAR>
|
|
<VAR>secname2</VAR> { <VAR>contents</VAR> } :<VAR>phdr</VAR> =<VAR>fill</VAR>
|
|
...
|
|
} ><VAR>region</VAR> :<VAR>phdr</VAR> =<VAR>fill</VAR>
|
|
</PRE>
|
|
|
|
<P>
|
|
Everything is optional except <CODE>OVERLAY</CODE> (a keyword), and each
|
|
section must have a name (<VAR>secname1</VAR> and <VAR>secname2</VAR> above). The
|
|
section definitions within the <CODE>OVERLAY</CODE> construct are identical to
|
|
those within the general <CODE>SECTIONS</CODE> contruct (see section <A HREF="ld_3.html#SEC17">Specifying Output Sections</A>),
|
|
except that no addresses and no memory regions may be defined for
|
|
sections within an <CODE>OVERLAY</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
The sections are all defined with the same starting address. The load
|
|
addresses of the sections are arranged such that they are consecutive in
|
|
memory starting at the load address used for the <CODE>OVERLAY</CODE> as a
|
|
whole (as with normal section definitions, the load address is optional,
|
|
and defaults to the start address; the start address is also optional,
|
|
and defaults to <CODE>.</CODE>).
|
|
|
|
</P>
|
|
<P>
|
|
If the <CODE>NOCROSSREFS</CODE> keyword is used, and there any references
|
|
among the sections, the linker will report an error. Since the sections
|
|
all run at the same address, it normally does not make sense for one
|
|
section to refer directly to another. See section <A HREF="ld_3.html#SEC26">Option Commands</A>.
|
|
|
|
</P>
|
|
<P>
|
|
For each section within the <CODE>OVERLAY</CODE>, the linker automatically
|
|
defines two symbols. The symbol <CODE>__load_start_<VAR>secname</VAR></CODE> is
|
|
defined as the starting load address of the section. The symbol
|
|
<CODE>__load_stop_<VAR>secname</VAR></CODE> is defined as the final load address of
|
|
the section. Any characters within <VAR>secname</VAR> which are not legal
|
|
within C identifiers are removed. C (or assembler) code may use these
|
|
symbols to move the overlaid sections around as necessary.
|
|
|
|
</P>
|
|
<P>
|
|
At the end of the overlay, the value of <CODE>.</CODE> is set to the start
|
|
address of the overlay plus the size of the largest section.
|
|
|
|
</P>
|
|
<P>
|
|
Here is an example. Remember that this would appear inside a
|
|
<CODE>SECTIONS</CODE> construct.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
OVERLAY 0x1000 : AT (0x4000)
|
|
{
|
|
.text0 { o1/*.o(.text) }
|
|
.text1 { o2/*.o(.text) }
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
This will define both <CODE>.text0</CODE> and <CODE>.text1</CODE> to start at
|
|
address 0x1000. <CODE>.text0</CODE> will be loaded at address 0x4000, and
|
|
<CODE>.text1</CODE> will be loaded immediately after <CODE>.text0</CODE>. The
|
|
following symbols will be defined: <CODE>__load_start_text0</CODE>,
|
|
<CODE>__load_stop_text0</CODE>, <CODE>__load_start_text1</CODE>,
|
|
<CODE>__load_stop_text1</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
C code to copy overlay <CODE>.text1</CODE> into the overlay area might look
|
|
like the following.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
extern char __load_start_text1, __load_stop_text1;
|
|
memcpy ((char *) 0x1000, &__load_start_text1,
|
|
&__load_stop_text1 - &__load_start_text1);
|
|
</PRE>
|
|
|
|
<P>
|
|
Note that the <CODE>OVERLAY</CODE> command is just syntactic sugar, since
|
|
everything it does can be done using the more basic commands. The above
|
|
example could have been written identically as follows.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
.text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
|
|
__load_start_text0 = LOADADDR (.text0);
|
|
__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
|
|
.text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
|
|
__load_start_text1 = LOADADDR (.text1);
|
|
__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
|
|
. = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC23" HREF="ld_toc.html#TOC23">ELF Program Headers</A></H2>
|
|
<P>
|
|
<A NAME="IDX319"></A>
|
|
<A NAME="IDX320"></A>
|
|
<A NAME="IDX321"></A>
|
|
|
|
</P>
|
|
<P>
|
|
The ELF object file format uses <EM>program headers</EM>, which are read by
|
|
the system loader and describe how the program should be loaded into
|
|
memory. These program headers must be set correctly in order to run the
|
|
program on a native ELF system. The linker will create reasonable
|
|
program headers by default. However, in some cases, it is desirable to
|
|
specify the program headers more precisely; the <CODE>PHDRS</CODE> command may
|
|
be used for this purpose. When the <CODE>PHDRS</CODE> command is used, the
|
|
linker will not generate any program headers itself.
|
|
|
|
</P>
|
|
<P>
|
|
The <CODE>PHDRS</CODE> command is only meaningful when generating an ELF
|
|
output file. It is ignored in other cases. This manual does not
|
|
describe the details of how the system loader interprets program
|
|
headers; for more information, see the ELF ABI. The program headers of
|
|
an ELF file may be displayed using the <SAMP>`-p'</SAMP> option of the
|
|
<CODE>objdump</CODE> command.
|
|
|
|
</P>
|
|
<P>
|
|
This is the syntax of the <CODE>PHDRS</CODE> command. The words <CODE>PHDRS</CODE>,
|
|
<CODE>FILEHDR</CODE>, <CODE>AT</CODE>, and <CODE>FLAGS</CODE> are keywords.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
PHDRS
|
|
{
|
|
<VAR>name</VAR> <VAR>type</VAR> [ FILEHDR ] [ PHDRS ] [ AT ( <VAR>address</VAR> ) ]
|
|
[ FLAGS ( <VAR>flags</VAR> ) ] ;
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
The <VAR>name</VAR> is used only for reference in the <CODE>SECTIONS</CODE> command
|
|
of the linker script. It does not get put into the output file.
|
|
|
|
</P>
|
|
<P>
|
|
Certain program header types describe segments of memory which are
|
|
loaded from the file by the system loader. In the linker script, the
|
|
contents of these segments are specified by directing allocated output
|
|
sections to be placed in the segment. To do this, the command
|
|
describing the output section in the <CODE>SECTIONS</CODE> command should use
|
|
<SAMP>`:<VAR>name</VAR>'</SAMP>, where <VAR>name</VAR> is the name of the program header
|
|
as it appears in the <CODE>PHDRS</CODE> command. See section <A HREF="ld_3.html#SEC21">Optional Section Attributes</A>.
|
|
|
|
</P>
|
|
<P>
|
|
It is normal for certain sections to appear in more than one segment.
|
|
This merely implies that one segment of memory contains another. This
|
|
is specified by repeating <SAMP>`:<VAR>name</VAR>'</SAMP>, using it once for each
|
|
program header in which the section is to appear.
|
|
|
|
</P>
|
|
<P>
|
|
If a section is placed in one or more segments using <SAMP>`:<VAR>name</VAR>'</SAMP>,
|
|
then all subsequent allocated sections which do not specify
|
|
<SAMP>`:<VAR>name</VAR>'</SAMP> are placed in the same segments. This is for
|
|
convenience, since generally a whole set of contiguous sections will be
|
|
placed in a single segment. To prevent a section from being assigned to
|
|
a segment when it would normally default to one, use <CODE>:NONE</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
The <CODE>FILEHDR</CODE> and <CODE>PHDRS</CODE> keywords which may appear after the
|
|
program header type also indicate contents of the segment of memory.
|
|
The <CODE>FILEHDR</CODE> keyword means that the segment should include the ELF
|
|
file header. The <CODE>PHDRS</CODE> keyword means that the segment should
|
|
include the ELF program headers themselves.
|
|
|
|
</P>
|
|
<P>
|
|
The <VAR>type</VAR> may be one of the following. The numbers indicate the
|
|
value of the keyword.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>PT_NULL</CODE> (0)
|
|
<DD>
|
|
Indicates an unused program header.
|
|
|
|
<DT><CODE>PT_LOAD</CODE> (1)
|
|
<DD>
|
|
Indicates that this program header describes a segment to be loaded from
|
|
the file.
|
|
|
|
<DT><CODE>PT_DYNAMIC</CODE> (2)
|
|
<DD>
|
|
Indicates a segment where dynamic linking information can be found.
|
|
|
|
<DT><CODE>PT_INTERP</CODE> (3)
|
|
<DD>
|
|
Indicates a segment where the name of the program interpreter may be
|
|
found.
|
|
|
|
<DT><CODE>PT_NOTE</CODE> (4)
|
|
<DD>
|
|
Indicates a segment holding note information.
|
|
|
|
<DT><CODE>PT_SHLIB</CODE> (5)
|
|
<DD>
|
|
A reserved program header type, defined but not specified by the ELF
|
|
ABI.
|
|
|
|
<DT><CODE>PT_PHDR</CODE> (6)
|
|
<DD>
|
|
Indicates a segment where the program headers may be found.
|
|
|
|
<DT><VAR>expression</VAR>
|
|
<DD>
|
|
An expression giving the numeric type of the program header. This may
|
|
be used for types not defined above.
|
|
</DL>
|
|
|
|
<P>
|
|
It is possible to specify that a segment should be loaded at a
|
|
particular address in memory. This is done using an <CODE>AT</CODE>
|
|
expression. This is identical to the <CODE>AT</CODE> command used in the
|
|
<CODE>SECTIONS</CODE> command (see section <A HREF="ld_3.html#SEC21">Optional Section Attributes</A>). Using the <CODE>AT</CODE>
|
|
command for a program header overrides any information in the
|
|
<CODE>SECTIONS</CODE> command.
|
|
|
|
</P>
|
|
<P>
|
|
Normally the segment flags are set based on the sections. The
|
|
<CODE>FLAGS</CODE> keyword may be used to explicitly specify the segment
|
|
flags. The value of <VAR>flags</VAR> must be an integer. It is used to
|
|
set the <CODE>p_flags</CODE> field of the program header.
|
|
|
|
</P>
|
|
<P>
|
|
Here is an example of the use of <CODE>PHDRS</CODE>. This shows a typical set
|
|
of program headers used on a native ELF system.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
PHDRS
|
|
{
|
|
headers PT_PHDR PHDRS ;
|
|
interp PT_INTERP ;
|
|
text PT_LOAD FILEHDR PHDRS ;
|
|
data PT_LOAD ;
|
|
dynamic PT_DYNAMIC ;
|
|
}
|
|
|
|
SECTIONS
|
|
{
|
|
. = SIZEOF_HEADERS;
|
|
.interp : { *(.interp) } :text :interp
|
|
.text : { *(.text) } :text
|
|
.rodata : { *(.rodata) } /* defaults to :text */
|
|
...
|
|
. = . + 0x1000; /* move to a new page in memory */
|
|
.data : { *(.data) } :data
|
|
.dynamic : { *(.dynamic) } :data :dynamic
|
|
...
|
|
}
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC24" HREF="ld_toc.html#TOC24">The Entry Point</A></H2>
|
|
<P>
|
|
<A NAME="IDX322"></A>
|
|
<A NAME="IDX323"></A>
|
|
<A NAME="IDX324"></A>
|
|
The linker command language includes a command specifically for
|
|
defining the first executable instruction in an output file (its
|
|
<EM>entry point</EM>). Its argument is a symbol name:
|
|
|
|
<PRE>
|
|
ENTRY(<VAR>symbol</VAR>)
|
|
</PRE>
|
|
|
|
<P>
|
|
Like symbol assignments, the <CODE>ENTRY</CODE> command may be placed either
|
|
as an independent command in the command file, or among the section
|
|
definitions within the <CODE>SECTIONS</CODE> command--whatever makes the most
|
|
sense for your layout.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX325"></A>
|
|
<CODE>ENTRY</CODE> 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).
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
the <SAMP>`-e'</SAMP> <VAR>entry</VAR> command-line option;
|
|
<LI>
|
|
|
|
the <CODE>ENTRY(<VAR>symbol</VAR>)</CODE> command in a linker control script;
|
|
<LI>
|
|
|
|
the value of the symbol <CODE>start</CODE>, if present;
|
|
<LI>
|
|
|
|
the address of the first byte of the <CODE>.text</CODE> section, if present;
|
|
<LI>
|
|
|
|
The address <CODE>0</CODE>.
|
|
</UL>
|
|
|
|
<P>
|
|
For example, you can use these rules to generate an entry point with an
|
|
assignment statement: if no symbol <CODE>start</CODE> is defined within your
|
|
input files, you can simply define it, assigning it an appropriate
|
|
value---
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
start = 0x2020;
|
|
</PRE>
|
|
|
|
<P>
|
|
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 <CODE>start</CODE>:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
start = other_symbol ;
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC25" HREF="ld_toc.html#TOC25">Version Script</A></H2>
|
|
<P>
|
|
<A NAME="IDX326"></A>
|
|
<A NAME="IDX327"></A>
|
|
<A NAME="IDX328"></A>
|
|
<A NAME="IDX329"></A>
|
|
The linker command script includes a command specifically for
|
|
specifying a version script, and is only meaningful for ELF platforms
|
|
that support shared libraries. A version script can be
|
|
build directly into the linker script that you are using, or you
|
|
can supply the version script as just another input file to the linker
|
|
at the time that you link. The command script syntax is:
|
|
|
|
<PRE>
|
|
VERSION { version script contents }
|
|
</PRE>
|
|
|
|
<P>
|
|
The version script can also be specified to the linker by means of the
|
|
<SAMP>`--version-script'</SAMP> linker command line option.
|
|
Version scripts are only meaningful when creating shared libraries.
|
|
|
|
</P>
|
|
<P>
|
|
The format of the version script itself is identical to that used by
|
|
Sun's linker in Solaris 2.5. Versioning is done by defining a tree of
|
|
version nodes with the names and interdependencies specified in the
|
|
version script. The version script can specify which symbols are bound
|
|
to which version nodes, and it can reduce a specified set of symbols to
|
|
local scope so that they are not globally visible outside of the shared
|
|
library.
|
|
|
|
</P>
|
|
<P>
|
|
The easiest way to demonstrate the version script language is with a few
|
|
examples.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
VERS_1.1 {
|
|
global:
|
|
foo1;
|
|
local:
|
|
old*;
|
|
original*;
|
|
new*;
|
|
};
|
|
|
|
VERS_1.2 {
|
|
foo2;
|
|
} VERS_1.1;
|
|
|
|
VERS_2.0 {
|
|
bar1; bar2;
|
|
} VERS_1.2;
|
|
</PRE>
|
|
|
|
<P>
|
|
In this example, three version nodes are defined. <SAMP>`VERS_1.1'</SAMP> is the
|
|
first version node defined, and has no other dependencies. The symbol
|
|
<SAMP>`foo1'</SAMP> is bound to this version node, and a number of symbols
|
|
that have appeared within various object files are reduced in scope to
|
|
local so that they are not visible outside of the shared library.
|
|
|
|
</P>
|
|
<P>
|
|
Next, the node <SAMP>`VERS_1.2'</SAMP> is defined. It depends upon
|
|
<SAMP>`VERS_1.1'</SAMP>. The symbol <SAMP>`foo2'</SAMP> is bound to this version node.
|
|
|
|
</P>
|
|
<P>
|
|
Finally, the node <SAMP>`VERS_2.0'</SAMP> is defined. It depends upon
|
|
<SAMP>`VERS_1.2'</SAMP>. The symbols <SAMP>`bar1'</SAMP> and <SAMP>`bar2'</SAMP> are bound to
|
|
this version node.
|
|
|
|
</P>
|
|
<P>
|
|
Symbols defined in the library which aren't specifically bound to a
|
|
version node are effectively bound to an unspecified base version of the
|
|
library. It is possible to bind all otherwise unspecified symbols to a
|
|
given version node using <SAMP>`global: *'</SAMP> somewhere in the version
|
|
script.
|
|
|
|
</P>
|
|
<P>
|
|
Lexically the names of the version nodes have no specific meaning other
|
|
than what they might suggest to the person reading them. The <SAMP>`2.0'</SAMP>
|
|
version could just as well have appeared in between <SAMP>`1.1'</SAMP> and
|
|
<SAMP>`1.2'</SAMP>. However, this would be a confusing way to write a version
|
|
script.
|
|
|
|
</P>
|
|
<P>
|
|
When you link an application against a shared library that has versioned
|
|
symbols, the application itself knows which version of each symbol it requires,
|
|
and it also knows which version nodes it needs from each shared library it is
|
|
linked against. Thus at runtime, the dynamic loader can make a quick check to
|
|
make sure that the libraries you have linked against do in fact supply all
|
|
of the version nodes that the application will need to resolve all of the
|
|
dynamic symbols. In this way it is possible for the dynamic linker to know
|
|
with certainty that all external symbols that it needs will be resolvable
|
|
without having to search for each symbol reference.
|
|
|
|
</P>
|
|
<P>
|
|
The symbol versioning is in effect a much more sophisticated way of
|
|
doing minor version checking that SunOS does. The fundamental problem
|
|
that is being addressed here is that typically references to external
|
|
functions are bound on an as-needed basis, and are not all bound when
|
|
the application starts up. If a shared library is out of date, a
|
|
required interface may be missing; when the application tries to use
|
|
that interface, it may suddenly and unexpectedly fail. With symbol
|
|
versioning, the user will get a warning when they start their program if
|
|
the libraries being used with the application are too old.
|
|
|
|
</P>
|
|
<P>
|
|
There are several GNU extensions to Sun's versioning approach. The
|
|
first of these is the ability to bind a symbol to a version node in the
|
|
source file where the symbol is defined instead of in the versioning
|
|
script. This was done mainly to reduce the burden on the library
|
|
maintainer. This can be done by putting something like:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
__asm__(".symver original_foo,foo@VERS_1.1");
|
|
</PRE>
|
|
|
|
<P>
|
|
in the C source file. This renamed the function <SAMP>`original_foo'</SAMP> to
|
|
be an alias for <SAMP>`foo'</SAMP> bound to the version node <SAMP>`VERS_1.1'</SAMP>.
|
|
The <SAMP>`local:'</SAMP> directive can be used to prevent the symbol
|
|
<SAMP>`original_foo'</SAMP> from being exported.
|
|
|
|
</P>
|
|
<P>
|
|
The second GNU extension is to allow multiple versions of the same function
|
|
to appear in a given shared library. In this way an incompatible change to
|
|
an interface can take place without increasing the major version number of
|
|
the shared library, while still allowing applications linked against the old
|
|
interface to continue to function.
|
|
|
|
</P>
|
|
<P>
|
|
This can only be accomplished by using multiple <SAMP>`.symver'</SAMP>
|
|
directives in the assembler. An example of this would be:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
__asm__(".symver original_foo,foo@");
|
|
__asm__(".symver old_foo,foo@VERS_1.1");
|
|
__asm__(".symver old_foo1,foo@VERS_1.2");
|
|
__asm__(".symver new_foo,foo@@VERS_2.0");
|
|
</PRE>
|
|
|
|
<P>
|
|
In this example, <SAMP>`foo@'</SAMP> represents the symbol <SAMP>`foo'</SAMP> bound to the
|
|
unspecified base version of the symbol. The source file that contains this
|
|
example would define 4 C functions: <SAMP>`original_foo'</SAMP>, <SAMP>`old_foo'</SAMP>,
|
|
<SAMP>`old_foo1'</SAMP>, and <SAMP>`new_foo'</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
When you have multiple definitions of a given symbol, there needs to be
|
|
some way to specify a default version to which external references to
|
|
this symbol will be bound. This can be accomplished with the
|
|
<SAMP>`foo@@VERS_2.0'</SAMP> type of <SAMP>`.symver'</SAMP> directive. Only one version of
|
|
a symbol can be declared 'default' in this manner - otherwise you would
|
|
effectively have multiple definitions of the same symbol.
|
|
|
|
</P>
|
|
<P>
|
|
If you wish to bind a reference to a specific version of the symbol
|
|
within the shared library, you can use the aliases of convenience
|
|
(i.e. <SAMP>`old_foo'</SAMP>), or you can use the <SAMP>`.symver'</SAMP> directive to
|
|
specifically bind to an external version of the function in question.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC26" HREF="ld_toc.html#TOC26">Option Commands</A></H2>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>CONSTRUCTORS</CODE>
|
|
<DD>
|
|
<A NAME="IDX330"></A>
|
|
<A NAME="IDX331"></A>
|
|
<A NAME="IDX332"></A>
|
|
|
|
When linking using the <CODE>a.out</CODE> object file format, the linker uses
|
|
an unusual set construct to support C++ global constructors and
|
|
destructors. When linking object file formats which do not support
|
|
arbitrary sections, such as <CODE>ECOFF</CODE> and <CODE>XCOFF</CODE>, the linker
|
|
will automatically recognize C++ global constructors and destructors by
|
|
name. For these object file formats, the <CODE>CONSTRUCTORS</CODE> command
|
|
tells the linker where this information should be placed. The
|
|
<CODE>CONSTRUCTORS</CODE> command is ignored for other object file formats.
|
|
|
|
The symbol <CODE>__CTOR_LIST__</CODE> marks the start of the global
|
|
constructors, and the symbol <CODE>__DTOR_LIST</CODE> marks the end. The
|
|
first word in the list is the number of entries, followed by the address
|
|
of each constructor or destructor, followed by a zero word. The
|
|
compiler must arrange to actually run the code. For these object file
|
|
formats GNU C++ calls constructors from a subroutine <CODE>__main</CODE>;
|
|
a call to <CODE>__main</CODE> is automatically inserted into the startup code
|
|
for <CODE>main</CODE>. GNU C++ runs destructors either by using
|
|
<CODE>atexit</CODE>, or directly from the function <CODE>exit</CODE>.
|
|
|
|
For object file formats such as <CODE>COFF</CODE> or <CODE>ELF</CODE> which support
|
|
multiple sections, GNU C++ will normally arrange to put the
|
|
addresses of global constructors and destructors into the <CODE>.ctors</CODE>
|
|
and <CODE>.dtors</CODE> sections. Placing the following sequence into your
|
|
linker script will build the sort of table which the GNU C++
|
|
runtime code expects to see.
|
|
|
|
|
|
<PRE>
|
|
__CTOR_LIST__ = .;
|
|
LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
|
|
*(.ctors)
|
|
LONG(0)
|
|
__CTOR_END__ = .;
|
|
__DTOR_LIST__ = .;
|
|
LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
|
|
*(.dtors)
|
|
LONG(0)
|
|
__DTOR_END__ = .;
|
|
</PRE>
|
|
|
|
Normally the compiler and linker will handle these issues automatically,
|
|
and you will not need to concern yourself with them. However, you may
|
|
need to consider this if you are using C++ and writing your own linker
|
|
scripts.
|
|
|
|
<A NAME="IDX333"></A>
|
|
<A NAME="IDX334"></A>
|
|
<DT><CODE>FLOAT</CODE>
|
|
<DD>
|
|
<DT><CODE>NOFLOAT</CODE>
|
|
<DD>
|
|
These keywords were used in some older linkers to request a particular
|
|
math subroutine library. <CODE>ld</CODE> 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
|
|
<CODE>FLOAT</CODE> and <CODE>NOFLOAT</CODE> are accepted and ignored.
|
|
|
|
<A NAME="IDX335"></A>
|
|
<A NAME="IDX336"></A>
|
|
<DT><CODE>FORCE_COMMON_ALLOCATION</CODE>
|
|
<DD>
|
|
This command has the same effect as the <SAMP>`-d'</SAMP> command-line option:
|
|
to make <CODE>ld</CODE> assign space to common symbols even if a relocatable
|
|
output file is specified (<SAMP>`-r'</SAMP>).
|
|
|
|
<A NAME="IDX337"></A>
|
|
<A NAME="IDX338"></A>
|
|
<DT><CODE>INCLUDE <VAR>filename</VAR></CODE>
|
|
<DD>
|
|
Include the linker script <VAR>filename</VAR> at this point. The file will
|
|
be searched for in the current directory, and in any directory specified
|
|
with the <CODE>-L</CODE> option. You can nest calls to <CODE>INCLUDE</CODE> up to
|
|
10 levels deep.
|
|
|
|
<A NAME="IDX339"></A>
|
|
<A NAME="IDX340"></A>
|
|
<DT><CODE>INPUT ( <VAR>file</VAR>, <VAR>file</VAR>, ... )</CODE>
|
|
<DD>
|
|
<DT><CODE>INPUT ( <VAR>file</VAR> <VAR>file</VAR> ... )</CODE>
|
|
<DD>
|
|
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 <VAR>file</VAR>, including <SAMP>`.a'</SAMP> if
|
|
required.
|
|
|
|
<CODE>ld</CODE> searches for each <VAR>file</VAR> through the archive-library
|
|
search path, just as for files you specify on the command line.
|
|
See the description of <SAMP>`-L'</SAMP> in section <A HREF="ld_2.html#SEC3">Command Line Options</A>.
|
|
|
|
If you use <SAMP>`-l<VAR>file</VAR>'</SAMP>, <CODE>ld</CODE> will transform the name to
|
|
<CODE>lib<VAR>file</VAR>.a</CODE> as with the command line argument <SAMP>`-l'</SAMP>.
|
|
|
|
<A NAME="IDX341"></A>
|
|
<A NAME="IDX342"></A>
|
|
<DT><CODE>GROUP ( <VAR>file</VAR>, <VAR>file</VAR>, ... )</CODE>
|
|
<DD>
|
|
<DT><CODE>GROUP ( <VAR>file</VAR> <VAR>file</VAR> ... )</CODE>
|
|
<DD>
|
|
This command is like <CODE>INPUT</CODE>, except that the named files should
|
|
all be archives, and they are searched repeatedly until no new undefined
|
|
references are created. See the description of <SAMP>`-('</SAMP> in
|
|
section <A HREF="ld_2.html#SEC3">Command Line Options</A>.
|
|
|
|
<A NAME="IDX343"></A>
|
|
<A NAME="IDX344"></A>
|
|
<DT><CODE>OUTPUT ( <VAR>filename</VAR> )</CODE>
|
|
<DD>
|
|
Use this command to name the link output file <VAR>filename</VAR>. The
|
|
effect of <CODE>OUTPUT(<VAR>filename</VAR>)</CODE> is identical to the effect of
|
|
<SAMP>`-o <VAR>filename</VAR>'</SAMP>, which overrides it. You can use this
|
|
command to supply a default output-file name other than <CODE>a.out</CODE>.
|
|
|
|
<A NAME="IDX345"></A>
|
|
<A NAME="IDX346"></A>
|
|
<DT><CODE>OUTPUT_ARCH ( <VAR>bfdname</VAR> )</CODE>
|
|
<DD>
|
|
Specify a particular output machine architecture, with one of the names
|
|
used by the BFD back-end routines (see section <A HREF="ld_5.html#SEC30">BFD</A>). 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 <CODE>OUTPUT_FORMAT</CODE>
|
|
command.
|
|
|
|
<A NAME="IDX347"></A>
|
|
<A NAME="IDX348"></A>
|
|
<DT><CODE>OUTPUT_FORMAT ( <VAR>bfdname</VAR> )</CODE>
|
|
<DD>
|
|
When <CODE>ld</CODE> is configured to support multiple object code formats,
|
|
you can use this command to specify a particular output format.
|
|
<VAR>bfdname</VAR> is one of the names used by the BFD back-end routines
|
|
(see section <A HREF="ld_5.html#SEC30">BFD</A>). The effect is identical to the effect of the
|
|
<SAMP>`--oformat'</SAMP> command-line option. This selection affects only the
|
|
output file; the related command <CODE>TARGET</CODE> affects primarily input
|
|
files.
|
|
|
|
<A NAME="IDX349"></A>
|
|
<A NAME="IDX350"></A>
|
|
<A NAME="IDX351"></A>
|
|
<DT><CODE>SEARCH_DIR ( <VAR>path</VAR> )</CODE>
|
|
<DD>
|
|
Add <VAR>path</VAR> to the list of paths where <CODE>ld</CODE> looks for
|
|
archive libraries. <CODE>SEARCH_DIR(<VAR>path</VAR>)</CODE> has the same
|
|
effect as <SAMP>`-L<VAR>path</VAR>'</SAMP> on the command line.
|
|
|
|
<A NAME="IDX352"></A>
|
|
<A NAME="IDX353"></A>
|
|
<DT><CODE>STARTUP ( <VAR>filename</VAR> )</CODE>
|
|
<DD>
|
|
Ensure that <VAR>filename</VAR> is the first input file used in the link
|
|
process.
|
|
|
|
<A NAME="IDX354"></A>
|
|
<A NAME="IDX355"></A>
|
|
<DT><CODE>TARGET ( <VAR>format</VAR> )</CODE>
|
|
<DD>
|
|
When <CODE>ld</CODE> is configured to support multiple object code formats,
|
|
you can use this command to change the input-file object code format
|
|
(like the command-line option <SAMP>`-b'</SAMP> or its synonym <SAMP>`--format'</SAMP>).
|
|
The argument <VAR>format</VAR> is one of the strings used by BFD to name
|
|
binary formats. If <CODE>TARGET</CODE> is specified but <CODE>OUTPUT_FORMAT</CODE>
|
|
is not, the last <CODE>TARGET</CODE> argument is also used as the default
|
|
format for the <CODE>ld</CODE> output file. See section <A HREF="ld_5.html#SEC30">BFD</A>.
|
|
|
|
<A NAME="IDX356"></A>
|
|
If you don't use the <CODE>TARGET</CODE> command, <CODE>ld</CODE> uses the value of
|
|
the environment variable <CODE>GNUTARGET</CODE>, if available, to select the
|
|
output file format. If that variable is also absent, <CODE>ld</CODE> uses
|
|
the default format configured for your machine in the BFD libraries.
|
|
|
|
<A NAME="IDX357"></A>
|
|
<A NAME="IDX358"></A>
|
|
<DT><CODE>NOCROSSREFS ( <VAR>section</VAR> <VAR>section</VAR> ... )</CODE>
|
|
<DD>
|
|
This command may be used to tell <CODE>ld</CODE> to issue an error about any
|
|
references among certain sections.
|
|
|
|
In certain types of programs, particularly on embedded systems, when one
|
|
section is loaded into memory, another section will not be. Any direct
|
|
references between the two sections would be errors. For example, it
|
|
would be an error if code in one section called a function defined in
|
|
the other section.
|
|
|
|
The <CODE>NOCROSSREFS</CODE> command takes a list of section names. If
|
|
<CODE>ld</CODE> detects any cross references between the sections, it reports
|
|
an error and returns a non-zero exit status. The <CODE>NOCROSSREFS</CODE>
|
|
command uses output section names, defined in the <CODE>SECTIONS</CODE>
|
|
command. It does not use the names of input sections.
|
|
</DL>
|
|
|
|
<P><HR><P>
|
|
Go to the <A HREF="ld_1.html">first</A>, <A HREF="ld_2.html">previous</A>, <A HREF="ld_4.html">next</A>, <A HREF="ld_8.html">last</A> section, <A HREF="ld_toc.html">table of contents</A>.
|
|
</BODY>
|
|
</HTML>
|