<!-- {{{ 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 tutorial
for configuring and building <productname>eCos</productname>, building and running <productname>eCos</productname> tests,
and finally building three stand-alone example programs which use
the  <productname>eCos</productname> API to perform some simple tasks.</PARA>

<PARA>You will need a properly installed <productname>eCos</productname> system, with the correct
versions of the GNU toolchain.<!-- <conditionaltext> --> On Windows
you will be using the bash command line interpreter that comes with
Cygwin, with the environment variables set as described in the
toolchain documentation.</PARA>

<SECT1 id="development-process">
<TITLE>The Development Process</TITLE>

<PARA>Most development projects using <productname>eCos</productname> would contain some (or
most) of  the following:</PARA>

<SECT2>
<TITLE><productname>eCos</productname> Configuration</TITLE>

<PARA><productname>eCos</productname> is configured to provide the desired API (the inclusion
of 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 checking
at this time as well, to catch as many programming errors during
the 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 fine
tuning to reduce the memory footprint and to improve performance
later 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 number
of configuration permutations mean that the particular configuration
parameters 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 changes
later on in the development process.</PARA>
</SECT2>

<SECT2>
<TITLE>    Application Development - Target Neutral Part</TITLE>

<PARA>While your project is probably targeting a specific architecture
and platform, possibly custom hardware, it may be possible to perform
part of the application development using simulated or synthetic
targets.</PARA>

<PARA>There are three good reasons for doing this:</PARA>

<ITEMIZEDLIST>

<LISTITEM>
<PARA>It may be possible by this means to perform application
development in parallel with the design/implementation
of the target hardware, thus providing more time for developing
and testing functionality, and reducing time-to-market.</PARA>
</LISTITEM>

<LISTITEM>
<PARA>The build-run-debug-cycle may be faster when the application
does 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 to
to communicate with the remote GDB stubs in RedBoot via serial. It
also removes the need for manually or automatically resetting the
target hardware.</PARA>
</LISTITEM>

<listitem>
<para>
New hardware can often be buggy. Comparing the behaviour of the
program on the hardware and in the simulator or synthetic target may
allow you to identify where the problems lie.
</para>
</listitem>

</ITEMIZEDLIST>

<PARA>This approach is possible because all targets (including
simulators and synthetic ones) provide the same basic API: that
is, kernel, libc, libm, uitron, infra, and to some extent, HAL and
IO.</PARA>

<PARA>Synthetic targets are especially suitable as they allow you
to construct simulations of elaborate devices by interaction with
the host system, where an IO device API can hide the details from
the application. When switching to hardware later in the development
cycle, the IO driver is properly implemented.
</para>

<para>
Simulators can also do this, but it all depends on the
design 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> provide
complete hardware emulation, while others just support enough of the
instruction set to run compiled code.
</PARA>

<PARA>Therefore, select a simulator or synthetic target and use
it for as long as possible for application development. That is,
configure for the selected target, build <productname>eCos</productname>, build the application
and link with <productname>eCos</productname>, run and debug. Repeat the latter two steps until
you are happy with it.</PARA>

<PARA>Obviously, at some time you will have to switch to the intended
target hardware, for example when adding target specific feature
support, 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 tuning
and debugging of application. Remember to disable <productname>eCos</productname> assertion
checking if you are testing any performance-related aspects, it can
make a big difference.</PARA>

<PARA>It may be useful to switch between this and the previous step
repeatedly through the development process; use the simulator/synthetic
target for actual development, and use the target hardware to continually
check memory footprint and performance. There should be little cost
in switching between the two targets when using two separate build
trees. </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 is
the same for any of the supported targets: you may select a
hardware target (if you have a board available), any one of the
simulators, or a synthetic target (if your host platform has synthetic
target 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 a
target board, and these involve different ways of preparing the
executable image. In the <productname>eCos</productname> Hardware Abstraction Layer (HAL package)
there are configuration options to support the different download
methods. <XREF LINKEND="user-guide-download-methods"> summarizes the
ways in which an <productname>eCos</productname> image can be prepared for different types of
download. This is not an exhaustive list, some targets define
additional start-up types of their own. Where a ROM Monitor is
mentioned, this will usually be RedBoot, although on some older, or
low 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-up
on the simulator directly: it will fail during start-up. You can
only download it to the simulator if
you are already running RedBoot in the simulator,
as described in the toolchain documentation
or you load through the 
<EMPHASIS>SID </EMPHASIS>
GDB debugging component.  This is not the same as the simulated
stub, since it does not require a target program to be running to
get GDB to talk to it.  It can be done before letting the simulator
run
or 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 should
rarely be needed for real development; binaries built with such
a kernel will not run on target boards at all,<!-- <conditionaltext> -->
and the MN10300 and
TX39 simulators can run binaries built for stdeval1 and jmr3904
target boards.
The main use for a ``simulation'' configuration
is if you are trying to work around problems with the device drivers
or with the simulator.  Also note that when using a TX39 system configured
for 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 RedBoot
ROM support, the combinations listed above that use 
RedBoot do not apply.</PARA>
</NOTE>

<PARA>The debugging environment for most developers will be either
a hardware board or the simulator, in which case they will be able
to 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. This
tool is probably more suited to users who prefer GUI's. The next
section describes a CLI based tool which Unix users may
prefer. </PARA>

<PARA>Note that the use of the <application>Configuration Tool</application>
is described in detail in <XREF
LINKEND="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>short
description 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 target
in terms of endianness, CPU model, Startup type, etc. (see <XREF LINKEND="CONFIGURING-FOR-THE-TARGET">).</PARA>