1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>5.2.�Program Startup and Termination</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="chap-cs3.html" title="Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence"><link rel="next" href="sec-cs3-memory-layout.html" title="5.3.�Memory Layout"></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.2.�Program Startup and Termination</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="chap-cs3.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-memory-layout.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-startup"></a>5.2.�Program Startup and Termination</h2></div></div></div><p> 2 This section documents CS3's model for target initialization 3 prior to invoking the <code class="function">main</code> function of 4 your program, and aspects of program termination that are 5 left unspecified in the C and C++ standards. It explains how 6 you can customize or override the default behavior for your 7 application. 8 </p><p> 9 CS3 divides the startup sequence into three phases: 10 </p><div class="itemizedlist"><ul type="disc"><li><p>The <em class="firstterm">hard reset phase</em> 11 (<code class="function">__cs3_reset</code>) 12 includes actions such as initializing the memory controller and 13 setting up the memory map. 14 </p></li><li><p>The <em class="firstterm">assembly initialization phase</em> 15 (<code class="function">__cs3_start_asm</code>) 16 prepares the stack to run C code, 17 and jumps to the C initialization function.</p></li><li><p>The <em class="firstterm">C initialization phase</em> 18 (<code class="function">__cs3_start_c</code>) 19 is responsible for initializing the data areas, 20 running constructors for statically-allocated objects, 21 and calling <code class="function">main</code>.</p></li></ul></div><p> 22 </p><p> 23 The hard reset and assembly initialization phases are 24 necessarily written in assembly language; at reset, there may 25 not yet be stack to hold compiler temporaries, or perhaps even 26 any RAM accessible to hold the stack. These phases do the 27 minimum necessary to prepare the environment for running simple 28 C code. Then, the code for the final phase may be written in C; 29 CS3 leaves as much as possible to be done at this point. 30 </p><p> 31 The CodeSourcery board support library provides default code for 32 all three phases. The hard reset phase is implemented by 33 board- and profile-specific code. 34 The assembly initialization phase is 35 implemented by profile-specific code. 36 The C initialization phase is implemented by generic code. 37 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id525274"></a>5.2.1.�The Hard Reset Phase</h3></div></div></div><p> 38 This phase, which begins at <code class="function">__cs3_reset</code>, 39 is responsible for initializing board-specific 40 registers, such as memory base registers and DRAM controllers, 41 or scanning memory to check the available size. It is written 42 in assembler and ends with a jump to 43 <code class="function">__cs3_start_asm</code>, which is where the assembly 44 initialization phase begins. 45 </p><p> 46 The hard reset code is in a section named 47 <code class="literal">.cs3.reset</code>. CS3 linker scripts define 48 <code class="function">__cs3_reset</code> as an alias for a board- and 49 profile-specific entry point. You may override the 50 CS3-provided reset code by defining your own 51 <code class="function">__cs3_reset</code> entry point in the 52 <code class="literal">.cs3.reset</code> section. 53 </p><p> 54 Program execution always begins at <code class="function">__cs3_reset</code>, 55 whether the program is started from the reset vector, the debugger, or 56 a boot monitor. 57 However, the <code class="function">__cs3_reset</code> code linked into the 58 application is typically non-empty only for ROM-based profiles. 59 For example, in a RAM-based profile, resetting 60 the memory controllers would overwrite the code being executed. 61 </p><p> 62 When using the Sourcery CodeBench Debug Sprite, the Sprite is responsible for 63 carrying out the hard reset actions before the program 64 is loaded onto the target. This is performed 65 prior to execution of both RAM- and ROM-profile applications 66 from the debugger. Thus, when debugging a ROM-profile application, 67 hard reset is actually performed twice — once by the Sprite, 68 and once by the application itself. 69 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-cs3-assembly-initialization"></a>5.2.2.�The Assembly Initialization Phase</h3></div></div></div><p> 70 This phase is responsible for initializing the stack pointer 71 and creating an initial stack frame. 72 The symbol <code class="function">__cs3_start_asm</code> 73 marks the entry point of the 74 assembly initialization code. 75 The assembly initialization phase ends with a call or jump to 76 <code class="function">__cs3_start_c</code>. 77 </p><p> 78 The assembly initialization phase is profile-specific. For 79 example, while bare-board applications typically 80 must initialize the stack themselves, CS3 also supports 81 boot-monitor profiles where the stack is initialized 82 by the boot monitor before it launches the application. 83 Likewise, some simulators automatically 84 initialize the stack pointer and initial stack frame on startup, 85 while others require a supervisory operation on startup to determine 86 the amount of available memory. Each of these scenarios requires 87 different assembly initialization behavior. 88 </p><p> 89 Note that on bare-board targets setting the stack pointer 90 explicitly in the assembly initialization phase is required 91 even if the processor itself initializes the stack pointer 92 automatically on reset. 93 This is to support running programs from 94 the debugger as well as from processor reset. 95 </p><p> 96 For backwards compatibility with previous versions of CS3, 97 on RAM and ROM profiles the symbol 98 <code class="function">__cs3_start_asm</code> is actually an alias 99 for a symbol named <code class="function">_start</code>. 100 However, referencing or defining <code class="function">_start</code> 101 directly is now deprecated. 102 </p><p> 103 The value of the symbol <code class="varname">__cs3_stack</code> 104 provides the initial value of the stack pointer for 105 profiles that must set it explicitly. 106 The CodeSourcery linker scripts provide a default value for this 107 symbol, which you may override by defining 108 <code class="varname">__cs3_stack</code> yourself. 109 110 See <a class="xref" href="sec-cs3-memory-layout.html#sec-cs3-heap-stack" title="5.3.3.�Heap and Stack Placement">Section�5.3.3, “Heap and Stack Placement”</a> for an example of a custom 111 stack. 112 </p><p> 113 The initial stack frame is created for the use of ordinary C 114 and C++ calling conventions. The stack should be initialized 115 so that backtraces stop cleanly at this point; this might 116 entail zeroing a dynamic link pointer, or providing 117 hand-written DWARF call frame information. 118 </p><p> 119 The last action of the assembly initialization phase is to 120 call the C function 121 <code class="function">__cs3_start_c</code>. This function never 122 returns, and <code class="function">__cs3_start_asm</code> 123 need not be prepared to handle a return from it. 124 </p><p> 125 As with the hard reset code, the CodeSourcery board 126 support library provides reasonable default assembly 127 initialization code. However, you may provide 128 your own code by providing a definition 129 for <code class="function">__cs3_start_asm</code>, either in an object 130 file or a library. 131 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id525474"></a>5.2.3.�The C Initialization Phase</h3></div></div></div><p> 132 Finally, C code can be executed. The C startup 133 function is declared as follows: 134 135 </p><pre class="programlisting">void __cs3_start_c (void) __attribute__ ((noreturn));</pre><p> 136 137 This function performs the following steps: 138 </p><div class="itemizedlist"><ul type="disc"><li><p> 139 Initialize all <code class="literal">.data</code>-like sections by 140 copying their contents. For example, ROM-profile linker 141 scripts use this mechanism to initialize writable data in RAM 142 from the read-only data program image. 143 </p></li><li><p> 144 Clear all <code class="literal">.bss</code>-like sections. 145 </p></li><li><p> 146 Run constructors for statically-allocated objects, 147 recorded using whatever conventions are usual for 148 C++ on the target architecture. 149 </p><p> 150 CS3 reserves priorities from 0 to 100 for use by 151 initialization code. You can handle tasks like enabling 152 interrupts, initializing coprocessors, pointing control 153 registers at interrupt vectors, and so on by defining 154 constructors with appropriate priorities. 155 </p></li><li><p> 156 Call <code class="function">main</code> as appropriate. 157 </p></li><li><p> 158 Call <code class="function">exit</code>, if it is available. 159 </p></li></ul></div><p> 160 </p><p> 161 As with the hard reset and assembly initialization code, the 162 CodeSourcery board support library provides a reasonable 163 definition for the <code class="function">__cs3_start_c</code> 164 function. You may override this by providing 165 a definition for <code class="function">__cs3_start_c</code>, 166 either in an object file or in a library. 167 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id525580"></a>5.2.4.�Arguments to <code class="function">main</code></h3></div></div></div><p> 168 The CodeSourcery-provided definition of 169 <code class="function">__cs3_start_c</code> can pass command-line arguments 170 to <code class="function">main</code> using the normal C 171 <code class="varname">argc</code> and <code class="varname">argv</code> mechanism 172 if the board support package provides corresponding definitions for 173 <code class="varname">__cs3_argc</code> and <code class="varname">__cs3_argv</code>. 174 For example: 175 176 </p><pre class="programlisting">int __cs3_argc; 177char **__cs3_argv;</pre><p> 178 179 These variables should be initialized using a constructor function, 180 which is run by <code class="function">__cs3_start_c</code> after it 181 initializes the data segment. Use the <code class="literal">constructor</code> 182 attribute on the function definition: 183 184 </p><pre class="programlisting">__attribute__((constructor)) 185static void __cs3_init_args (void) { 186 __cs3_argc = ...; 187 __cs3_argv = ...; 188}</pre><p> 189 190 The constructor function may have an arbitrary name; 191 <code class="function">__cs3_init_args</code> is used only for illustrative 192 purposes here. 193 </p><p> 194 If definitions of <code class="varname">__cs3_argc</code> and 195 <code class="varname">__cs3_argv</code> are not provided, then the default 196 <code class="function">__cs3_start_c</code> function invokes 197 <code class="function">main</code> with zero as the <code class="varname">argc</code> 198 argument and a null pointer as <code class="varname">argv</code>. 199 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id525686"></a>5.2.5.�Program Termination</h3></div></div></div><p> 200 A program running on an embedded system is usually designed 201 never to exit — it runs until the system is powered down. 202 The C and C++ standards leave it unspecified 203 as to whether <code class="function">exit</code> is called at program 204 termination. If the program never exits, then there is no 205 reason to include <code class="function">exit</code>, facilities to run 206 functions registered with <code class="function">atexit</code>, or global 207 destructors. This code would never be run and would therefore 208 just waste space in the application. 209 </p><p> 210 The CS3 startup code, by itself, does not cause 211 <code class="function">exit</code> to be present in the application. It 212 dynamically checks whether <code class="function">exit</code> is present, 213 and only calls it if it is. If you require 214 <code class="function">exit</code> to be present, either refer to it 215 within your application, or add <code class="option">-Wl,-u,exit</code> to 216 the linking command line. 217 </p><p> 218 Similarly, code to register global destructors is only invoked 219 when <code class="function">atexit</code> is already in the executable; 220 CS3, by itself, does not cause <code class="function">atexit</code> to be 221 present. If you require <code class="function">atexit</code>, either 222 refer to it within your application, or add 223 <code class="option">-Wl,-u,atexit</code> to the linking command line. 224 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="chap-cs3.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-memory-layout.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�5.�CS3™: The CodeSourcery Common Startup Code Sequence�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�5.3.�Memory Layout</td></tr></table></div></body></html> 225