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" type="text/css" href="cs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.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"><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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><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 class="listitem"><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 class="listitem"><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"><div class="titlepage"><div><div><h3 class="title"><a name="idm46915333591856"></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></div><div class="section"><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> 62 This phase is responsible for initializing the stack pointer 63 and creating an initial stack frame. 64 The symbol <code class="function">__cs3_start_asm</code> 65 marks the entry point of the 66 assembly initialization code. 67 The assembly initialization phase ends with a call or jump to 68 <code class="function">__cs3_start_c</code>. 69 </p><p> 70 The assembly initialization phase is profile-specific. For 71 example, while bare-board applications typically 72 must initialize the stack themselves, CS3 also supports 73 boot-monitor profiles where the stack is initialized 74 by the boot monitor before it launches the application. 75 Likewise, some simulators automatically 76 initialize the stack pointer and initial stack frame on startup, 77 while others require a supervisory operation on startup to determine 78 the amount of available memory. Each of these scenarios requires 79 different assembly initialization behavior. 80 </p><p> 81 Note that on bare-board targets setting the stack pointer 82 explicitly in the assembly initialization phase is required 83 even if the processor itself initializes the stack pointer 84 automatically on reset. 85 This is to support running programs from 86 the debugger as well as from processor reset. 87 </p><p> 88 For backwards compatibility with previous versions of CS3, 89 on RAM and ROM profiles the symbol 90 <code class="function">__cs3_start_asm</code> is actually an alias 91 for a symbol named <code class="function">_start</code>. 92 However, referencing or defining <code class="function">_start</code> 93 directly is now deprecated. 94 </p><p> 95 The value of the symbol <code class="varname">__cs3_stack</code> 96 provides the initial value of the stack pointer for 97 profiles that must set it explicitly. 98 The CodeSourcery linker scripts provide a default value for this 99 symbol, which you may override by defining 100 <code class="varname">__cs3_stack</code> yourself. 101 102 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 103 stack. 104 </p><p> 105 The initial stack frame is created for the use of ordinary C 106 and C++ calling conventions. The stack should be initialized 107 so that backtraces stop cleanly at this point; this might 108 entail zeroing a dynamic link pointer, or providing 109 hand-written DWARF call frame information. 110 </p><p> 111 The last action of the assembly initialization phase is to 112 call the C function 113 <code class="function">__cs3_start_c</code>. This function never 114 returns, and <code class="function">__cs3_start_asm</code> 115 need not be prepared to handle a return from it. 116 </p><p> 117 As with the hard reset code, the CodeSourcery board 118 support library provides reasonable default assembly 119 initialization code. However, you may provide 120 your own code by providing a definition 121 for <code class="function">__cs3_start_asm</code>, either in an object 122 file or a library. 123 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="sec-cs3-c-initialization"></a>5.2.3.�The C Initialization Phase</h3></div></div></div><p> 124 Finally, C code can be executed. The C startup 125 function is declared as follows: 126 127 </p><pre class="programlisting">void __cs3_start_c (void) __attribute__ ((noreturn));</pre><p> 128 129 This function performs the following steps: 130 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 131 Initialize all <code class="literal">.data</code>-like sections by 132 copying their contents. For example, ROM-profile linker 133 scripts use this mechanism to initialize writable data in RAM 134 from the read-only data program image. 135 </p></li><li class="listitem"><p> 136 Clear all <code class="literal">.bss</code>-like sections. 137 </p></li><li class="listitem"><p> 138 Run constructors for statically-allocated objects, 139 recorded using whatever conventions are usual for 140 C++ on the target architecture. 141 </p><p> 142 CS3 reserves priorities from 0 to 100 for use by 143 initialization code. You can handle tasks like enabling 144 interrupts, initializing coprocessors, pointing control 145 registers at interrupt vectors, and so on by defining 146 constructors with appropriate priorities. 147 </p></li><li class="listitem"><p> 148 Call <code class="function">main</code> as appropriate. 149 </p></li><li class="listitem"><p> 150 Call <code class="function">exit</code>, if it is available. 151 </p></li></ul></div><p> 152 </p><p> 153 As with the hard reset and assembly initialization code, the 154 CodeSourcery board support library provides a reasonable 155 definition for the <code class="function">__cs3_start_c</code> 156 function. You may override this by providing 157 a definition for <code class="function">__cs3_start_c</code>, 158 either in an object file or in a library. 159 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm46915333556336"></a>5.2.4.�Arguments to <code class="function">main</code></h3></div></div></div><p> 160 The CodeSourcery-provided definition of 161 <code class="function">__cs3_start_c</code> can pass command-line arguments 162 to <code class="function">main</code> using the normal C 163 <code class="varname">argc</code> and <code class="varname">argv</code> mechanism 164 if the board support package provides corresponding definitions for 165 <code class="varname">__cs3_argc</code> and <code class="varname">__cs3_argv</code>. 166 For example: 167 168 </p><pre class="programlisting">int __cs3_argc; 169char **__cs3_argv;</pre><p> 170 171 These variables should be initialized using a constructor function, 172 which is run by <code class="function">__cs3_start_c</code> after it 173 initializes the data segment. Use the <code class="literal">constructor</code> 174 attribute on the function definition: 175 176 </p><pre class="programlisting">__attribute__((constructor)) 177void __cs3_init_args (void) { 178 __cs3_argc = ...; 179 __cs3_argv = ...; 180}</pre><p> 181 182 The constructor function must be named 183 <code class="function">__cs3_init_args</code>, since some 184 profiles provide a default definition of this function. 185 </p><p> 186 If definitions of <code class="varname">__cs3_argc</code> and 187 <code class="varname">__cs3_argv</code> are not provided, then the default 188 <code class="function">__cs3_start_c</code> function invokes 189 <code class="function">main</code> with zero as the <code class="varname">argc</code> 190 argument and a null pointer as <code class="varname">argv</code>. 191 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm46915333543600"></a>5.2.5.�Program Termination</h3></div></div></div><p> 192 A program running on an embedded system is usually designed 193 never to exit — it runs until the system is powered down. 194 The C and C++ standards leave it unspecified 195 as to whether <code class="function">exit</code> is called at program 196 termination. If the program never exits, then there is no 197 reason to include <code class="function">exit</code>, facilities to run 198 functions registered with <code class="function">atexit</code>, or global 199 destructors. This code would never be run and would therefore 200 just waste space in the application. 201 </p><p> 202 The CS3 startup code, by itself, does not cause 203 <code class="function">exit</code> to be present in the application. It 204 dynamically checks whether <code class="function">exit</code> is present, 205 and only calls it if it is. If you require 206 <code class="function">exit</code> to be present, either refer to it 207 within your application, or add <code class="option">-Wl,-u,exit</code> to 208 the linking command line. 209 </p><p> 210 Similarly, code to register global destructors is only invoked 211 when <code class="function">atexit</code> is already in the executable; 212 CS3, by itself, does not cause <code class="function">atexit</code> to be 213 present. If you require <code class="function">atexit</code>, either 214 refer to it within your application, or add 215 <code class="option">-Wl,-u,atexit</code> to the linking command line. 216 </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> 217