<html lang="en">
<head>
<title>REGION_ALIAS - Untitled</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Untitled">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Simple-Commands.html#Simple-Commands" title="Simple Commands">
<link rel="prev" href="Format-Commands.html#Format-Commands" title="Format Commands">
<link rel="next" href="Miscellaneous-Commands.html#Miscellaneous-Commands" title="Miscellaneous Commands">
<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.26.
Copyright (C) 1991-2015 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.3
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; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="REGION_ALIAS"></a>
<a name="REGION_005fALIAS"></a>
<p>
Next: <a rel="next" accesskey="n" href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>,
Previous: <a rel="previous" accesskey="p" href="Format-Commands.html#Format-Commands">Format Commands</a>,
Up: <a rel="up" accesskey="u" href="Simple-Commands.html#Simple-Commands">Simple Commands</a>
<hr>
</div>
<h4 class="subsection">3.4.4 Assign alias names to memory regions</h4>
<p><a name="index-REGION_005fALIAS_0028_0040var_007balias_007d_002c-_0040var_007bregion_007d_0029-398"></a><a name="index-region-alias-399"></a><a name="index-region-names-400"></a>
Alias names can be added to existing memory regions created with the
<a href="MEMORY.html#MEMORY">MEMORY</a> command. Each name corresponds to at most one memory region.
<pre class="smallexample"> REGION_ALIAS(<var>alias</var>, <var>region</var>)
</pre>
<p>The <code>REGION_ALIAS</code> function creates an alias name <var>alias</var> for the
memory region <var>region</var>. This allows a flexible mapping of output sections
to memory regions. An example follows.
<p>Suppose we have an application for embedded systems which come with various
memory storage devices. All have a general purpose, volatile memory <code>RAM</code>
that allows code execution or data storage. Some may have a read-only,
non-volatile memory <code>ROM</code> that allows code execution and read-only data
access. The last variant is a read-only, non-volatile memory <code>ROM2</code> with
read-only data access and no code execution capability. We have four output
sections:
<ul>
<li><code>.text</code> program code;
<li><code>.rodata</code> read-only data;
<li><code>.data</code> read-write initialized data;
<li><code>.bss</code> read-write zero initialized data.
</ul>
<p>The goal is to provide a linker command file that contains a system independent
part defining the output sections and a system dependent part mapping the
output sections to the memory regions available on the system. Our embedded
systems come with three different memory setups <code>A</code>, <code>B</code> and
<code>C</code>:
<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
<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
<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
<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
<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
<br></td></tr></table>
The notation <code>RAM/ROM</code> or <code>RAM/ROM2</code> means that this section is
loaded into region <code>ROM</code> or <code>ROM2</code> respectively. Please note that
the load address of the <code>.data</code> section starts in all three variants at
the end of the <code>.rodata</code> section.
<p>The base linker script that deals with the output sections follows. It
includes the system dependent <code>linkcmds.memory</code> file that describes the
memory layout:
<pre class="smallexample"> INCLUDE linkcmds.memory
SECTIONS
{
.text :
{
*(.text)
} > REGION_TEXT
.rodata :
{
*(.rodata)
rodata_end = .;
} > REGION_RODATA
.data : AT (rodata_end)
{
data_start = .;
*(.data)
} > REGION_DATA
data_size = SIZEOF(.data);
data_load_start = LOADADDR(.data);
.bss :
{
*(.bss)
} > REGION_BSS
}
</pre>
<p>Now we need three different <code>linkcmds.memory</code> files to define memory
regions and alias names. The content of <code>linkcmds.memory</code> for the three
variants <code>A</code>, <code>B</code> and <code>C</code>:
<dl>
<dt><code>A</code><dd>Here everything goes into the <code>RAM</code>.
<pre class="smallexample"> MEMORY
{
RAM : ORIGIN = 0, LENGTH = 4M
}
REGION_ALIAS("REGION_TEXT", RAM);
REGION_ALIAS("REGION_RODATA", RAM);
REGION_ALIAS("REGION_DATA", RAM);
REGION_ALIAS("REGION_BSS", RAM);
</pre>
<br><dt><code>B</code><dd>Program code and read-only data go into the <code>ROM</code>. Read-write data goes
into the <code>RAM</code>. An image of the initialized data is loaded into the
<code>ROM</code> and will be copied during system start into the <code>RAM</code>.
<pre class="smallexample"> MEMORY
{
ROM : ORIGIN = 0, LENGTH = 3M
RAM : ORIGIN = 0x10000000, LENGTH = 1M
}
REGION_ALIAS("REGION_TEXT", ROM);
REGION_ALIAS("REGION_RODATA", ROM);
REGION_ALIAS("REGION_DATA", RAM);
REGION_ALIAS("REGION_BSS", RAM);
</pre>
<br><dt><code>C</code><dd>Program code goes into the <code>ROM</code>. Read-only data goes into the
<code>ROM2</code>. Read-write data goes into the <code>RAM</code>. An image of the
initialized data is loaded into the <code>ROM2</code> and will be copied during
system start into the <code>RAM</code>.
<pre class="smallexample"> MEMORY
{
ROM : ORIGIN = 0, LENGTH = 2M
ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
RAM : ORIGIN = 0x20000000, LENGTH = 1M
}
REGION_ALIAS("REGION_TEXT", ROM);
REGION_ALIAS("REGION_RODATA", ROM2);
REGION_ALIAS("REGION_DATA", RAM);
REGION_ALIAS("REGION_BSS", RAM);
</pre>
</dl>
<p>It is possible to write a common system initialization routine to copy the
<code>.data</code> section from <code>ROM</code> or <code>ROM2</code> into the <code>RAM</code> if
necessary:
<pre class="smallexample"> #include <string.h>
extern char data_start [];
extern char data_size [];
extern char data_load_start [];
void copy_data(void)
{
if (data_start != data_load_start)
{
memcpy(data_start, data_load_start, (size_t) data_size);
}
}
</pre>
</body></html>