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: Overlay Description</title> 18 19<meta name="description" content="LD: Overlay Description"> 20<meta name="keywords" content="LD: Overlay Description"> 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="SECTIONS.html#SECTIONS" rel="up" title="SECTIONS"> 29<link href="MEMORY.html#MEMORY" rel="next" title="MEMORY"> 30<link href="Output-Section-Fill.html#Output-Section-Fill" rel="previous" title="Output Section Fill"> 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="Overlay-Description"></a> 65<div class="header"> 66<p> 67Previous: <a href="Output-Section-Attributes.html#Output-Section-Attributes" accesskey="p" rel="previous">Output Section Attributes</a>, Up: <a href="SECTIONS.html#SECTIONS" accesskey="u" rel="up">SECTIONS</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="Overlay-Description-1"></a> 71<h4 class="subsection">3.6.9 Overlay Description</h4> 72<a name="index-OVERLAY"></a> 73<a name="index-overlays"></a> 74<p>An overlay description provides an easy way to describe sections which 75are to be loaded as part of a single memory image but are to be run at 76the same memory address. At run time, some sort of overlay manager will 77copy the overlaid sections in and out of the runtime memory address as 78required, perhaps by simply manipulating addressing bits. This approach 79can be useful, for example, when a certain region of memory is faster 80than another. 81</p> 82<p>Overlays are described using the <code>OVERLAY</code> command. The 83<code>OVERLAY</code> command is used within a <code>SECTIONS</code> command, like an 84output section description. The full syntax of the <code>OVERLAY</code> 85command is as follows: 86</p><div class="smallexample"> 87<pre class="smallexample">OVERLAY [<var>start</var>] : [NOCROSSREFS] [AT ( <var>ldaddr</var> )] 88 { 89 <var>secname1</var> 90 { 91 <var>output-section-command</var> 92 <var>output-section-command</var> 93 … 94 } [:<var>phdr</var>…] [=<var>fill</var>] 95 <var>secname2</var> 96 { 97 <var>output-section-command</var> 98 <var>output-section-command</var> 99 … 100 } [:<var>phdr</var>…] [=<var>fill</var>] 101 … 102 } [><var>region</var>] [:<var>phdr</var>…] [=<var>fill</var>] [,] 103</pre></div> 104 105<p>Everything is optional except <code>OVERLAY</code> (a keyword), and each 106section must have a name (<var>secname1</var> and <var>secname2</var> above). The 107section definitions within the <code>OVERLAY</code> construct are identical to 108those within the general <code>SECTIONS</code> construct (see <a href="SECTIONS.html#SECTIONS">SECTIONS</a>), 109except that no addresses and no memory regions may be defined for 110sections within an <code>OVERLAY</code>. 111</p> 112<p>The comma at the end may be required if a <var>fill</var> is used and 113the next <var>sections-command</var> looks like a continuation of the expression. 114</p> 115<p>The sections are all defined with the same starting address. The load 116addresses of the sections are arranged such that they are consecutive in 117memory starting at the load address used for the <code>OVERLAY</code> as a 118whole (as with normal section definitions, the load address is optional, 119and defaults to the start address; the start address is also optional, 120and defaults to the current value of the location counter). 121</p> 122<p>If the <code>NOCROSSREFS</code> keyword is used, and there are any 123references among the sections, the linker will report an error. Since 124the sections all run at the same address, it normally does not make 125sense for one section to refer directly to another. 126See <a href="Miscellaneous-Commands.html#Miscellaneous-Commands">NOCROSSREFS</a>. 127</p> 128<p>For each section within the <code>OVERLAY</code>, the linker automatically 129provides two symbols. The symbol <code>__load_start_<var>secname</var></code> is 130defined as the starting load address of the section. The symbol 131<code>__load_stop_<var>secname</var></code> is defined as the final load address of 132the section. Any characters within <var>secname</var> which are not legal 133within C identifiers are removed. C (or assembler) code may use these 134symbols to move the overlaid sections around as necessary. 135</p> 136<p>At the end of the overlay, the value of the location counter is set to 137the start address of the overlay plus the size of the largest section. 138</p> 139<p>Here is an example. Remember that this would appear inside a 140<code>SECTIONS</code> construct. 141</p><div class="smallexample"> 142<pre class="smallexample"> OVERLAY 0x1000 : AT (0x4000) 143 { 144 .text0 { o1/*.o(.text) } 145 .text1 { o2/*.o(.text) } 146 } 147</pre></div> 148<p>This will define both ‘<samp>.text0</samp>’ and ‘<samp>.text1</samp>’ to start at 149address 0x1000. ‘<samp>.text0</samp>’ will be loaded at address 0x4000, and 150‘<samp>.text1</samp>’ will be loaded immediately after ‘<samp>.text0</samp>’. The 151following symbols will be defined if referenced: <code>__load_start_text0</code>, 152<code>__load_stop_text0</code>, <code>__load_start_text1</code>, 153<code>__load_stop_text1</code>. 154</p> 155<p>C code to copy overlay <code>.text1</code> into the overlay area might look 156like the following. 157</p> 158<div class="smallexample"> 159<pre class="smallexample"> extern char __load_start_text1, __load_stop_text1; 160 memcpy ((char *) 0x1000, &__load_start_text1, 161 &__load_stop_text1 - &__load_start_text1); 162</pre></div> 163 164<p>Note that the <code>OVERLAY</code> command is just syntactic sugar, since 165everything it does can be done using the more basic commands. The above 166example could have been written identically as follows. 167</p> 168<div class="smallexample"> 169<pre class="smallexample"> .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } 170 PROVIDE (__load_start_text0 = LOADADDR (.text0)); 171 PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); 172 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } 173 PROVIDE (__load_start_text1 = LOADADDR (.text1)); 174 PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); 175 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); 176</pre></div> 177 178<hr> 179<div class="header"> 180<p> 181Previous: <a href="Output-Section-Attributes.html#Output-Section-Attributes" accesskey="p" rel="previous">Output Section Attributes</a>, Up: <a href="SECTIONS.html#SECTIONS" accesskey="u" rel="up">SECTIONS</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> 182</div> 183 184 185 186</body> 187</html> 188