arduino-0018-windows
This commit is contained in:
parent
157fd6f1a1
commit
f39fc49523
5182 changed files with 950586 additions and 0 deletions
|
|
@ -0,0 +1,225 @@
|
|||
<html lang="en">
|
||||
<head>
|
||||
<title>Builtin Functions - Untitled</title>
|
||||
<meta http-equiv="Content-Type" content="text/html">
|
||||
<meta name="description" content="Untitled">
|
||||
<meta name="generator" content="makeinfo 4.7">
|
||||
<link title="Top" rel="start" href="index.html#Top">
|
||||
<link rel="up" href="Expressions.html#Expressions" title="Expressions">
|
||||
<link rel="prev" href="Expression-Section.html#Expression-Section" title="Expression Section">
|
||||
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||||
<!--
|
||||
This file documents the GNU linker LD
|
||||
(GNU Binutils)
|
||||
version 2.19.
|
||||
|
||||
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
|
||||
2001, 2002, 2003, 2004, 2005, 2006, 2007 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.1
|
||||
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''.-->
|
||||
<meta http-equiv="Content-Style-Type" content="text/css">
|
||||
<style type="text/css"><!--
|
||||
pre.display { font-family:inherit }
|
||||
pre.format { font-family:inherit }
|
||||
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||||
pre.smallformat { font-family:inherit; font-size:smaller }
|
||||
pre.smallexample { font-size:smaller }
|
||||
pre.smalllisp { font-size:smaller }
|
||||
span.sc { font-variant:small-caps }
|
||||
span.roman { font-family: serif; font-weight: normal; }
|
||||
--></style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="node">
|
||||
<p>
|
||||
<a name="Builtin-Functions"></a>Previous: <a rel="previous" accesskey="p" href="Expression-Section.html#Expression-Section">Expression Section</a>,
|
||||
Up: <a rel="up" accesskey="u" href="Expressions.html#Expressions">Expressions</a>
|
||||
<hr><br>
|
||||
</div>
|
||||
|
||||
<h4 class="subsection">3.10.8 Builtin Functions</h4>
|
||||
|
||||
<p><a name="index-functions-in-expressions-486"></a>The linker script language includes a number of builtin functions for
|
||||
use in linker script expressions.
|
||||
|
||||
<dl>
|
||||
<dt><code>ABSOLUTE(</code><var>exp</var><code>)</code><dd><a name="index-ABSOLUTE_0028_0040var_007bexp_007d_0029-487"></a><a name="index-expression_002c-absolute-488"></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. See <a href="Expression-Section.html#Expression-Section">Expression Section</a>.
|
||||
|
||||
<br><dt><code>ADDR(</code><var>section</var><code>)</code><dd><a name="index-ADDR_0028_0040var_007bsection_007d_0029-489"></a><a name="index-section-address-in-expression-490"></a>Return the absolute address (the VMA) 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 class="smallexample"> SECTIONS { ...
|
||||
.output1 :
|
||||
{
|
||||
start_of_output_1 = ABSOLUTE(.);
|
||||
...
|
||||
}
|
||||
.output :
|
||||
{
|
||||
symbol_1 = ADDR(.output1);
|
||||
symbol_2 = start_of_output_1;
|
||||
}
|
||||
... }
|
||||
</pre>
|
||||
<br><dt><code>ALIGN(</code><var>align</var><code>)</code><dt><code>ALIGN(</code><var>exp</var><code>,</code><var>align</var><code>)</code><dd><a name="index-ALIGN_0028_0040var_007balign_007d_0029-491"></a><a name="index-ALIGN_0028_0040var_007bexp_007d_002c_0040var_007balign_007d_0029-492"></a><a name="index-round-up-location-counter-493"></a><a name="index-align-location-counter-494"></a><a name="index-round-up-expression-495"></a><a name="index-align-expression-496"></a>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(</code><var>align</var><code>)</code> is
|
||||
equivalent to <code>ALIGN(., </code><var>align</var><code>)</code>).
|
||||
|
||||
<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:
|
||||
<pre class="smallexample"> SECTIONS { ...
|
||||
.data ALIGN(0x2000): {
|
||||
*(.data)
|
||||
variable = ALIGN(0x8000);
|
||||
}
|
||||
... }
|
||||
</pre>
|
||||
<p class="noindent">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>The builtin function <code>NEXT</code> is closely related to <code>ALIGN</code>.
|
||||
|
||||
<br><dt><code>ALIGNOF(</code><var>section</var><code>)</code><dd><a name="index-ALIGNOF_0028_0040var_007bsection_007d_0029-497"></a><a name="index-section-alignment-498"></a>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.
|
||||
<pre class="smallexample"> SECTIONS{ ...
|
||||
.output {
|
||||
LONG (ALIGNOF (.output))
|
||||
...
|
||||
}
|
||||
... }
|
||||
</pre>
|
||||
<br><dt><code>BLOCK(</code><var>exp</var><code>)</code><dd><a name="index-BLOCK_0028_0040var_007bexp_007d_0029-499"></a>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.
|
||||
|
||||
<br><dt><code>DATA_SEGMENT_ALIGN(</code><var>maxpagesize</var><code>, </code><var>commonpagesize</var><code>)</code><dd><a name="index-DATA_005fSEGMENT_005fALIGN_0028_0040var_007bmaxpagesize_007d_002c-_0040var_007bcommonpagesize_007d_0029-500"></a>This is equivalent to either
|
||||
<pre class="smallexample"> (ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - 1)))
|
||||
</pre>
|
||||
<p>or
|
||||
<pre class="smallexample"> (ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - <var>commonpagesize</var>)))
|
||||
</pre>
|
||||
<p class="noindent">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>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 class="noindent">Example:
|
||||
<pre class="smallexample"> . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
|
||||
</pre>
|
||||
<br><dt><code>DATA_SEGMENT_END(</code><var>exp</var><code>)</code><dd><a name="index-DATA_005fSEGMENT_005fEND_0028_0040var_007bexp_007d_0029-501"></a>This defines the end of data segment for <code>DATA_SEGMENT_ALIGN</code>
|
||||
evaluation purposes.
|
||||
|
||||
<pre class="smallexample"> . = DATA_SEGMENT_END(.);
|
||||
</pre>
|
||||
<br><dt><code>DATA_SEGMENT_RELRO_END(</code><var>offset</var><code>, </code><var>exp</var><code>)</code><dd><a name="index-DATA_005fSEGMENT_005fRELRO_005fEND_0028_0040var_007boffset_007d_002c-_0040var_007bexp_007d_0029-502"></a>This defines the end of the <code>PT_GNU_RELRO</code> segment when
|
||||
<span class="samp">-z relro</span> option is used. Second argument is returned.
|
||||
When <span class="samp">-z relro</span> 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>.
|
||||
|
||||
<pre class="smallexample"> . = DATA_SEGMENT_RELRO_END(24, .);
|
||||
</pre>
|
||||
<br><dt><code>DEFINED(</code><var>symbol</var><code>)</code><dd><a name="index-DEFINED_0028_0040var_007bsymbol_007d_0029-503"></a><a name="index-symbol-defaults-504"></a>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 <span class="samp">begin</span> to the first location in
|
||||
the <span class="samp">.text</span> section—but if a symbol called <span class="samp">begin</span> already
|
||||
existed, its value is preserved:
|
||||
|
||||
<pre class="smallexample"> SECTIONS { ...
|
||||
.text : {
|
||||
begin = DEFINED(begin) ? begin : . ;
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
</pre>
|
||||
<br><dt><code>LENGTH(</code><var>memory</var><code>)</code><dd><a name="index-LENGTH_0028_0040var_007bmemory_007d_0029-505"></a>Return the length of the memory region named <var>memory</var>.
|
||||
|
||||
<br><dt><code>LOADADDR(</code><var>section</var><code>)</code><dd><a name="index-LOADADDR_0028_0040var_007bsection_007d_0029-506"></a><a name="index-section-load-address-in-expression-507"></a>Return the absolute LMA 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>
|
||||
attribute is used in the output section definition (see <a href="Output-Section-LMA.html#Output-Section-LMA">Output Section LMA</a>).
|
||||
|
||||
<p><a name="index-MAX-508"></a><br><dt><code>MAX(</code><var>exp1</var><code>, </code><var>exp2</var><code>)</code><dd>Returns the maximum of <var>exp1</var> and <var>exp2</var>.
|
||||
|
||||
<p><a name="index-MIN-509"></a><br><dt><code>MIN(</code><var>exp1</var><code>, </code><var>exp2</var><code>)</code><dd>Returns the minimum of <var>exp1</var> and <var>exp2</var>.
|
||||
|
||||
<br><dt><code>NEXT(</code><var>exp</var><code>)</code><dd><a name="index-NEXT_0028_0040var_007bexp_007d_0029-510"></a><a name="index-unallocated-address_002c-next-511"></a>Return the next unallocated address that is a multiple of <var>exp</var>.
|
||||
This function is closely related to <code>ALIGN(</code><var>exp</var><code>)</code>; unless you
|
||||
use the <code>MEMORY</code> command to define discontinuous memory for the
|
||||
output file, the two functions are equivalent.
|
||||
|
||||
<br><dt><code>ORIGIN(</code><var>memory</var><code>)</code><dd><a name="index-ORIGIN_0028_0040var_007bmemory_007d_0029-512"></a>Return the origin of the memory region named <var>memory</var>.
|
||||
|
||||
<br><dt><code>SEGMENT_START(</code><var>segment</var><code>, </code><var>default</var><code>)</code><dd><a name="index-SEGMENT_005fSTART_0028_0040var_007bsegment_007d_002c-_0040var_007bdefault_007d_0029-513"></a>Return the base address of the named <var>segment</var>. If an explicit
|
||||
value has been given for this segment (with a command-line <span class="samp">-T</span>
|
||||
option) that value will be returned; otherwise the value will be
|
||||
<var>default</var>. At present, the <span class="samp">-T</span> command-line option can only
|
||||
be used to set the base address for the “text”, “data”, and
|
||||
“bss” sections, but you use <code>SEGMENT_START</code> with any segment
|
||||
name.
|
||||
|
||||
<br><dt><code>SIZEOF(</code><var>section</var><code>)</code><dd><a name="index-SIZEOF_0028_0040var_007bsection_007d_0029-514"></a><a name="index-section-size-515"></a>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:
|
||||
<pre class="smallexample"> SECTIONS{ ...
|
||||
.output {
|
||||
.start = . ;
|
||||
...
|
||||
.end = . ;
|
||||
}
|
||||
symbol_1 = .end - .start ;
|
||||
symbol_2 = SIZEOF(.output);
|
||||
... }
|
||||
</pre>
|
||||
<br><dt><code>SIZEOF_HEADERS</code><dt><code>sizeof_headers</code><dd><a name="index-SIZEOF_005fHEADERS-516"></a><a name="index-header-size-517"></a>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-518"></a><a name="index-program-headers_002c-not-enough-room-519"></a>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 <span class="samp">not enough
|
||||
room for program headers</span>. 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>).
|
||||
</dl>
|
||||
|
||||
</body></html>
|
||||
|
||||
Reference in a new issue