1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>5.3.�Memory Layout</title><link rel="stylesheet" href="cs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="Sourcery CodeBench Lite"><link rel="up" href="chap-cs3.html" title="Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence"><link rel="prev" href="sec-cs3-startup.html" title="5.2.�Program Startup and Termination"><link rel="next" href="sec-cs3-interrupts.html" title="5.4.�Interrupt Vectors and Handlers"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.3.�Memory Layout</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-cs3-startup.html">Prev</a>�</td><th width="60%" align="center">Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence</th><td width="20%" align="right">�<a accesskey="n" href="sec-cs3-interrupts.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec-cs3-memory-layout"></a>5.3.�Memory Layout</h2></div></div></div><p> 2 Boards supported by CS3 can have multiple banks or regions of 3 memory with different characteristics. 4 This section describes how program sections are mapped onto 5 memory regions, and how you can use these CS3 features to customize 6 placement of your program's code or data in memory. 7 CS3 also provides a uniform set of symbolic names for each region, 8 allowing you to programmatically refer to each region's address range 9 from C or assembly language as well as from the linker script. 10 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-cs3-regions"></a>5.3.1.�Memory Regions and Program Sections</h3></div></div></div><p> 11 The regions that are available on a particular board are listed 12 in the table for that board in 13 <a class="xref" href="sec-cs3-supported-boards.html" title="5.5.�Supported Boards for ARM EABI">Section�5.5, “Supported Boards for ARM EABI”</a>, below. 14 There are two kinds of regions: those documented as 15 "Memory regions", which are general-purpose memory banks 16 that can be used for program or data storage; 17 and those documented as "Other regions", which typically 18 correspond to memory-mapped control registers or other 19 special-purpose storage. 20 </p><p> 21 CS3 supports boards that include both <code class="literal">ram</code> 22 and <code class="literal">rom</code> memory regions. The <code class="literal">ram</code> 23 region holds the <code class="literal">.data</code> and <code class="literal">.bss</code> 24 sections, and the <code class="literal">.text</code> section in RAM profiles. 25 In ROM profiles, the <code class="literal">rom</code> region holds the 26 <code class="literal">.text</code> section and initialization values for 27 the writable data sections. 28 </p><p> 29 In addition, all regions documented as "Memory regions" correspond to 30 similarly-named program sections. 31 For example, the linker script assigns the <code class="literal">.ram</code> 32 section to the <code class="literal">ram</code> region. 33 </p><p> 34 More generally, for a memory region named 35 <em class="replaceable"><code>R</code></em>, CS3 linker scripts define a 36 section named <code class="literal">.<em class="replaceable"><code>R</code></em></code>, 37 which may contain initialized data or code. There is also a section 38 named <code class="literal">.bss.<em class="replaceable"><code>R</code></em></code> for 39 zero-initialized data (BSS), which is placed after the initialized 40 data section for this region. 41 42 </p><p> 43 You can explicitly locate data or code in a section 44 corresponding to a particular memory region using 45 section attributes in your source C or C++ code. 46 Section attributes are especially useful on code compiled for 47 boards that include special memory banks, such as a fast on-chip 48 cache memory, in addition to the default 49 <code class="literal">ram</code> and/or <code class="literal">rom</code> regions. 50 CS3's start-up code arranges for additional data-like sections 51 to be initialized in the same way as the default 52 <code class="literal">.data</code> section. 53 </p><p> 54 As an example to illustrate the attribute syntax, 55 you can put a variable 56 <code class="varname">v</code> in the <code class="literal">.ram</code> section using: 57 58 </p><pre class="programlisting">int v __attribute__ ((section (".ram")));</pre><p> 59 60 To declare a function <code class="function">f</code> in this section, use: 61 62 </p><pre class="programlisting">int f (void) __attribute__ ((section (".ram"))) {...}</pre><p> 63 64 For more information about attribute syntax, see the GCC manual. 65 </p><p> 66 In addition to the <code class="literal">.<em class="replaceable"><code>R</code></em></code> 67 and <code class="literal">.bss.<em class="replaceable"><code>R</code></em></code> sections, 68 CS3 places a 69 <code class="literal">.cs3.region-head.<em class="replaceable"><code>R</code></em></code> 70 section at the beginning of each region <em class="replaceable"><code>R</code></em>. 71 Explicitly placing data in 72 <code class="literal">.cs3.region-head.<em class="replaceable"><code>R</code></em></code> 73 sections is discouraged, because CS3 itself may want to place items 74 (like interrupt vector tables) at these locations. 75 If there is a conflict, CS3 raises an error at link time. 76 </p><p> 77 Regions documented as "Other regions" in the tables in 78 <a class="xref" href="sec-cs3-supported-boards.html" title="5.5.�Supported Boards for ARM EABI">Section�5.5, “Supported Boards for ARM EABI”</a> 79 do not have corresponding program sections. 80 Typically, these regions contain 81 memory-mapped control and I/O registers and cannot be used for 82 general data or program storage. 83 If your program needs to manipulate data in 84 these regions, you can use the CS3 memory map access interface 85 declared in <code class="filename">cs3.h</code>, 86 as described in <a class="xref" href="sec-cs3-memory-layout.html#sec-cs3-memory-hooks" title="5.3.2.�Programmatic Access to the CS3 Memory Map">Section�5.3.2, “Programmatic Access to the CS3 Memory Map”</a>. 87 </p><p> 88 Memory maps for boards supported by Sourcery CodeBench Lite for ARM EABI 89 are documented in 90 XML files in the <code class="filename">arm-none-eabi/lib/boards/</code> 91 subdirectory of your Sourcery CodeBench installation directory. 92 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-cs3-memory-hooks"></a>5.3.2.�Programmatic Access to the CS3 Memory Map</h3></div></div></div><p> 93 CS3 makes C declarations describing the memory regions on the 94 target board available to your program via the header file 95 <code class="filename">cs3.h</code>, which you can 96 find in the 97 <code class="filename">arm-none-eabi/include</code> directory 98 within your install. 99 </p><p> 100 For each region named <em class="replaceable"><code>R</code></em>, 101 <code class="filename">cs3.h</code> declares a byte array 102 variable 103 <code class="varname">__cs3_region_start_<em class="replaceable"><code>R</code></em></code> 104 at the region's start address, and a <code class="type">size_t</code> variable 105 <code class="varname">__cs3_region_size_<em class="replaceable"><code>R</code></em></code> 106 to represent the total size of the region. These symbols are 107 defined by the linker script and so may also be referenced from 108 assembly language. Note that all regions are aligned on eight-byte 109 boundaries and sizes are also multiples of eight bytes. 110 </p><p> 111 For memory regions that can correspond to program 112 sections (as described in <a class="xref" href="sec-cs3-memory-layout.html#sec-cs3-regions" title="5.3.1.�Memory Regions and Program Sections">Section�5.3.1, “Memory Regions and Program Sections”</a>), 113 there are additional symbols 114 <code class="varname">__cs3_region_init_<em class="replaceable"><code>R</code></em></code> 115 and 116 <code class="varname">__cs3_region_init_size_<em class="replaceable"><code>R</code></em></code> 117 that describe constant data used to initialize the region. 118 During the C initialization phase (<a class="xref" href="sec-cs3-startup.html" title="5.2.�Program Startup and Termination">Section�5.2, “Program Startup and Termination”</a>), 119 this data is copied into the lower part of the memory region. 120 The symbol 121 <code class="varname">__cs3_region_zero_size_<em class="replaceable"><code>R</code></em></code> 122 represents the size of the zero-initialized 123 <code class="literal">.bss.<em class="replaceable"><code>R</code></em></code> section 124 following the initialized data. 125 Any of these identifiers may actually be defined as a preprocessor 126 macro that expands to an expression of the appropriate type and 127 value. 128 </p><p> 129 To perform the memory region initializations during startup, 130 CS3 internally uses the array variable 131 <code class="varname">__cs3_regions</code>, which 132 contains descriptors for all of the writable (RAM) memory regions. 133 These descriptors are also exposed in 134 <code class="filename">cs3.h</code>; 135 refer to the header file for details. 136 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-cs3-heap-stack"></a>5.3.3.�Heap and Stack Placement</h3></div></div></div><p> 137 CS3 linker scripts provide default placement of the heap and 138 stack in the RAM region. However, you can override the defaults 139 by providing your own definitions of the associated CS3 variables. 140 For example, you may put the heap and/or stack in some other 141 memory region. 142 </p><p> 143 Heap placement is controlled by defining the symbol 144 <code class="varname">__cs3_heap_start</code> at the beginning of the heap, 145 and either the symbol <code class="varname">__cs3_heap_end</code> or the 146 pointer variable <code class="varname">__cs3_heap_limit</code> to mark the 147 end of the heap. For example, this fragment of C code places 148 the heap in a region named <code class="literal">extsram</code>: 149 150</p><pre class="programlisting">#define HEAPSIZE ... /* However big you want to make it. */ 151unsigned char __cs3_heap_start[HEAPSIZE] 152 __attribute__ ((section (".bss.extsram"), aligned(8))); 153unsigned char *__cs3_heap_limit = __cs3_heap_start + HEAPSIZE; 154</pre><p> 155 </p><p> 156 The default initial stack pointer for bare-metal profiles 157 is given by the symbol <code class="varname">__cs3_stack</code>, and the stack 158 grows downward from this address. 159 Stack initialization is discussed in more detail in 160 <a class="xref" href="sec-cs3-startup.html#sec-cs3-assembly-initialization" title="5.2.2.�The Assembly Initialization Phase">Section�5.2.2, “The Assembly Initialization Phase”</a>. 161 </p><p> 162 You can find C declarations for the CS3 heap and stack symbols 163 in the header file <code class="filename">cs3.h</code>. 164 </p><p> 165 The <code class="filename">cs3.h</code> header file also 166 defines a macro for creating a custom stack. The custom stack is 167 created as a block of RAM in the zero-initialized data section (BSS). 168 The specified size must be a compile-time constant. To account for 169 alignment, the final size of the stack may be a few bytes less than the 170 requested size. The symbol <code class="varname">__cs3_stack</code> is 171 initialized to point to the last extent of the stack block, and is 172 16-byte aligned. 173 174 For example, the following fragment of C code creates a stack of 8192 175 bytes: 176 177 </p><pre class="programlisting">#include <cs3.h> 178 179CS3_STACK(2 * 4096);</pre><p> 180 181 As indicated in <a class="xref" href="sec-cs3-startup.html#sec-cs3-assembly-initialization" title="5.2.2.�The Assembly Initialization Phase">Section�5.2.2, “The Assembly Initialization Phase”</a>, 182 there are cases where a boot monitor or simulator overrides a custom 183 stack. 184 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-cs3-startup.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="chap-cs3.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="sec-cs3-interrupts.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.2.�Program Startup and Termination�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�5.4.�Interrupt Vectors and Handlers</td></tr></table></div></body></html> 185