<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 Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10))
version 2.33.1.

Copyright (C) 1991-2019 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:&nbsp;<a rel="next" accesskey="n" href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Format-Commands.html#Format-Commands">Format Commands</a>,
Up:&nbsp;<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-419"></a><a name="index-region-alias-420"></a><a name="index-region-names-421"></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)
           } &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>
   <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 &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>
   </body></html>