1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence</title><link rel="stylesheet" href="cs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><meta name="description" content=" CS3 is CodeSourcery's low-level board support library. This chapter documents the boards supported by Sourcery CodeBench Lite and the compiler and linker options you need to use with them. It also explains how you can use and modify CS3-provided definitions for memory maps, system startup code and interrupt vectors in your own code."><link rel="home" href="index.html" title="Sourcery CodeBench Lite"><link rel="up" href="index.html" title="Sourcery CodeBench Lite"><link rel="prev" href="sec-remote-debugging.html" title="4.4.�Running Applications from GDB"><link rel="next" href="sec-cs3-startup.html" title="5.2.�Program Startup and Termination"></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">Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-remote-debugging.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="sec-cs3-startup.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chap-cs3"></a>Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence</h2></div><div><div class="abstract"><p class="title"><b></b></p><p> 2 CS3 is CodeSourcery's low-level board support library. 3 This chapter documents the boards 4 supported by Sourcery CodeBench Lite and the compiler and linker 5 options you need to use with them. 6 It also explains how you can use and modify CS3-provided 7 definitions for memory maps, system startup code and 8 interrupt vectors in your own code. 9 </p></div></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="chap-cs3.html#sec-cs3-linker-scripts">5.1. Linker Scripts</a></span></dt><dt><span class="section"><a href="sec-cs3-startup.html">5.2. Program Startup and Termination</a></span></dt><dt><span class="section"><a href="sec-cs3-memory-layout.html">5.3. Memory Layout</a></span></dt><dt><span class="section"><a href="sec-cs3-interrupts.html">5.4. Interrupt Vectors and Handlers</a></span></dt><dt><span class="section"><a href="sec-cs3-supported-boards.html">5.5. Supported Boards for ARM EABI</a></span></dt><dt><span class="section"><a href="sec-cs3-vector-tables.html">5.6. Interrupt Vector Tables</a></span></dt></dl></div><p> 10 Many developers turn to the GNU toolchain for its cross-platform 11 consistency: having a single system support so many different 12 processors and boards helps to limit risk and keep learning curves 13 gentle. Historically, however, the GNU toolchain has lacked a 14 consistent set of conventions for processor- and board-level 15 initialization, language run-time setup, and interrupt and trap 16 handler definition. 17 </p><p> 18 The CodeSourcery Common Startup Code Sequence (CS3) addresses 19 this problem. For each supported system, CS3 provides a set of 20 linker scripts describing the system's memory map, and a board 21 support library providing generic reset, startup, and interrupt 22 handlers. These scripts and libraries all follow a standard set 23 of conventions across a range of processors and boards. 24 </p><p> 25 In addition to providing linker support, CS3's functionality is 26 fully integrated with the Sourcery CodeBench Debug Sprite. For each 27 supported board, CS3 provides the board file containing the 28 memory map and initialization sequence required for debugging 29 applications on the board via the Sprite, as documented in 30 <a class="xref" href="sec-sprite-supported-boards.html" title="6.9.�Supported Board Files">Section�6.9, “Supported Board Files”</a>. 31 </p><p> 32 This chapter is organized in two parts. The first part explains 33 CS3 concepts: 34 </p><div class="itemizedlist"><ul type="disc"><li><a class="xref" href="chap-cs3.html#sec-cs3-linker-scripts" title="5.1.�Linker Scripts">Section�5.1, “Linker Scripts”</a> provides basic information 35 you need to know in order to select an appropriate 36 CS3-provided linker script for your ARM EABI board. 37 </li><li> 38 CS3's program startup and termination model is discussed in 39 <a class="xref" href="sec-cs3-startup.html" title="5.2.�Program Startup and Termination">Section�5.2, “Program Startup and Termination”</a>. 40 </li><li><a class="xref" href="sec-cs3-memory-layout.html" title="5.3.�Memory Layout">Section�5.3, “Memory Layout”</a> 41 discusses the mapping from program sections to memory regions. 42 It also explains how you can refer to 43 memory regions using CS3-provided symbolic names from C, 44 assembly language, or the linker script, and customize placement 45 of code or data in your program. 46 </li><li><a class="xref" href="sec-cs3-interrupts.html" title="5.4.�Interrupt Vectors and Handlers">Section�5.4, “Interrupt Vectors and Handlers”</a> covers CS3's interrupt 47 handling model, and discusses how you can customize the CS3-provided 48 interrupt vector tables. 49 </li></ul></div><p> 50 The second part provides details about the CS3 implementation for 51 ARM EABI: 52 </p><div class="itemizedlist"><ul type="disc"><li><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> lists the boards 53 supported by CS3 for ARM EABI, and the available linker 54 scripts for them. 55 </li><li><a class="xref" href="sec-cs3-vector-tables.html" title="5.6.�Interrupt Vector Tables">Section�5.6, “Interrupt Vector Tables”</a> 56 documents the details of the provided interrupt vectors 57 for CS3-supported devices. 58 </li></ul></div><p> 59 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec-cs3-linker-scripts"></a>5.1.�Linker Scripts</h2></div></div></div><p> 60 When you build programs for ARM EABI targets, you must 61 use a linker script. The linker script serves several purposes: 62 63 </p><div class="itemizedlist"><ul type="disc"><li> 64 It determines the memory addresses for placement of code and 65 data sections. 66 </li><li> 67 It defines symbolic names for memory regions present on the 68 board, which you can use programmatically within your code. 69 </li><li> 70 It provides appropriate program startup and termination code, 71 and causes the linker to pull in any low-level board support 72 libraries that are required to run code on the target. 73 </li><li> 74 It optionally provides a <em class="firstterm">hosting</em> library 75 for basic I/O functionality. 76 </li><li> 77 It provides a default interrupt vector appropriate for the 78 target processor. 79 </li></ul></div><p> 80 </p><p> 81 82 When invoking the Sourcery CodeBench linker from the command line, 83 you must explicitly supply a linker script using the 84 <code class="option">-T</code> option; otherwise a link error results. 85 </p><p> 86 CS3 may provide multiple linker scripts for different configurations 87 using the same board. For example, on some boards CS3 may support 88 running the program from either RAM or ROM (flash). 89 Some CS3 link configurations are also designed to co-exist with, or be 90 run from, a boot monitor on the target board. 91 Simulator targets typically require different startup code configurations 92 than hardware targets. 93 In CS3 terminology, each of these different 94 configurations is referred to as a <em class="firstterm">profile</em>. 95 </p><p> 96 The remainder of this section discusses profile and hosting 97 selection considerations in more detail. You can find the full 98 list of supported boards and linker scripts included in this 99 release of Sourcery CodeBench Lite in <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>. 100 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id525012"></a>5.1.1.�Program and Data Placement</h3></div></div></div><p> 101 Many boards have both RAM and ROM (flash) memory devices. CS3 102 provides distinct linker scripts to place the application either 103 entirely in RAM, or to place code and read-only data in ROM. 104 </p><p> 105 Some boards have very small amounts of RAM memory. If you use 106 large library functions (such as <code class="function">printf</code> and 107 <code class="function">malloc</code>), you may overflow the available 108 memory. You may need to use the ROM-based profile for 109 such programs, so that the program itself is stored in ROM. You 110 may be able to reduce the total amount of memory used by your 111 program by replacing portions of the Sourcery CodeBench runtime library 112 and/or startup code. 113 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-cs3-semihosting"></a>5.1.2.�Hosting and Semihosting</h3></div></div></div><p> 114 CS3 is designed to support boards without an operating system. 115 To allow functions like 116 <code class="function">open</code> and <code class="function">write</code> to 117 work without operating system support, a 118 <em class="firstterm">semihosting</em> feature is 119 supported, in conjunction with the debugger. 120 </p><p> 121 With semihosting enabled, these system calls are translated 122 into equivalent function calls on your host system. You can 123 only use these function calls while connected to the debugger; 124 if you try to use them when disconnected from the debugger, 125 you will get a hardware exception. 126 </p><p> 127 Semihosting requires support from the remote GDB debugging stub 128 or agent, as well as the debugger itself. 129 <span> 130 The Sourcery CodeBench Debug Sprite implements semihosting for all 131 supported devices. 132 </span> 133 <span> 134 Semihosting is 135 <span>also</span> 136 supported by the 137 <span> 138 GDB Simulator 139 140 </span> 141 142 included with Sourcery CodeBench Lite. 143 </span> 144 However, semihosting may not be supported by debugging stubs 145 provided by third parties. If you are using a debug device that 146 communicates with GDB using the GDB remote protocol, 147 check the documentation for your device to see whether semihosting 148 is supported. 149 </p><p> 150 A good use of semihosting is to display debugging messages. For 151 example, this program prints a message on the debugger console 152 on the host: 153 </p><pre class="programlisting">#include <unistd.h> 154 155int main () { 156 write (STDERR_FILENO, "Hello, world!\n", 14); 157 return 0; 158}</pre><p> 159 </p><p> 160 The hosted CS3 linker scripts provide the semihosting support, 161 and as such programs linked with them may only be run with the 162 debugger. For production code, or programs where memory usage 163 is tightly constrained, use the unhosted CS3 linker scripts 164 instead. 165 These scripts provide stub versions of the system calls, 166 which return an appropriate 167 error value in <code class="varname">errno</code>. If such a stub 168 system call is required in the executable, the linker also 169 produces a warning. Such a warning may indicate that you have 170 left debugging code active, or that your program contains unused 171 code. 172 </p><p> 173 As an alternative to semihosting via the debugger, 174 some targets supported by CS3 can run a boot monitor that 175 provides console I/O services and other basic system calls. 176 CS3 can also provide hosting via these facilities; where a boot 177 monitor is supported, this is noted in the board tables below. 178 Unlike semihosting, hosting via the boot monitor can be used when 179 running programs outside of the debugger. 180 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id525143"></a>5.1.3.�Specifying a Linker Script</h3></div></div></div><p> 181 When using Sourcery CodeBench from the command line or from a 182 <code class="filename">Makefile</code>, you must add <code class="option">-T 183 <em class="replaceable"><code>script</code></em></code> to your linking 184 command, where <em class="replaceable"><code>script</code></em> is the 185 appropriate linker script. For example, to target 186 Altera Cyclone III Cortex-M1 boards, you could link with <code class="option">-T 187 cycloneiii-cm1-ram-hosted.ld</code>. 188 </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-remote-debugging.html">Prev</a>�</td><td width="20%" align="center">�</td><td width="40%" align="right">�<a accesskey="n" href="sec-cs3-startup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.4.�Running Applications from GDB�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�5.2.�Program Startup and Termination</td></tr></table></div></body></html> 189