<!-- {{{ Banner                         --><!-- =============================================================== --><!--                                                                 --><!--     programming.sgml                                            --><!--                                                                 --><!--     eCos User Guide                                             --><!--                                                                 --><!-- =============================================================== --><!-- ####COPYRIGHTBEGIN####                                          --><!--                                                                 --><!-- =============================================================== --><!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  --><!-- Copyright (C) 2003 Nick Garnett                                 --><!-- This material may be distributed only subject to the terms      --><!-- and conditions set forth in the Open Publication License, v1.0  --><!-- or later (the latest version is presently available at          --><!-- http://www.opencontent.org/openpub/)                            --><!-- Distribution of the work or derivative of the work in any       --><!-- standard (paper) book form is prohibited unless prior           --><!-- permission obtained from the copyright holder                   --><!-- =============================================================== --><!--                                                                 -->      <!-- ####COPYRIGHTEND####                                            --><!-- =============================================================== --><!-- #####DESCRIPTIONBEGIN####                                       --><!--                                                                 --><!-- ####DESCRIPTIONEND####                                          --><!-- =============================================================== --><!-- }}} --><part ID="user-guide-programming"><TITLE>Programming With <productname>eCos</productname></TITLE><CHAPTER ID="PROGRAMMING-WITH-ECOS"><TITLE>Programming With <productname>eCos</productname></TITLE><PARA>The following chapters of this manual comprise a simple tutorialfor configuring and building <productname>eCos</productname>, building and running <productname>eCos</productname> tests,and finally building three stand-alone example programs which usethe  <productname>eCos</productname> API to perform some simple tasks.</PARA><PARA>You will need a properly installed <productname>eCos</productname> system, with the correctversions of the GNU toolchain.<!-- <conditionaltext> --> On Windowsyou will be using the bash command line interpreter that comes withCygwin, with the environment variables set as described in thetoolchain documentation.</PARA><SECT1 id="development-process"><TITLE>The Development Process</TITLE><PARA>Most development projects using <productname>eCos</productname> would contain some (ormost) of  the following:</PARA><SECT2><TITLE><productname>eCos</productname> Configuration</TITLE><PARA><productname>eCos</productname> is configured to provide the desired API (the inclusionof libc, uitron, and the disabling of certain undesired funtions,etc.), and semantics (selecting scheduler, mutex behavior, etc.).See <XREF LINKEND="CONFIGURING-AND-BUILDING-ECOS-FROM-SOURCE">.</PARA><PARA>It would normally make sense to enable <productname>eCos</productname> assertion checkingat this time as well, to catch as many programming errors duringthe development phase as possible.</PARA><PARA>Note that it should not be necessary to spend much time on<productname>eCos</productname> configuration initially. It may be important to perform finetuning to reduce the memory footprint and to improve performancelater when the product reaches a testable state.</PARA></SECT2><SECT2><TITLE>    Integrity check of the <productname>eCos</productname> configuration</TITLE><PARA>While we strive to thoroughly test <productname>eCos</productname>, the vast numberof configuration permutations mean that the particular configurationparameters used for your project may not have been tested. Therefore,we advise running the <productname>eCos</productname> tests after the project's<productname>eCos</productname> configuration has been determined. See <XREF LINKEND="RUNNING-AN-ECOS-TEST-CASE">.</PARA><PARA>Obviously, this should be repeated if the configuration changeslater on in the development process.</PARA></SECT2><SECT2><TITLE>    Application Development - Target Neutral Part</TITLE><PARA>While your project is probably targeting a specific architectureand platform, possibly custom hardware, it may be possible to performpart of the application development using simulated or synthetictargets.</PARA><PARA>There are three good reasons for doing this:</PARA><ITEMIZEDLIST><LISTITEM><PARA>It may be possible by this means to perform applicationdevelopment in parallel with the design/implementationof the target hardware, thus providing more time for developingand testing functionality, and reducing time-to-market.</PARA></LISTITEM><LISTITEM><PARA>The build-run-debug-cycle may be faster when the applicationdoes not have to be downloaded to a target via a serial interface.Debugging is also likely to be more responsive when you do not have toto communicate with the remote GDB stubs in RedBoot via serial. Italso removes the need for manually or automatically resetting thetarget hardware.</PARA></LISTITEM><listitem><para>New hardware can often be buggy. Comparing the behaviour of theprogram on the hardware and in the simulator or synthetic target mayallow you to identify where the problems lie.</para></listitem></ITEMIZEDLIST><PARA>This approach is possible because all targets (includingsimulators and synthetic ones) provide the same basic API: thatis, kernel, libc, libm, uitron, infra, and to some extent, HAL andIO.</PARA><PARA>Synthetic targets are especially suitable as they allow youto construct simulations of elaborate devices by interaction withthe host system, where an IO device API can hide the details fromthe application. When switching to hardware later in the developmentcycle, the IO driver is properly implemented.</para><para>Simulators can also do this, but it all depends on thedesign and capabilities of the simulator you use. Some, like<ULINK URL="http://sources.redhat.com/sid">SID</ULINK> or<ULINK URL="http://bochs.sourceforge.net/">Bochs</ULINK> providecomplete hardware emulation, while others just support enough of theinstruction set to run compiled code.</PARA><PARA>Therefore, select a simulator or synthetic target and useit for as long as possible for application development. That is,configure for the selected target, build <productname>eCos</productname>, build the applicationand link with <productname>eCos</productname>, run and debug. Repeat the latter two steps untilyou are happy with it.</PARA><PARA>Obviously, at some time you will have to switch to the intendedtarget hardware, for example when adding target specific featuresupport, for memory footprint/performance characterization,and for final tuning of <productname>eCos</productname> and the application.</PARA></SECT2><SECT2><TITLE>    Application Development - Target Specific Part</TITLE><PARA>Repeat the build-run-debug-cycle while performing final tuningand debugging of application. Remember to disable <productname>eCos</productname> assertionchecking if you are testing any performance-related aspects, it canmake a big difference.</PARA><PARA>It may be useful to switch between this and the previous steprepeatedly through the development process; use the simulator/synthetictarget for actual development, and use the target hardware to continuallycheck memory footprint and performance. There should be little costin switching between the two targets when using two separate buildtrees. </PARA></SECT2></SECT1></CHAPTER><!-- ==================================================== --><CHAPTER ID="CONFIGURING-AND-BUILDING-ECOS-FROM-SOURCE"><!-- <conditionaltext> --><TITLE><!-- <xref> --><!-- <index></index> -->Configuring and Building <productname>eCos</productname> from Source</TITLE><PARA>This chapter documents the configuration of <productname>eCos</productname>. The process isthe same for any of the supported targets: you may select ahardware target (if you have a board available), any one of thesimulators, or a synthetic target (if your host platform has synthetictarget support).</PARA><!-- ==================================================== --><SECT1 id="ecos-startup-configs"><TITLE><!-- <xref> --><productname>eCos</productname> Start-up Configurations</TITLE><PARA>There are various ways to download an executable image to atarget board, and these involve different ways of preparing theexecutable image. In the <productname>eCos</productname> Hardware Abstraction Layer (HAL package)there are configuration options to support the different downloadmethods. <XREF LINKEND="user-guide-download-methods"> summarizes theways in which an <productname>eCos</productname> image can be prepared for different types ofdownload. This is not an exhaustive list, some targets defineadditional start-up types of their own. Where a ROM Monitor ismentioned, this will usually be RedBoot, although on some older, orlow resource, targets you may need to use CygMon or the GDB stubs ROM,see the target documentation for details.</PARA><TABLE id="user-guide-download-methods"><TITLE>Configuration for various download methods</TITLE><TGROUP COLS="2"><THEAD><ROW><ENTRY>Download method</ENTRY><ENTRY>HAL configuration</ENTRY></ROW></THEAD><TBODY><ROW><ENTRY>Burn hardware ROM</ENTRY><ENTRY>&nbsp;ROM or ROMRAM start-up</ENTRY></ROW><ROW><ENTRY>Download to ROM emulator</ENTRY><ENTRY>&nbsp;ROM or ROMRAM start-up</ENTRY></ROW><ROW><ENTRY>Download to board with ROM Monitor</ENTRY><ENTRY>&nbsp;RAM start-up</ENTRY></ROW><ROW><ENTRY>Download to simulator without ROM Monitor</ENTRY><ENTRY>&nbsp;ROM start-up</ENTRY></ROW><ROW><ENTRY>Download to simulator with ROM Monitor</ENTRY><ENTRY>&nbsp;RAM start-up</ENTRY></ROW><ROW><ENTRY>Download to simulator ignoring devices</ENTRY><ENTRY>&nbsp;SIM configuration</ENTRY></ROW><ROW><ENTRY>Run synthetic target</ENTRY><ENTRY>&nbsp;RAM start-up</ENTRY></ROW></TBODY></TGROUP></TABLE><CAUTION><PARA>You cannot run an application configured for RAM start-upon the simulator directly: it will fail during start-up. You canonly download it to the simulator ifyou are already running RedBoot in the simulator,as described in the toolchain documentationor you load through the <EMPHASIS>SID </EMPHASIS>GDB debugging component.  This is not the same as the simulatedstub, since it does not require a target program to be running toget GDB to talk to it.  It can be done before letting the simulatorrunor you use the ELF loader component to get a program into memory.</PARA></CAUTION><!-- <label> --><!-- <conditionaltext> --><!-- NOTE</label> --><NOTE><PARA>Configuring <productname>eCos</productname>' HAL package for simulation shouldrarely be needed for real development; binaries built with sucha kernel will not run on target boards at all,<!-- <conditionaltext> -->and the MN10300 andTX39 simulators can run binaries built for stdeval1 and jmr3904target boards.The main use for a ``simulation'' configurationis if you are trying to work around problems with the device driversor with the simulator.  Also note that when using a TX39 system configuredfor simulator start-up you should then invoke the simulator with the <OPTION>--board=jmr3904pal</OPTION>option instead of <OPTION>--board=jmr3904</OPTION><!-- <conditionaltext> --></PARA></NOTE><NOTE><PARA>If your chosen architecture does not have simulator support,then the combinations above that refer to the simulator do not apply.Similarly, if your chosen platform does not have RedBootROM support, the combinations listed above that use RedBoot do not apply.</PARA></NOTE><PARA>The debugging environment for most developers will be eithera hardware board or the simulator, in which case they will be ableto select a single HAL configuration.</PARA></SECT1><!-- ==================================================== --><SECT1 id="using-configtool-windows-linux"><TITLE><!-- <index></index> -->Configuration Tool on Windows and Linux Quick Start</TITLE><PARA><!-- <conditionaltext> --> This section described the GUI based configuration tool. Thistool is probably more suited to users who prefer GUI's. The nextsection describes a CLI based tool which Unix users mayprefer. </PARA><PARA>Note that the use of the <application>Configuration Tool</application>is described in detail in <XREFLINKEND="THE-ECOS-CONFIGURATION-TOOL">.</PARA><PARA>The <application>Configuration Tool</application> (see <XREF LINKEND="PROGRAMMING-FIGURE-CONFIGURATION-TOOL">)has five main elements: the <EMPHASIS>configuration window</EMPHASIS>,the <emphasis>conflicts window</emphasis>,the <EMPHASIS>properties window</EMPHASIS>, the <!-- <xref> --><EMPHASIS>shortdescription window</EMPHASIS>,and the <EMPHASIS>output window</EMPHASIS>.</PARA><FIGURE ID="PROGRAMMING-FIGURE-CONFIGURATION-TOOL"><TITLE>Configuration Tool</TITLE><!-- <xref> --><GRAPHIC ENTITYREF="programming-graphic1"></GRAPHIC></FIGURE><PARA>Start by opening the templates window via <GUIMENUITEM>Build-&#62;Templates</GUIMENUITEM>.Select the desired target (see <XREF LINKEND="FIGURE-TEMPLATE-SELECTION">).</PARA><FIGURE ID="FIGURE-TEMPLATE-SELECTION"><TITLE>Template selection</TITLE><!-- <xref> --><GRAPHIC ENTITYREF="programming-graphic2"></GRAPHIC></FIGURE><PARA>Make sure that the configuration is correct for the targetin terms of endianness, CPU model, Startup type, etc. (see <XREF LINKEND="CONFIGURING-FOR-THE-TARGET">).</PARA>