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" type="text/css" href="cs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.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-cs.html" title="4.4.�Using the Compiler Cache"><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-cs.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"><div class="titlepage"><div><div><h1 class="title"><a name="chap-cs3"></a>Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence</h1></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 class="toc"><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 This chapter is organized in two parts. The first part explains 26 CS3 concepts: 27 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><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 28 you need to know in order to select an appropriate 29 CS3-provided linker script for your ARM EABI board. 30 </li><li class="listitem"> 31 CS3's program startup and termination model is discussed in 32 <a class="xref" href="sec-cs3-startup.html" title="5.2.�Program Startup and Termination">Section�5.2, “Program Startup and Termination”</a>. 33 </li><li class="listitem"><a class="xref" href="sec-cs3-memory-layout.html" title="5.3.�Memory Layout">Section�5.3, “Memory Layout”</a> 34 discusses the mapping from program sections to memory regions. 35 It also explains how you can refer to 36 memory regions using CS3-provided symbolic names from C, 37 assembly language, or the linker script, and customize placement 38 of code or data in your program. 39 </li><li class="listitem"><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 40 handling model, and discusses how you can customize the CS3-provided 41 interrupt vector tables. 42 </li></ul></div><p> 43 The second part provides details about the CS3 implementation for 44 ARM EABI: 45 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><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 46 supported by CS3 for ARM EABI, and the available linker 47 scripts for them. 48 </li><li class="listitem"><a class="xref" href="sec-cs3-vector-tables.html" title="5.6.�Interrupt Vector Tables">Section�5.6, “Interrupt Vector Tables”</a> 49 documents the details of the provided interrupt vectors 50 for CS3-supported devices. 51 </li></ul></div><p> 52 </p><div class="section"><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> 53 When you build programs for ARM EABI targets, you must 54 use a linker script. The linker script serves several purposes: 55 56 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 57 It determines the memory addresses for placement of code and 58 data sections. 59 </li><li class="listitem"> 60 It defines symbolic names for memory regions present on the 61 board, which you can use programmatically within your code. 62 </li><li class="listitem"> 63 It provides appropriate program startup and termination code, 64 and causes the linker to pull in any low-level board support 65 libraries that are required to run code on the target. 66 </li><li class="listitem"> 67 It optionally provides a <em class="firstterm">hosting</em> library 68 for basic I/O functionality. 69 </li><li class="listitem"> 70 It provides a default interrupt vector appropriate for the 71 target processor. 72 </li></ul></div><p> 73 </p><p> 74 75 When invoking the Sourcery CodeBench linker from the command line, 76 you must explicitly supply a linker script using the 77 <code class="option">-T</code> option; otherwise a link error results. 78 </p><p> 79 CS3 may provide multiple linker scripts for different configurations 80 using the same board. For example, on some boards CS3 may support 81 running the program from either RAM or ROM (flash). 82 Some CS3 link configurations are also designed to co-exist with, or be 83 run from, a boot monitor on the target board. 84 Simulator targets typically require different startup code configurations 85 than hardware targets. 86 In CS3 terminology, each of these different 87 configurations is referred to as a <em class="firstterm">profile</em>. 88 </p><p> 89 The remainder of this section discusses profile and hosting 90 selection considerations in more detail. You can find the full 91 list of supported boards and linker scripts included in this 92 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>. 93 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm46915333620176"></a>5.1.1.�Program and Data Placement</h3></div></div></div><p> 94 Many boards have both RAM and ROM (flash) memory devices. CS3 95 provides distinct linker scripts to place the application either 96 entirely in RAM, or to place code and read-only data in ROM. 97 </p><p> 98 Some boards have very small amounts of RAM memory. If you use 99 large library functions (such as <code class="function">printf</code> and 100 <code class="function">malloc</code>), you may overflow the available 101 memory. You may need to use the ROM-based profile for 102 such programs, so that the program itself is stored in ROM. You 103 may be able to reduce the total amount of memory used by your 104 program by replacing portions of the Sourcery CodeBench runtime library 105 and/or startup code. 106 </p></div><div class="section"><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> 107 CS3 is designed to support boards without an operating system. 108 To allow functions like 109 <code class="function">open</code> and <code class="function">write</code> to 110 work without operating system support, a 111 <em class="firstterm">semihosting</em> feature is 112 supported, in conjunction with the debugger. 113 </p><p> 114 With semihosting enabled, these system calls are translated 115 into equivalent function calls on your host system. You can 116 only use these function calls while connected to the debugger; 117 if you try to use them when disconnected from the debugger, 118 you will get a hardware exception. 119 </p><p> 120 Semihosting requires support from the remote GDB debugging stub 121 or agent, as well as the debugger itself. 122 123 124 However, semihosting may not be supported by debugging stubs 125 provided by third parties. If you are using a debug device that 126 communicates with GDB using the GDB remote protocol, 127 check the documentation for your device to see whether semihosting 128 is supported. 129 </p><p> 130 A good use of semihosting is to display debugging messages. For 131 example, this program prints a message on the debugger console 132 on the host: 133 </p><pre class="programlisting">#include <unistd.h> 134 135int main () { 136 write (STDERR_FILENO, "Hello, world!\n", 14); 137 return 0; 138}</pre><p> 139 </p><p> 140 The hosted CS3 linker scripts provide the semihosting support, 141 and as such programs linked with them may only be run with the 142 debugger. For production code, or programs where memory usage 143 is tightly constrained, use the unhosted CS3 linker scripts 144 instead. 145 These scripts provide stub versions of the system calls, 146 which return an appropriate 147 error value in <code class="varname">errno</code>. If such a stub 148 system call is required in the executable, the linker also 149 produces a warning. Such a warning may indicate that you have 150 left debugging code active, or that your program contains unused 151 code. 152 </p><p> 153 As an alternative to semihosting via the debugger, 154 some targets supported by CS3 can run a boot monitor that 155 provides console I/O services and other basic system calls. 156 CS3 can also provide hosting via these facilities; where a boot 157 monitor is supported, this is noted in the board tables below. 158 Unlike semihosting, hosting via the boot monitor can be used when 159 running programs outside of the debugger. 160 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm46915333607536"></a>5.1.3.�Specifying a Linker Script</h3></div></div></div><p> 161 When using Sourcery CodeBench from the command line or from a 162 <code class="filename">Makefile</code>, you must add <code class="option">-T 163 <em class="replaceable"><code>script</code></em></code> to your linking 164 command, where <em class="replaceable"><code>script</code></em> is the 165 appropriate linker script. For example, to target 166 Altera Cyclone III Cortex-M1 boards, you could link with <code class="option">-T 167 cycloneiii-cm1-ram-hosted.ld</code>. 168 </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-cs.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.�Using the Compiler Cache�</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> 169