1<html lang="en"> 2<head> 3<title>Overlay Description - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="SECTIONS.html#SECTIONS" title="SECTIONS"> 9<link rel="prev" href="Output-Section-Attributes.html#Output-Section-Attributes" title="Output Section Attributes"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12This file documents the GNU linker LD 13(Sourcery CodeBench Lite 2011.09-69) 14version 2.21.53. 15 16Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 172001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. 18 19Permission is granted to copy, distribute and/or modify this document 20under the terms of the GNU Free Documentation License, Version 1.3 21or any later version published by the Free Software Foundation; 22with no Invariant Sections, with no Front-Cover Texts, and with no 23Back-Cover Texts. A copy of the license is included in the 24section entitled ``GNU Free Documentation License''.--> 25<meta http-equiv="Content-Style-Type" content="text/css"> 26<style type="text/css"><!-- 27 pre.display { font-family:inherit } 28 pre.format { font-family:inherit } 29 pre.smalldisplay { font-family:inherit; font-size:smaller } 30 pre.smallformat { font-family:inherit; font-size:smaller } 31 pre.smallexample { font-size:smaller } 32 pre.smalllisp { font-size:smaller } 33 span.sc { font-variant:small-caps } 34 span.roman { font-family:serif; font-weight:normal; } 35 span.sansserif { font-family:sans-serif; font-weight:normal; } 36--></style> 37<link rel="stylesheet" type="text/css" href="../cs.css"> 38</head> 39<body> 40<div class="node"> 41<a name="Overlay-Description"></a> 42<p> 43Previous: <a rel="previous" accesskey="p" href="Output-Section-Attributes.html#Output-Section-Attributes">Output Section Attributes</a>, 44Up: <a rel="up" accesskey="u" href="SECTIONS.html#SECTIONS">SECTIONS</a> 45<hr> 46</div> 47 48<h4 class="subsection">3.6.9 Overlay Description</h4> 49 50<p><a name="index-OVERLAY-472"></a><a name="index-overlays-473"></a>An overlay description provides an easy way to describe sections which 51are to be loaded as part of a single memory image but are to be run at 52the same memory address. At run time, some sort of overlay manager will 53copy the overlaid sections in and out of the runtime memory address as 54required, perhaps by simply manipulating addressing bits. This approach 55can be useful, for example, when a certain region of memory is faster 56than another. 57 58 <p>Overlays are described using the <code>OVERLAY</code> command. The 59<code>OVERLAY</code> command is used within a <code>SECTIONS</code> command, like an 60output section description. The full syntax of the <code>OVERLAY</code> 61command is as follows: 62<pre class="smallexample"> OVERLAY [<var>start</var>] : [NOCROSSREFS] [AT ( <var>ldaddr</var> )] 63 { 64 <var>secname1</var> 65 { 66 <var>output-section-command</var> 67 <var>output-section-command</var> 68 ... 69 } [:<var>phdr</var>...] [=<var>fill</var>] 70 <var>secname2</var> 71 { 72 <var>output-section-command</var> 73 <var>output-section-command</var> 74 ... 75 } [:<var>phdr</var>...] [=<var>fill</var>] 76 ... 77 } [><var>region</var>] [:<var>phdr</var>...] [=<var>fill</var>] 78</pre> 79 <p>Everything is optional except <code>OVERLAY</code> (a keyword), and each 80section must have a name (<var>secname1</var> and <var>secname2</var> above). The 81section definitions within the <code>OVERLAY</code> construct are identical to 82those within the general <code>SECTIONS</code> contruct (see <a href="SECTIONS.html#SECTIONS">SECTIONS</a>), 83except that no addresses and no memory regions may be defined for 84sections within an <code>OVERLAY</code>. 85 86 <p>The sections are all defined with the same starting address. The load 87addresses of the sections are arranged such that they are consecutive in 88memory starting at the load address used for the <code>OVERLAY</code> as a 89whole (as with normal section definitions, the load address is optional, 90and defaults to the start address; the start address is also optional, 91and defaults to the current value of the location counter). 92 93 <p>If the <code>NOCROSSREFS</code> keyword is used, and there any references 94among the sections, the linker will report an error. Since the sections 95all run at the same address, it normally does not make sense for one 96section to refer directly to another. See <a href="Miscellaneous-Commands.html#Miscellaneous-Commands">NOCROSSREFS</a>. 97 98 <p>For each section within the <code>OVERLAY</code>, the linker automatically 99provides two symbols. The symbol <code>__load_start_</code><var>secname</var> is 100defined as the starting load address of the section. The symbol 101<code>__load_stop_</code><var>secname</var> is defined as the final load address of 102the section. Any characters within <var>secname</var> which are not legal 103within C identifiers are removed. C (or assembler) code may use these 104symbols to move the overlaid sections around as necessary. 105 106 <p>At the end of the overlay, the value of the location counter is set to 107the start address of the overlay plus the size of the largest section. 108 109 <p>Here is an example. Remember that this would appear inside a 110<code>SECTIONS</code> construct. 111<pre class="smallexample"> OVERLAY 0x1000 : AT (0x4000) 112 { 113 .text0 { o1/*.o(.text) } 114 .text1 { o2/*.o(.text) } 115 } 116</pre> 117 <p class="noindent">This will define both ‘<samp><span class="samp">.text0</span></samp>’ and ‘<samp><span class="samp">.text1</span></samp>’ to start at 118address 0x1000. ‘<samp><span class="samp">.text0</span></samp>’ will be loaded at address 0x4000, and 119‘<samp><span class="samp">.text1</span></samp>’ will be loaded immediately after ‘<samp><span class="samp">.text0</span></samp>’. The 120following symbols will be defined if referenced: <code>__load_start_text0</code>, 121<code>__load_stop_text0</code>, <code>__load_start_text1</code>, 122<code>__load_stop_text1</code>. 123 124 <p>C code to copy overlay <code>.text1</code> into the overlay area might look 125like the following. 126 127<pre class="smallexample"> extern char __load_start_text1, __load_stop_text1; 128 memcpy ((char *) 0x1000, &__load_start_text1, 129 &__load_stop_text1 - &__load_start_text1); 130</pre> 131 <p>Note that the <code>OVERLAY</code> command is just syntactic sugar, since 132everything it does can be done using the more basic commands. The above 133example could have been written identically as follows. 134 135<pre class="smallexample"> .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } 136 PROVIDE (__load_start_text0 = LOADADDR (.text0)); 137 PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); 138 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } 139 PROVIDE (__load_start_text1 = LOADADDR (.text1)); 140 PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); 141 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); 142</pre> 143 </body></html> 144 145