1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- This file documents the GNU linker LD 4(GNU Toolchain for the A-profile Architecture 10.3-2021.07 (arm-10.29)) 5version 2.36.1. 6 7Copyright (C) 1991-2021 Free Software Foundation, Inc. 8 9Permission is granted to copy, distribute and/or modify this document 10under the terms of the GNU Free Documentation License, Version 1.3 11or any later version published by the Free Software Foundation; 12with no Invariant Sections, with no Front-Cover Texts, and with no 13Back-Cover Texts. A copy of the license is included in the 14section entitled "GNU Free Documentation License". --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>LD: Builtin Functions</title> 18 19<meta name="description" content="LD: Builtin Functions"> 20<meta name="keywords" content="LD: Builtin Functions"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="LD-Index.html#LD-Index" rel="index" title="LD Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Expressions.html#Expressions" rel="up" title="Expressions"> 29<link href="Implicit-Linker-Scripts.html#Implicit-Linker-Scripts" rel="next" title="Implicit Linker Scripts"> 30<link href="Expression-Section.html#Expression-Section" rel="previous" title="Expression Section"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Builtin-Functions"></a> 65<div class="header"> 66<p> 67Previous: <a href="Expression-Section.html#Expression-Section" accesskey="p" rel="previous">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> 68</div> 69<hr> 70<a name="Builtin-Functions-1"></a> 71<h4 class="subsection">3.10.9 Builtin Functions</h4> 72<a name="index-functions-in-expressions"></a> 73<p>The linker script language includes a number of builtin functions for 74use in linker script expressions. 75</p> 76<dl compact="compact"> 77<dt><code>ABSOLUTE(<var>exp</var>)</code></dt> 78<dd><a name="index-ABSOLUTE_0028exp_0029"></a> 79<a name="index-expression_002c-absolute"></a> 80<p>Return the absolute (non-relocatable, as opposed to non-negative) value 81of the expression <var>exp</var>. Primarily useful to assign an absolute 82value to a symbol within a section definition, where symbol values are 83normally section relative. See <a href="Expression-Section.html#Expression-Section">Expression Section</a>. 84</p> 85</dd> 86<dt><code>ADDR(<var>section</var>)</code></dt> 87<dd><a name="index-ADDR_0028section_0029"></a> 88<a name="index-section-address-in-expression"></a> 89<p>Return the address (VMA) of the named <var>section</var>. Your 90script must previously have defined the location of that section. In 91the following example, <code>start_of_output_1</code>, <code>symbol_1</code> and 92<code>symbol_2</code> are assigned equivalent values, except that 93<code>symbol_1</code> will be relative to the <code>.output1</code> section while 94the other two will be absolute: 95</p><div class="smallexample"> 96<pre class="smallexample">SECTIONS { … 97 .output1 : 98 { 99 start_of_output_1 = ABSOLUTE(.); 100 … 101 } 102 .output : 103 { 104 symbol_1 = ADDR(.output1); 105 symbol_2 = start_of_output_1; 106 } 107… } 108</pre></div> 109 110</dd> 111<dt><code>ALIGN(<var>align</var>)</code></dt> 112<dt><code>ALIGN(<var>exp</var>,<var>align</var>)</code></dt> 113<dd><a name="index-ALIGN_0028align_0029"></a> 114<a name="index-ALIGN_0028exp_002calign_0029"></a> 115<a name="index-round-up-location-counter"></a> 116<a name="index-align-location-counter"></a> 117<a name="index-round-up-expression"></a> 118<a name="index-align-expression"></a> 119<p>Return the location counter (<code>.</code>) or arbitrary expression aligned 120to the next <var>align</var> boundary. The single operand <code>ALIGN</code> 121doesn’t change the value of the location counter—it just does 122arithmetic on it. The two operand <code>ALIGN</code> allows an arbitrary 123expression to be aligned upwards (<code>ALIGN(<var>align</var>)</code> is 124equivalent to <code>ALIGN(ABSOLUTE(.), <var>align</var>)</code>). 125</p> 126<p>Here is an example which aligns the output <code>.data</code> section to the 127next <code>0x2000</code> byte boundary after the preceding section and sets a 128variable within the section to the next <code>0x8000</code> boundary after the 129input sections: 130</p><div class="smallexample"> 131<pre class="smallexample">SECTIONS { … 132 .data ALIGN(0x2000): { 133 *(.data) 134 variable = ALIGN(0x8000); 135 } 136… } 137</pre></div> 138<p>The first use of <code>ALIGN</code> in this example specifies the location of 139a section because it is used as the optional <var>address</var> attribute of 140a section definition (see <a href="Output-Section-Address.html#Output-Section-Address">Output Section Address</a>). The second use 141of <code>ALIGN</code> is used to defines the value of a symbol. 142</p> 143<p>The builtin function <code>NEXT</code> is closely related to <code>ALIGN</code>. 144</p> 145</dd> 146<dt><code>ALIGNOF(<var>section</var>)</code></dt> 147<dd><a name="index-ALIGNOF_0028section_0029"></a> 148<a name="index-section-alignment"></a> 149<p>Return the alignment in bytes of the named <var>section</var>, if that section has 150been allocated. If the section has not been allocated when this is 151evaluated, the linker will report an error. In the following example, 152the alignment of the <code>.output</code> section is stored as the first 153value in that section. 154</p><div class="smallexample"> 155<pre class="smallexample">SECTIONS{ … 156 .output { 157 LONG (ALIGNOF (.output)) 158 … 159 } 160… } 161</pre></div> 162 163</dd> 164<dt><code>BLOCK(<var>exp</var>)</code></dt> 165<dd><a name="index-BLOCK_0028exp_0029"></a> 166<p>This is a synonym for <code>ALIGN</code>, for compatibility with older linker 167scripts. It is most often seen when setting the address of an output 168section. 169</p> 170</dd> 171<dt><code>DATA_SEGMENT_ALIGN(<var>maxpagesize</var>, <var>commonpagesize</var>)</code></dt> 172<dd><a name="index-DATA_005fSEGMENT_005fALIGN_0028maxpagesize_002c-commonpagesize_0029"></a> 173<p>This is equivalent to either 174</p><div class="smallexample"> 175<pre class="smallexample">(ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - 1))) 176</pre></div> 177<p>or 178</p><div class="smallexample"> 179<pre class="smallexample">(ALIGN(<var>maxpagesize</var>) 180 + ((. + <var>commonpagesize</var> - 1) & (<var>maxpagesize</var> - <var>commonpagesize</var>))) 181</pre></div> 182<p>depending on whether the latter uses fewer <var>commonpagesize</var> sized pages 183for the data segment (area between the result of this expression and 184<code>DATA_SEGMENT_END</code>) than the former or not. 185If the latter form is used, it means <var>commonpagesize</var> bytes of runtime 186memory will be saved at the expense of up to <var>commonpagesize</var> wasted 187bytes in the on-disk file. 188</p> 189<p>This expression can only be used directly in <code>SECTIONS</code> commands, not in 190any output section descriptions and only once in the linker script. 191<var>commonpagesize</var> should be less or equal to <var>maxpagesize</var> and should 192be the system page size the object wants to be optimized for while still 193running on system page sizes up to <var>maxpagesize</var>. Note however 194that ‘<samp>-z relro</samp>’ protection will not be effective if the system 195page size is larger than <var>commonpagesize</var>. 196</p> 197<p>Example: 198</p><div class="smallexample"> 199<pre class="smallexample"> . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); 200</pre></div> 201 202</dd> 203<dt><code>DATA_SEGMENT_END(<var>exp</var>)</code></dt> 204<dd><a name="index-DATA_005fSEGMENT_005fEND_0028exp_0029"></a> 205<p>This defines the end of data segment for <code>DATA_SEGMENT_ALIGN</code> 206evaluation purposes. 207</p> 208<div class="smallexample"> 209<pre class="smallexample"> . = DATA_SEGMENT_END(.); 210</pre></div> 211 212</dd> 213<dt><code>DATA_SEGMENT_RELRO_END(<var>offset</var>, <var>exp</var>)</code></dt> 214<dd><a name="index-DATA_005fSEGMENT_005fRELRO_005fEND_0028offset_002c-exp_0029"></a> 215<p>This defines the end of the <code>PT_GNU_RELRO</code> segment when 216‘<samp>-z relro</samp>’ option is used. 217When ‘<samp>-z relro</samp>’ option is not present, <code>DATA_SEGMENT_RELRO_END</code> 218does nothing, otherwise <code>DATA_SEGMENT_ALIGN</code> is padded so that 219<var>exp</var> + <var>offset</var> is aligned to the <var>commonpagesize</var> 220argument given to <code>DATA_SEGMENT_ALIGN</code>. If present in the linker 221script, it must be placed between <code>DATA_SEGMENT_ALIGN</code> and 222<code>DATA_SEGMENT_END</code>. Evaluates to the second argument plus any 223padding needed at the end of the <code>PT_GNU_RELRO</code> segment due to 224section alignment. 225</p> 226<div class="smallexample"> 227<pre class="smallexample"> . = DATA_SEGMENT_RELRO_END(24, .); 228</pre></div> 229 230</dd> 231<dt><code>DEFINED(<var>symbol</var>)</code></dt> 232<dd><a name="index-DEFINED_0028symbol_0029"></a> 233<a name="index-symbol-defaults"></a> 234<p>Return 1 if <var>symbol</var> is in the linker global symbol table and is 235defined before the statement using DEFINED in the script, otherwise 236return 0. You can use this function to provide 237default values for symbols. For example, the following script fragment 238shows how to set a global symbol ‘<samp>begin</samp>’ to the first location in 239the ‘<samp>.text</samp>’ section—but if a symbol called ‘<samp>begin</samp>’ already 240existed, its value is preserved: 241</p> 242<div class="smallexample"> 243<pre class="smallexample">SECTIONS { … 244 .text : { 245 begin = DEFINED(begin) ? begin : . ; 246 … 247 } 248 … 249} 250</pre></div> 251 252</dd> 253<dt><code>LENGTH(<var>memory</var>)</code></dt> 254<dd><a name="index-LENGTH_0028memory_0029"></a> 255<p>Return the length of the memory region named <var>memory</var>. 256</p> 257</dd> 258<dt><code>LOADADDR(<var>section</var>)</code></dt> 259<dd><a name="index-LOADADDR_0028section_0029"></a> 260<a name="index-section-load-address-in-expression"></a> 261<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>). 262</p> 263</dd> 264<dt><code>LOG2CEIL(<var>exp</var>)</code></dt> 265<dd><a name="index-LOG2CEIL_0028exp_0029"></a> 266<p>Return the binary logarithm of <var>exp</var> rounded towards infinity. 267<code>LOG2CEIL(0)</code> returns 0. 268</p> 269<a name="index-MAX"></a> 270</dd> 271<dt><code>MAX(<var>exp1</var>, <var>exp2</var>)</code></dt> 272<dd><p>Returns the maximum of <var>exp1</var> and <var>exp2</var>. 273</p> 274<a name="index-MIN"></a> 275</dd> 276<dt><code>MIN(<var>exp1</var>, <var>exp2</var>)</code></dt> 277<dd><p>Returns the minimum of <var>exp1</var> and <var>exp2</var>. 278</p> 279</dd> 280<dt><code>NEXT(<var>exp</var>)</code></dt> 281<dd><a name="index-NEXT_0028exp_0029"></a> 282<a name="index-unallocated-address_002c-next"></a> 283<p>Return the next unallocated address that is a multiple of <var>exp</var>. 284This function is closely related to <code>ALIGN(<var>exp</var>)</code>; unless you 285use the <code>MEMORY</code> command to define discontinuous memory for the 286output file, the two functions are equivalent. 287</p> 288</dd> 289<dt><code>ORIGIN(<var>memory</var>)</code></dt> 290<dd><a name="index-ORIGIN_0028memory_0029"></a> 291<p>Return the origin of the memory region named <var>memory</var>. 292</p> 293</dd> 294<dt><code>SEGMENT_START(<var>segment</var>, <var>default</var>)</code></dt> 295<dd><a name="index-SEGMENT_005fSTART_0028segment_002c-default_0029"></a> 296<p>Return the base address of the named <var>segment</var>. If an explicit 297value has already been given for this segment (with a command-line 298‘<samp>-T</samp>’ option) then that value will be returned otherwise the value 299will be <var>default</var>. At present, the ‘<samp>-T</samp>’ command-line option 300can only be used to set the base address for the “text”, “data”, and 301“bss” sections, but you can use <code>SEGMENT_START</code> with any segment 302name. 303</p> 304</dd> 305<dt><code>SIZEOF(<var>section</var>)</code></dt> 306<dd><a name="index-SIZEOF_0028section_0029"></a> 307<a name="index-section-size"></a> 308<p>Return the size in bytes of the named <var>section</var>, if that section has 309been allocated. If the section has not been allocated when this is 310evaluated, the linker will report an error. In the following example, 311<code>symbol_1</code> and <code>symbol_2</code> are assigned identical values: 312</p><div class="smallexample"> 313<pre class="smallexample">SECTIONS{ … 314 .output { 315 .start = . ; 316 … 317 .end = . ; 318 } 319 symbol_1 = .end - .start ; 320 symbol_2 = SIZEOF(.output); 321… } 322</pre></div> 323 324</dd> 325<dt><code>SIZEOF_HEADERS</code></dt> 326<dt><code>sizeof_headers</code></dt> 327<dd><a name="index-SIZEOF_005fHEADERS"></a> 328<a name="index-header-size"></a> 329<p>Return the size in bytes of the output file’s headers. This is 330information which appears at the start of the output file. You can use 331this number when setting the start address of the first section, if you 332choose, to facilitate paging. 333</p> 334<a name="index-not-enough-room-for-program-headers"></a> 335<a name="index-program-headers_002c-not-enough-room"></a> 336<p>When producing an ELF output file, if the linker script uses the 337<code>SIZEOF_HEADERS</code> builtin function, the linker must compute the 338number of program headers before it has determined all the section 339addresses and sizes. If the linker later discovers that it needs 340additional program headers, it will report an error ‘<samp>not enough 341room for program headers</samp>’. To avoid this error, you must avoid using 342the <code>SIZEOF_HEADERS</code> function, or you must rework your linker 343script to avoid forcing the linker to use additional program headers, or 344you must define the program headers yourself using the <code>PHDRS</code> 345command (see <a href="PHDRS.html#PHDRS">PHDRS</a>). 346</p></dd> 347</dl> 348 349<hr> 350<div class="header"> 351<p> 352Previous: <a href="Expression-Section.html#Expression-Section" accesskey="p" rel="previous">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> 353</div> 354 355 356 357</body> 358</html> 359