You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
358 lines
15 KiB
HTML
358 lines
15 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- This file documents the GNU linker LD
|
||
|
|
(SiFive Binutils 2.32.0-2020.04.1)
|
||
|
|
version 2.32.
|
||
|
|
|
||
|
|
Copyright (C) 1991-2019 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
||
|
|
or any later version published by the Free Software Foundation;
|
||
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
||
|
|
Back-Cover Texts. A copy of the license is included in the
|
||
|
|
section entitled "GNU Free Documentation License". -->
|
||
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Builtin Functions (LD)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Builtin Functions (LD)">
|
||
|
|
<meta name="keywords" content="Builtin Functions (LD)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Expressions.html#Expressions" rel="up" title="Expressions">
|
||
|
|
<link href="Implicit-Linker-Scripts.html#Implicit-Linker-Scripts" rel="next" title="Implicit Linker Scripts">
|
||
|
|
<link href="Expression-Section.html#Expression-Section" rel="prev" title="Expression Section">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style: oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<a name="Builtin-Functions"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Previous: <a href="Expression-Section.html#Expression-Section" accesskey="p" rel="prev">Expression Section</a>, Up: <a href="Expressions.html#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="Builtin-Functions-1"></a>
|
||
|
|
<h4 class="subsection">3.10.9 Builtin Functions</h4>
|
||
|
|
<a name="index-functions-in-expressions"></a>
|
||
|
|
<p>The linker script language includes a number of builtin functions for
|
||
|
|
use in linker script expressions.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>ABSOLUTE(<var>exp</var>)</code></dt>
|
||
|
|
<dd><a name="index-ABSOLUTE_0028exp_0029"></a>
|
||
|
|
<a name="index-expression_002c-absolute"></a>
|
||
|
|
<p>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. See <a href="Expression-Section.html#Expression-Section">Expression Section</a>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>ADDR(<var>section</var>)</code></dt>
|
||
|
|
<dd><a name="index-ADDR_0028section_0029"></a>
|
||
|
|
<a name="index-section-address-in-expression"></a>
|
||
|
|
<p>Return the address (VMA) of the named <var>section</var>. Your
|
||
|
|
script must previously have defined the location of that section. In
|
||
|
|
the following example, <code>start_of_output_1</code>, <code>symbol_1</code> and
|
||
|
|
<code>symbol_2</code> are assigned equivalent values, except that
|
||
|
|
<code>symbol_1</code> will be relative to the <code>.output1</code> section while
|
||
|
|
the other two will be absolute:
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample">SECTIONS { …
|
||
|
|
.output1 :
|
||
|
|
{
|
||
|
|
start_of_output_1 = ABSOLUTE(.);
|
||
|
|
…
|
||
|
|
}
|
||
|
|
.output :
|
||
|
|
{
|
||
|
|
symbol_1 = ADDR(.output1);
|
||
|
|
symbol_2 = start_of_output_1;
|
||
|
|
}
|
||
|
|
… }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>ALIGN(<var>align</var>)</code></dt>
|
||
|
|
<dt><code>ALIGN(<var>exp</var>,<var>align</var>)</code></dt>
|
||
|
|
<dd><a name="index-ALIGN_0028align_0029"></a>
|
||
|
|
<a name="index-ALIGN_0028exp_002calign_0029"></a>
|
||
|
|
<a name="index-round-up-location-counter"></a>
|
||
|
|
<a name="index-align-location-counter"></a>
|
||
|
|
<a name="index-round-up-expression"></a>
|
||
|
|
<a name="index-align-expression"></a>
|
||
|
|
<p>Return the location counter (<code>.</code>) or arbitrary expression aligned
|
||
|
|
to the next <var>align</var> boundary. The single operand <code>ALIGN</code>
|
||
|
|
doesn’t change the value of the location counter—it just does
|
||
|
|
arithmetic on it. The two operand <code>ALIGN</code> allows an arbitrary
|
||
|
|
expression to be aligned upwards (<code>ALIGN(<var>align</var>)</code> is
|
||
|
|
equivalent to <code>ALIGN(ABSOLUTE(.), <var>align</var>)</code>).
|
||
|
|
</p>
|
||
|
|
<p>Here is an example which aligns the output <code>.data</code> section to the
|
||
|
|
next <code>0x2000</code> byte boundary after the preceding section and sets a
|
||
|
|
variable within the section to the next <code>0x8000</code> boundary after the
|
||
|
|
input sections:
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample">SECTIONS { …
|
||
|
|
.data ALIGN(0x2000): {
|
||
|
|
*(.data)
|
||
|
|
variable = ALIGN(0x8000);
|
||
|
|
}
|
||
|
|
… }
|
||
|
|
</pre></div>
|
||
|
|
<p>The first use of <code>ALIGN</code> in this example specifies the location of
|
||
|
|
a section because it is used as the optional <var>address</var> attribute of
|
||
|
|
a section definition (see <a href="Output-Section-Address.html#Output-Section-Address">Output Section Address</a>). The second use
|
||
|
|
of <code>ALIGN</code> is used to defines the value of a symbol.
|
||
|
|
</p>
|
||
|
|
<p>The builtin function <code>NEXT</code> is closely related to <code>ALIGN</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>ALIGNOF(<var>section</var>)</code></dt>
|
||
|
|
<dd><a name="index-ALIGNOF_0028section_0029"></a>
|
||
|
|
<a name="index-section-alignment"></a>
|
||
|
|
<p>Return the alignment in bytes of the named <var>section</var>, if that section has
|
||
|
|
been allocated. If the section has not been allocated when this is
|
||
|
|
evaluated, the linker will report an error. In the following example,
|
||
|
|
the alignment of the <code>.output</code> section is stored as the first
|
||
|
|
value in that section.
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample">SECTIONS{ …
|
||
|
|
.output {
|
||
|
|
LONG (ALIGNOF (.output))
|
||
|
|
…
|
||
|
|
}
|
||
|
|
… }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>BLOCK(<var>exp</var>)</code></dt>
|
||
|
|
<dd><a name="index-BLOCK_0028exp_0029"></a>
|
||
|
|
<p>This is a synonym for <code>ALIGN</code>, for compatibility with older linker
|
||
|
|
scripts. It is most often seen when setting the address of an output
|
||
|
|
section.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>DATA_SEGMENT_ALIGN(<var>maxpagesize</var>, <var>commonpagesize</var>)</code></dt>
|
||
|
|
<dd><a name="index-DATA_005fSEGMENT_005fALIGN_0028maxpagesize_002c-commonpagesize_0029"></a>
|
||
|
|
<p>This is equivalent to either
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample">(ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - 1)))
|
||
|
|
</pre></div>
|
||
|
|
<p>or
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample">(ALIGN(<var>maxpagesize</var>)
|
||
|
|
+ ((. + <var>commonpagesize</var> - 1) & (<var>maxpagesize</var> - <var>commonpagesize</var>)))
|
||
|
|
</pre></div>
|
||
|
|
<p>depending on whether the latter uses fewer <var>commonpagesize</var> sized pages
|
||
|
|
for the data segment (area between the result of this expression and
|
||
|
|
<code>DATA_SEGMENT_END</code>) than the former or not.
|
||
|
|
If the latter form is used, it means <var>commonpagesize</var> bytes of runtime
|
||
|
|
memory will be saved at the expense of up to <var>commonpagesize</var> wasted
|
||
|
|
bytes in the on-disk file.
|
||
|
|
</p>
|
||
|
|
<p>This expression can only be used directly in <code>SECTIONS</code> commands, not in
|
||
|
|
any output section descriptions and only once in the linker script.
|
||
|
|
<var>commonpagesize</var> should be less or equal to <var>maxpagesize</var> and should
|
||
|
|
be the system page size the object wants to be optimized for while still
|
||
|
|
running on system page sizes up to <var>maxpagesize</var>. Note however
|
||
|
|
that ‘<samp>-z relro</samp>’ protection will not be effective if the system
|
||
|
|
page size is larger than <var>commonpagesize</var>.
|
||
|
|
</p>
|
||
|
|
<p>Example:
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample"> . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>DATA_SEGMENT_END(<var>exp</var>)</code></dt>
|
||
|
|
<dd><a name="index-DATA_005fSEGMENT_005fEND_0028exp_0029"></a>
|
||
|
|
<p>This defines the end of data segment for <code>DATA_SEGMENT_ALIGN</code>
|
||
|
|
evaluation purposes.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> . = DATA_SEGMENT_END(.);
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>DATA_SEGMENT_RELRO_END(<var>offset</var>, <var>exp</var>)</code></dt>
|
||
|
|
<dd><a name="index-DATA_005fSEGMENT_005fRELRO_005fEND_0028offset_002c-exp_0029"></a>
|
||
|
|
<p>This defines the end of the <code>PT_GNU_RELRO</code> segment when
|
||
|
|
‘<samp>-z relro</samp>’ option is used.
|
||
|
|
When ‘<samp>-z relro</samp>’ option is not present, <code>DATA_SEGMENT_RELRO_END</code>
|
||
|
|
does nothing, otherwise <code>DATA_SEGMENT_ALIGN</code> is padded so that
|
||
|
|
<var>exp</var> + <var>offset</var> is aligned to the <var>commonpagesize</var>
|
||
|
|
argument given to <code>DATA_SEGMENT_ALIGN</code>. If present in the linker
|
||
|
|
script, it must be placed between <code>DATA_SEGMENT_ALIGN</code> and
|
||
|
|
<code>DATA_SEGMENT_END</code>. Evaluates to the second argument plus any
|
||
|
|
padding needed at the end of the <code>PT_GNU_RELRO</code> segment due to
|
||
|
|
section alignment.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> . = DATA_SEGMENT_RELRO_END(24, .);
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>DEFINED(<var>symbol</var>)</code></dt>
|
||
|
|
<dd><a name="index-DEFINED_0028symbol_0029"></a>
|
||
|
|
<a name="index-symbol-defaults"></a>
|
||
|
|
<p>Return 1 if <var>symbol</var> is in the linker global symbol table and is
|
||
|
|
defined before the statement using DEFINED in the script, otherwise
|
||
|
|
return 0. You can use this function to provide
|
||
|
|
default values for symbols. For example, the following script fragment
|
||
|
|
shows how to set a global symbol ‘<samp>begin</samp>’ to the first location in
|
||
|
|
the ‘<samp>.text</samp>’ section—but if a symbol called ‘<samp>begin</samp>’ already
|
||
|
|
existed, its value is preserved:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">SECTIONS { …
|
||
|
|
.text : {
|
||
|
|
begin = DEFINED(begin) ? begin : . ;
|
||
|
|
…
|
||
|
|
}
|
||
|
|
…
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>LENGTH(<var>memory</var>)</code></dt>
|
||
|
|
<dd><a name="index-LENGTH_0028memory_0029"></a>
|
||
|
|
<p>Return the length of the memory region named <var>memory</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>LOADADDR(<var>section</var>)</code></dt>
|
||
|
|
<dd><a name="index-LOADADDR_0028section_0029"></a>
|
||
|
|
<a name="index-section-load-address-in-expression"></a>
|
||
|
|
<p>Return the absolute LMA of the named <var>section</var>. (see <a href="Output-Section-LMA.html#Output-Section-LMA">Output Section LMA</a>).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>LOG2CEIL(<var>exp</var>)</code></dt>
|
||
|
|
<dd><a name="index-LOG2CEIL_0028exp_0029"></a>
|
||
|
|
<p>Return the binary logarithm of <var>exp</var> rounded towards infinity.
|
||
|
|
<code>LOG2CEIL(0)</code> returns 0.
|
||
|
|
</p>
|
||
|
|
<a name="index-MAX"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>MAX(<var>exp1</var>, <var>exp2</var>)</code></dt>
|
||
|
|
<dd><p>Returns the maximum of <var>exp1</var> and <var>exp2</var>.
|
||
|
|
</p>
|
||
|
|
<a name="index-MIN"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>MIN(<var>exp1</var>, <var>exp2</var>)</code></dt>
|
||
|
|
<dd><p>Returns the minimum of <var>exp1</var> and <var>exp2</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>NEXT(<var>exp</var>)</code></dt>
|
||
|
|
<dd><a name="index-NEXT_0028exp_0029"></a>
|
||
|
|
<a name="index-unallocated-address_002c-next"></a>
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>ORIGIN(<var>memory</var>)</code></dt>
|
||
|
|
<dd><a name="index-ORIGIN_0028memory_0029"></a>
|
||
|
|
<p>Return the origin of the memory region named <var>memory</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>SEGMENT_START(<var>segment</var>, <var>default</var>)</code></dt>
|
||
|
|
<dd><a name="index-SEGMENT_005fSTART_0028segment_002c-default_0029"></a>
|
||
|
|
<p>Return the base address of the named <var>segment</var>. If an explicit
|
||
|
|
value has already been given for this segment (with a command-line
|
||
|
|
‘<samp>-T</samp>’ option) then that value will be returned otherwise the value
|
||
|
|
will be <var>default</var>. At present, the ‘<samp>-T</samp>’ command-line option
|
||
|
|
can only be used to set the base address for the “text”, “data”, and
|
||
|
|
“bss” sections, but you can use <code>SEGMENT_START</code> with any segment
|
||
|
|
name.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>SIZEOF(<var>section</var>)</code></dt>
|
||
|
|
<dd><a name="index-SIZEOF_0028section_0029"></a>
|
||
|
|
<a name="index-section-size"></a>
|
||
|
|
<p>Return the size in bytes of the named <var>section</var>, if that section has
|
||
|
|
been allocated. If the section has not been allocated when this is
|
||
|
|
evaluated, the linker will report an error. In the following example,
|
||
|
|
<code>symbol_1</code> and <code>symbol_2</code> are assigned identical values:
|
||
|
|
</p><div class="smallexample">
|
||
|
|
<pre class="smallexample">SECTIONS{ …
|
||
|
|
.output {
|
||
|
|
.start = . ;
|
||
|
|
…
|
||
|
|
.end = . ;
|
||
|
|
}
|
||
|
|
symbol_1 = .end - .start ;
|
||
|
|
symbol_2 = SIZEOF(.output);
|
||
|
|
… }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>SIZEOF_HEADERS</code></dt>
|
||
|
|
<dt><code>sizeof_headers</code></dt>
|
||
|
|
<dd><a name="index-SIZEOF_005fHEADERS"></a>
|
||
|
|
<a name="index-header-size"></a>
|
||
|
|
<p>Return the size in bytes of the output file’s headers. This is
|
||
|
|
information which appears at the start of the output file. You can use
|
||
|
|
this number when setting the start address of the first section, if you
|
||
|
|
choose, to facilitate paging.
|
||
|
|
</p>
|
||
|
|
<a name="index-not-enough-room-for-program-headers"></a>
|
||
|
|
<a name="index-program-headers_002c-not-enough-room"></a>
|
||
|
|
<p>When producing an ELF output file, if the linker script uses the
|
||
|
|
<code>SIZEOF_HEADERS</code> builtin function, the linker must compute the
|
||
|
|
number of program headers before it has determined all the section
|
||
|
|
addresses and sizes. If the linker later discovers that it needs
|
||
|
|
additional program headers, it will report an error ‘<samp>not enough
|
||
|
|
room for program headers</samp>’. To avoid this error, you must avoid using
|
||
|
|
the <code>SIZEOF_HEADERS</code> function, or you must rework your linker
|
||
|
|
script to avoid forcing the linker to use additional program headers, or
|
||
|
|
you must define the program headers yourself using the <code>PHDRS</code>
|
||
|
|
command (see <a href="PHDRS.html#PHDRS">PHDRS</a>).
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Previous: <a href="Expression-Section.html#Expression-Section" accesskey="p" rel="prev">Expression Section</a>, Up: <a href="Expressions.html#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|