visus
/
toolchain-gcc-arm-embedded

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the GNU linker LD
(GNU Arm Embedded Toolchain 10-2020-q4-major)
version 2.35.1.

Copyright (C) 1991-2020 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". -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>REGION_ALIAS (LD)</title>

<meta name="description" content="REGION_ALIAS (LD)">
<meta name="keywords" content="REGION_ALIAS (LD)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Simple-Commands.html#Simple-Commands" rel="up" title="Simple Commands">
<link href="Miscellaneous-Commands.html#Miscellaneous-Commands" rel="next" title="Miscellaneous Commands">
<link href="Format-Commands.html#Format-Commands" rel="prev" title="Format Commands">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="REGION_005fALIAS"></a>
<div class="header">
<p>
Next: <a href="Miscellaneous-Commands.html#Miscellaneous-Commands" accesskey="n" rel="next">Miscellaneous Commands</a>, Previous: <a href="Format-Commands.html#Format-Commands" accesskey="p" rel="prev">Format Commands</a>, Up: <a href="Simple-Commands.html#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> &nbsp; [<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>
</div>
<hr>
<a name="Assign-alias-names-to-memory-regions"></a>
<h4 class="subsection">3.4.4 Assign alias names to memory regions</h4>
<a name="index-REGION_005fALIAS_0028alias_002c-region_0029"></a>
<a name="index-region-alias"></a>
<a name="index-region-names"></a>

<p>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.
</p>
<div class="smallexample">
<pre class="smallexample">REGION_ALIAS(<var>alias</var>, <var>region</var>)
</pre></div>

<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>
<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:
</p>
<ul>
<li> <code>.text</code> program code;
</li><li> <code>.rodata</code> read-only data;
</li><li> <code>.data</code> read-write initialized data;
</li><li> <code>.bss</code> read-write zero initialized data.
</li></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>
<tr><td width="25%">Section</td><td width="25%">Variant A</td><td width="25%">Variant B</td><td width="25%">Variant C</td></tr>
<tr><td width="25%">.text</td><td width="25%">RAM</td><td width="25%">ROM</td><td width="25%">ROM</td></tr>
<tr><td width="25%">.rodata</td><td width="25%">RAM</td><td width="25%">ROM</td><td width="25%">ROM2</td></tr>
<tr><td width="25%">.data</td><td width="25%">RAM</td><td width="25%">RAM/ROM</td><td width="25%">RAM/ROM2</td></tr>
<tr><td width="25%">.bss</td><td width="25%">RAM</td><td width="25%">RAM</td><td width="25%">RAM</td></tr>
</table>
<p>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>
<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:
</p><div class="smallexample">
<pre class="smallexample">INCLUDE linkcmds.memory

SECTIONS
  {
    .text :
      {
        *(.text)
      } &gt; REGION_TEXT
    .rodata :
      {
        *(.rodata)
        rodata_end = .;
      } &gt; REGION_RODATA
    .data : AT (rodata_end)
      {
        data_start = .;
        *(.data)
      } &gt; REGION_DATA
    data_size = SIZEOF(.data);
    data_load_start = LOADADDR(.data);
    .bss :
      {
        *(.bss)
      } &gt; REGION_BSS
  }
</pre></div>

<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>:
</p><dl compact="compact">
<dt><code>A</code></dt>
<dd><p>Here everything goes into the <code>RAM</code>.
</p><div class="smallexample">
<pre class="smallexample">MEMORY
  {
    RAM : ORIGIN = 0, LENGTH = 4M
  }

REGION_ALIAS(&quot;REGION_TEXT&quot;, RAM);
REGION_ALIAS(&quot;REGION_RODATA&quot;, RAM);
REGION_ALIAS(&quot;REGION_DATA&quot;, RAM);
REGION_ALIAS(&quot;REGION_BSS&quot;, RAM);
</pre></div>
</dd>
<dt><code>B</code></dt>
<dd><p>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>.
</p><div class="smallexample">
<pre class="smallexample">MEMORY
  {
    ROM : ORIGIN = 0, LENGTH = 3M
    RAM : ORIGIN = 0x10000000, LENGTH = 1M
  }

REGION_ALIAS(&quot;REGION_TEXT&quot;, ROM);
REGION_ALIAS(&quot;REGION_RODATA&quot;, ROM);
REGION_ALIAS(&quot;REGION_DATA&quot;, RAM);
REGION_ALIAS(&quot;REGION_BSS&quot;, RAM);
</pre></div>
</dd>
<dt><code>C</code></dt>
<dd><p>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>.
</p><div class="smallexample">
<pre class="smallexample">MEMORY
  {
    ROM : ORIGIN = 0, LENGTH = 2M
    ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
    RAM : ORIGIN = 0x20000000, LENGTH = 1M
  }

REGION_ALIAS(&quot;REGION_TEXT&quot;, ROM);
REGION_ALIAS(&quot;REGION_RODATA&quot;, ROM2);
REGION_ALIAS(&quot;REGION_DATA&quot;, RAM);
REGION_ALIAS(&quot;REGION_BSS&quot;, RAM);
</pre></div>
</dd>
</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:
</p><div class="smallexample">
<pre class="smallexample">#include &lt;string.h&gt;

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></div>

<hr>
<div class="header">
<p>
Next: <a href="Miscellaneous-Commands.html#Miscellaneous-Commands" accesskey="n" rel="next">Miscellaneous Commands</a>, Previous: <a href="Format-Commands.html#Format-Commands" accesskey="p" rel="prev">Format Commands</a>, Up: <a href="Simple-Commands.html#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> &nbsp; [<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>
</div>


</body>
</html>