1<html lang="en"> 2<head> 3<title>REGION_ALIAS - 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="Simple-Commands.html#Simple-Commands" title="Simple Commands"> 9<link rel="prev" href="Format-Commands.html#Format-Commands" title="Format Commands"> 10<link rel="next" href="Miscellaneous-Commands.html#Miscellaneous-Commands" title="Miscellaneous Commands"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13This file documents the GNU linker LD 14(Sourcery CodeBench Lite 2011.09-69) 15version 2.21.53. 16 17Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 182001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. 19 20Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.3 22or any later version published by the Free Software Foundation; 23with no Invariant Sections, with no Front-Cover Texts, and with no 24Back-Cover Texts. A copy of the license is included in the 25section entitled ``GNU Free Documentation License''.--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="REGION_ALIAS"></a> 43<a name="REGION_005fALIAS"></a> 44<p> 45Next: <a rel="next" accesskey="n" href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>, 46Previous: <a rel="previous" accesskey="p" href="Format-Commands.html#Format-Commands">Format Commands</a>, 47Up: <a rel="up" accesskey="u" href="Simple-Commands.html#Simple-Commands">Simple Commands</a> 48<hr> 49</div> 50 51<h4 class="subsection">3.4.4 Assign alias names to memory regions</h4> 52 53<p><a name="index-REGION_005fALIAS_0028_0040var_007balias_007d_002c-_0040var_007bregion_007d_0029-376"></a><a name="index-region-alias-377"></a><a name="index-region-names-378"></a> 54Alias names can be added to existing memory regions created with the 55<a href="MEMORY.html#MEMORY">MEMORY</a> command. Each name corresponds to at most one memory region. 56 57<pre class="smallexample"> REGION_ALIAS(<var>alias</var>, <var>region</var>) 58</pre> 59 <p>The <code>REGION_ALIAS</code> function creates an alias name <var>alias</var> for the 60memory region <var>region</var>. This allows a flexible mapping of output sections 61to memory regions. An example follows. 62 63 <p>Suppose we have an application for embedded systems which come with various 64memory storage devices. All have a general purpose, volatile memory <code>RAM</code> 65that allows code execution or data storage. Some may have a read-only, 66non-volatile memory <code>ROM</code> that allows code execution and read-only data 67access. The last variant is a read-only, non-volatile memory <code>ROM2</code> with 68read-only data access and no code execution capability. We have four output 69sections: 70 71 <ul> 72<li><code>.text</code> program code; 73<li><code>.rodata</code> read-only data; 74<li><code>.data</code> read-write initialized data; 75<li><code>.bss</code> read-write zero initialized data. 76</ul> 77 78 <p>The goal is to provide a linker command file that contains a system independent 79part defining the output sections and a system dependent part mapping the 80output sections to the memory regions available on the system. Our embedded 81systems come with three different memory setups <code>A</code>, <code>B</code> and 82<code>C</code>: 83 <p><table summary=""><tr align="left"><td valign="top" width="25%">Section </td><td valign="top" width="25%">Variant A </td><td valign="top" width="25%">Variant B </td><td valign="top" width="25%">Variant C 84<br></td></tr><tr align="left"><td valign="top" width="25%">.text </td><td valign="top" width="25%">RAM </td><td valign="top" width="25%">ROM </td><td valign="top" width="25%">ROM 85<br></td></tr><tr align="left"><td valign="top" width="25%">.rodata </td><td valign="top" width="25%">RAM </td><td valign="top" width="25%">ROM </td><td valign="top" width="25%">ROM2 86<br></td></tr><tr align="left"><td valign="top" width="25%">.data </td><td valign="top" width="25%">RAM </td><td valign="top" width="25%">RAM/ROM </td><td valign="top" width="25%">RAM/ROM2 87<br></td></tr><tr align="left"><td valign="top" width="25%">.bss </td><td valign="top" width="25%">RAM </td><td valign="top" width="25%">RAM </td><td valign="top" width="25%">RAM 88 <br></td></tr></table> 89The notation <code>RAM/ROM</code> or <code>RAM/ROM2</code> means that this section is 90loaded into region <code>ROM</code> or <code>ROM2</code> respectively. Please note that 91the load address of the <code>.data</code> section starts in all three variants at 92the end of the <code>.rodata</code> section. 93 94 <p>The base linker script that deals with the output sections follows. It 95includes the system dependent <code>linkcmds.memory</code> file that describes the 96memory layout: 97<pre class="smallexample"> INCLUDE linkcmds.memory 98 99 SECTIONS 100 { 101 .text : 102 { 103 *(.text) 104 } > REGION_TEXT 105 .rodata : 106 { 107 *(.rodata) 108 rodata_end = .; 109 } > REGION_RODATA 110 .data : AT (rodata_end) 111 { 112 data_start = .; 113 *(.data) 114 } > REGION_DATA 115 data_size = SIZEOF(.data); 116 data_load_start = LOADADDR(.data); 117 .bss : 118 { 119 *(.bss) 120 } > REGION_BSS 121 } 122</pre> 123 <p>Now we need three different <code>linkcmds.memory</code> files to define memory 124regions and alias names. The content of <code>linkcmds.memory</code> for the three 125variants <code>A</code>, <code>B</code> and <code>C</code>: 126 <dl> 127<dt><code>A</code><dd>Here everything goes into the <code>RAM</code>. 128 <pre class="smallexample"> MEMORY 129 { 130 RAM : ORIGIN = 0, LENGTH = 4M 131 } 132 133 REGION_ALIAS("REGION_TEXT", RAM); 134 REGION_ALIAS("REGION_RODATA", RAM); 135 REGION_ALIAS("REGION_DATA", RAM); 136 REGION_ALIAS("REGION_BSS", RAM); 137</pre> 138 <br><dt><code>B</code><dd>Program code and read-only data go into the <code>ROM</code>. Read-write data goes 139into the <code>RAM</code>. An image of the initialized data is loaded into the 140<code>ROM</code> and will be copied during system start into the <code>RAM</code>. 141 <pre class="smallexample"> MEMORY 142 { 143 ROM : ORIGIN = 0, LENGTH = 3M 144 RAM : ORIGIN = 0x10000000, LENGTH = 1M 145 } 146 147 REGION_ALIAS("REGION_TEXT", ROM); 148 REGION_ALIAS("REGION_RODATA", ROM); 149 REGION_ALIAS("REGION_DATA", RAM); 150 REGION_ALIAS("REGION_BSS", RAM); 151</pre> 152 <br><dt><code>C</code><dd>Program code goes into the <code>ROM</code>. Read-only data goes into the 153<code>ROM2</code>. Read-write data goes into the <code>RAM</code>. An image of the 154initialized data is loaded into the <code>ROM2</code> and will be copied during 155system start into the <code>RAM</code>. 156 <pre class="smallexample"> MEMORY 157 { 158 ROM : ORIGIN = 0, LENGTH = 2M 159 ROM2 : ORIGIN = 0x10000000, LENGTH = 1M 160 RAM : ORIGIN = 0x20000000, LENGTH = 1M 161 } 162 163 REGION_ALIAS("REGION_TEXT", ROM); 164 REGION_ALIAS("REGION_RODATA", ROM2); 165 REGION_ALIAS("REGION_DATA", RAM); 166 REGION_ALIAS("REGION_BSS", RAM); 167</pre> 168 </dl> 169 170 <p>It is possible to write a common system initialization routine to copy the 171<code>.data</code> section from <code>ROM</code> or <code>ROM2</code> into the <code>RAM</code> if 172necessary: 173<pre class="smallexample"> #include <string.h> 174 175 extern char data_start []; 176 extern char data_size []; 177 extern char data_load_start []; 178 179 void copy_data(void) 180 { 181 if (data_start != data_load_start) 182 { 183 memcpy(data_start, data_load_start, (size_t) data_size); 184 } 185 } 186</pre> 187 </body></html> 188 189