V3s_Allwinner
/
toolchain
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
toolchain/gcc-linaro-6.3.1-2017.02-x8.../share/doc/ld.html/Builtin-Functions.html

357 lines
15 KiB
HTML
Raw Normal View History

1
2024-03-22 05:10:17 +00:00
<!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
(Linaro_Binutils-2017.02)
version 2.27.0.
Copyright (C) 1991-2016 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 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>LD: Builtin Functions</title>
<meta name="description" content="LD: Builtin Functions">
<meta name="keywords" content="LD: Builtin Functions">
<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.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
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.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<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> &nbsp; [<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 { &hellip;
.output1 :
{
start_of_output_1 = ABSOLUTE(.);
&hellip;
}
.output :
{
symbol_1 = ADDR(.output1);
symbol_2 = start_of_output_1;
}
&hellip; }
</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&rsquo;t change the value of the location counter&mdash;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 { &hellip;
.data ALIGN(0x2000): {
*(.data)
variable = ALIGN(0x8000);
}
&hellip; }
</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{ &hellip;
.output {
LONG (ALIGNOF (.output))
&hellip;
}
&hellip; }
</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>) + (. &amp; (<var>maxpagesize</var> - 1)))
</pre></div>
<p>or
</p><div class="smallexample">
<pre class="smallexample">(ALIGN(<var>maxpagesize</var>)
+ ((. + <var>commonpagesize</var> - 1) &amp; (<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
working on system page sizes up to <var>maxpagesize</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
&lsquo;<samp>-z relro</samp>&rsquo; option is used.
When &lsquo;<samp>-z relro</samp>&rsquo; 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 most commonly used page
boundary for particular target. If present in the linker script,
it must always come in 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 &lsquo;<samp>begin</samp>&rsquo; to the first location in
the &lsquo;<samp>.text</samp>&rsquo; section&mdash;but if a symbol called &lsquo;<samp>begin</samp>&rsquo; already
existed, its value is preserved:
</p>
<div class="smallexample">
<pre class="smallexample">SECTIONS { &hellip;
.text : {
begin = DEFINED(begin) ? begin : . ;
&hellip;
}
&hellip;
}
</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
&lsquo;<samp>-T</samp>&rsquo; option) then that value will be returned otherwise the value
will be <var>default</var>. At present, the &lsquo;<samp>-T</samp>&rsquo; command-line option
can only be used to set the base address for the &ldquo;text&rdquo;, &ldquo;data&rdquo;, and
&ldquo;bss&rdquo; 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{ &hellip;
.output {
.start = . ;
&hellip;
.end = . ;
}
symbol_1 = .end - .start ;
symbol_2 = SIZEOF(.output);
&hellip; }
</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&rsquo;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 &lsquo;<samp>not enough
room for program headers</samp>&rsquo;. 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> &nbsp; [<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>