programming.sgml

eCos操作系统源码

<FIGURE ID="CONFIGURING-FOR-THE-TARGET">
<TITLE><!-- <conditionaltext> --><!-- <xref> -->Configuring
for the target</TITLE>
<GRAPHIC ENTITYREF="programming-graphic3"></GRAPHIC>
</FIGURE>

<PARA>Next, select the <EMPHASIS>Build-&#62;Library</EMPHASIS> menu
item to start building <productname>eCos</productname> (see <XREF
LINKEND="FIGURE-SELECTING-THE-BUILD-LIBRARY-MENU-ITEM">).  The
application will configure the sources, prepare a build tree, and
build the <FILENAME>libtarget.a</FILENAME> library, which contains the
<productname>eCos</productname> kernel and other packages.</PARA>

<FIGURE ID="FIGURE-SELECTING-THE-BUILD-LIBRARY-MENU-ITEM"><!-- <xref> -->
<TITLE>Selecting the Build Library menu item</TITLE>
<GRAPHIC ENTITYREF="programming-graphic4"></GRAPHIC>
</FIGURE>


<PARA>The <EMPHASIS>Save As</EMPHASIS> dialog box will appear, asking
you to specify a directory in which to place your save file. You
can use the default, but it is a good idea to make a subdirectory,
called <filename>ecos-work</filename> for example. </PARA>

<FIGURE>
<TITLE>Save file dialog</TITLE>
<GRAPHIC ENTITYREF="programming-graphic5"></GRAPHIC>
</FIGURE>

<PARA>The first time you build an <productname>eCos</productname> library for a specific
architecture, the <application>Configuration Tool</application> may prompt
you for the location of the appropriate build tools (including
<command>make</command> and
<command><replaceable>TARGET-</replaceable>gcc</command>) using a
<EMPHASIS>Build Tools</EMPHASIS> dialog box (as shown in <XREF
LINKEND="FIGURE-BUILD-TOOLS-DIALOG">). You can select a location from
the drop down list, browse to the directory using the
<EMPHASIS>Browse</EMPHASIS> button, or type in the location of the
build tools manually.</PARA>

<FIGURE ID="FIGURE-BUILD-TOOLS-DIALOG"><!-- <xref> -->
<TITLE>Build tools dialog</TITLE>
<GRAPHIC ENTITYREF="programming-graphic6"></GRAPHIC>
</FIGURE>

<PARA>The <application>Configuration Tool</application> may also prompt you
for the location of the user tools (such as <command>cat</command> and
<command>ls</command>) using a <emphasis>User Tools</emphasis> dialog
box (as shown in <XREF LINKEND="FIGURE-USER-TOOLS-DIALOG">). As with
the <EMPHASIS>Build Tools</EMPHASIS> dialog, you can select a location
from the drop down list, browse to the directory using the
<EMPHASIS>Browse</EMPHASIS> button, or type in the location of the
user tools manually. Note that on Linux, this will often be
unnecessary as the tools will already be on your PATH.</PARA>

<FIGURE ID="FIGURE-USER-TOOLS-DIALOG"><!-- <xref> -->
<TITLE>User tools dialog</TITLE>
<GRAPHIC ENTITYREF="programming-graphic7"></GRAPHIC>
</FIGURE>

<PARA>When the tool locations have been entered, the <application>Configuration
Tool</application> will configure the sources, prepare a build tree,
and build the <filename>libtarget.a</filename> library, which contains
the <productname>eCos</productname> kernel and other packages.</PARA>

<PARA>The output from the configuration process and the building
of <filename>libtarget.a</filename> will be shown in the output
window.</PARA>

<PARA>Once the build process has finished you will have a kernel
with other packages in <FILENAME>libtarget.a</FILENAME>. You should
now build the <productname>eCos</productname> tests for your particular configuration. </PARA>

<PARA>You can do this by selecting <EMPHASIS>Build</EMPHASIS> -&#62; <EMPHASIS>Tests</EMPHASIS>.
Notice that you could have selected <EMPHASIS>Tests</EMPHASIS> instead
of <EMPHASIS>Library</EMPHASIS> in the earlier step and it would
have built <EMPHASIS>both</EMPHASIS> the library and the tests,
but this would increase the build time substantially, and if you
do not need to build the tests it is unnecessary.</PARA>

<FIGURE>
<TITLE>Selecting the Build Tests menu item</TITLE>
<GRAPHIC ENTITYREF="programming-graphic8"></GRAPHIC>
</FIGURE>

<PARA><XREF LINKEND="RUNNING-AN-ECOS-TEST-CASE"> will guide you through running one
	    of the test cases you just built on the selected target,
	    using GDB. </PARA>
</SECT1>

<!-- ==================================================== -->

<SECT1 ID="USING-ECOSCONFIG-ON-LINUX">
<TITLE><!-- <index></index> -->
Ecosconfig on Windows and Linux Quick Start</TITLE>

<PARA>As an alternative to using the graphical
<application>Configuration Tool</application>, it is possible to
configure and build a kernel by editing a configuration file manually
and using the <command>ecosconfig</command> command. Users with a Unix
background may find this tool more suitable than the GUI tool
described in the previous section.</PARA>

<para>
Manual configuration and the <command>ecosconfig</command> command are
described in detail in <XREF LINKEND="manual-configuration">.
</para>

<para>
To use the <command>ecosconfig</command> command you need to start a
shell. In Windows you need to start a
<productname>CygWin</productname> <command>bash</command> shell, not a
DOS command line.
</para>

<!--
<para>
XXXXX Need to know whether there will be a packaged shell entry in the
start menu, and where XXXXX
</para>
-->

<PARA>The following instructions assume that the
<literal>PATH</literal> and <literal>ECOS_REPOSITORY</literal>
environment variables have been setup correctly as described in <XREF
LINKEND="user-guide-installation-linux">.  They also assume Linux
usage but equally well apply to Windows running Cygwin.</PARA>

<PARA>Before invoking <command>ecosconfig</command> you need to
choose a directory in which to work. For the purposes of this tutorial,
the default path will be <FILENAME><replaceable>BASE_DIR</replaceable>/ecos-work</FILENAME>.
Create this directory and change to it by typing: </PARA>

<PROGRAMLISTING>
$ mkdir <replaceable>BASE_DIR</replaceable>/ecos-work
$ cd <replaceable>BASE_DIR</replaceable>/ecos-work
</PROGRAMLISTING>

<PARA>To see what options can be used with <command>ecosconfig</command>,
type: </PARA>

<PROGRAMLISTING>$ ecosconfig --help</PROGRAMLISTING>

<PARA>The available packages, targets and templates may be listed
as follows:</PARA>

<PROGRAMLISTING>
$ ecosconfig list
</PROGRAMLISTING>

<PARA>Here is sample output from <command>ecosconfig</command> showing
the usage message.</PARA>

<EXAMPLE>
<TITLE>Getting <!-- <index></index> --> help from ecosconfig</TITLE>

<PROGRAMLISTING>
$ ecosconfig --help
Usage: ecosconfig [ qualifier ... ] [ command ]
  commands are:
    list                                       : list repository contents
    new TARGET [ TEMPLATE [ VERSION ] ]        : create a configuration
    target TARGET                              : change the target hardware
    template TEMPLATE [ VERSION ]              : change the template
    add PACKAGE [ PACKAGE ... ]                : add package(s)
    remove PACKAGE [ PACKAGE ... ]             : remove package(s)
    version VERSION PACKAGE [ PACKAGE ... ]    : change version of package(s)
    export FILE                                : export minimal config info
    import FILE                                : import additional config info
    check                                      : check the configuration
    resolve                                    : resolve conflicts
    tree                                       : create a build tree
  qualifiers are:
    --config=FILE                              : the configuration file
    --prefix=DIRECTORY                         : the install prefix
    --srcdir=DIRECTORY                         : the source repository
    --no-resolve                               : disable conflict
resolution
    --version                                  : show version and copyright
$
</PROGRAMLISTING>
</EXAMPLE>

<EXAMPLE>

<TITLE>ecosconfig output &mdash; <!-- <index></index> -->
list of available packages, targets and templates</TITLE>

<PROGRAMLISTING>
$ ecosconfig list
Package CYGPKG_CYGMON (CygMon support via eCos): 
aliases: cygmon 
versions: &Version; 
Package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1742 (Wallclock driver for Dallas 1742): 
aliases: devices_wallclock_ds1742 device_wallclock_ds1742 
versions: &Version; 
Package CYGPKG_DEVICES_WALLCLOCK_SH3 (Wallclock driver for SH3 RTC module): 
aliases: devices_wallclock_sh3 device_wallclock_sh3 
versions: &Version; 
Package CYGPKG_DEVICES_WATCHDOG_ARM_AEB (Watchdog driver for ARM/AEB board): 
aliases: devices_watchdog_aeb device_watchdog_aeb 
versions: &Version; 
Package CYGPKG_DEVICES_WATCHDOG_ARM_EBSA285 (Watchdog driver for ARM/EBSA285 board): 
aliases: devices_watchdog_ebsa285 device_watchdog_ebsa285 
versions: &Version; 
&hellip;
</PROGRAMLISTING>
</EXAMPLE>


<SECT2>
<TITLE>Selecting a <!-- <index></index> --> Target</TITLE>

<PARA>To configure for a listed target, type: </PARA>

<PROGRAMLISTING>
$ ecosconfig new &lt;target&#62;
</PROGRAMLISTING>

<PARA>For example, to configure for the ARM PID development board,
type: </PARA>

<PROGRAMLISTING>
$ ecosconfig new pid
</PROGRAMLISTING>

<PARA>You can then edit the generated file,
<FILENAME>ecos.ecc</FILENAME>, setting the options as required for the
target (endianess, CPU model, Startup type, etc.).  For detailed
information about how to edit the <filename>ecos.ecc</filename> file,
see the <citetitle>CDL Writer's Guide</citetitle> and <XREF
LINKEND="editing-an-ecos-savefile">.
</PARA>

<PARA>Create a build tree for the configured target by typing:</PARA>

<PROGRAMLISTING>
$ ecosconfig tree
</PROGRAMLISTING>

<para>
If there are any problem with the configuration,
<command>ecosconfig</command> will tell you. The most likely cause of
this is mistakes when editing the <filename>ecos.ecc</filename> file.
You can check whether the configuration you have made is correct,
without building the tree with the following command:
</para>

<PROGRAMLISTING>
$ ecosconfig check
</PROGRAMLISTING>

<para>
If this reports any conflicts you can get
<command>ecosconfig</command> to try and resolve them itself by typing:
</para>

<PROGRAMLISTING>
$ ecosconfig resolve
</PROGRAMLISTING>

<para>
See <XREF LINKEND="conflicts-and-constraints"> for more details.
</para>

<PARA>You can now run the command <command>make</command> or <command>make
tests</command>, after which you will be at the same point you
would be after running the <application>Configuration Tool</application>
&mdash; you can start developing your own applications,
following the steps in <XREF LINKEND="BUILDING-AND-RUNNING-SAMPLE-APPLIATIONS">. </PARA>

<PARA>The procedure shown above allows you to do very coarse-grained
configuration of the <productname>eCos</productname> kernel: you can select which packages
to include in your kernel, and give target and start-up options.
But you cannot select components within a package, or set the very
fine-grained options. </PARA>

<PARA>To select fine-grained configuration options you will need to
edit the configuration file <filename>ecos.ecc</filename> in the
current directory and regenerate the build tree.</PARA>

<CAUTION>
<PARA>You should follow the manual configuration process described
above very carefully, and you should read the comments in each file
to see when one option depends on other options or packages being
enabled or disabled. If you do not, you might end up with an inconsistently
configured kernel which could fail to build or might execute
incorrectly.</PARA>
</CAUTION>

</SECT2>
</SECT1>

</CHAPTER>

<!-- ==================================================== -->

<CHAPTER ID="RUNNING-AN-ECOS-TEST-CASE">
<TITLE>Running an <productname>eCos</productname> Test Case</TITLE>

<PARA>In <XREF LINKEND="using-configtool-windows-linux"> or <XREF
LINKEND="using-ecosconfig-on-linux"> you created the <productname>eCos</productname> test cases
as part of the build process. Now it is time to try and run one.
</para>

<!-- ==================================================== -->

<SECT1 id="using-configtool-testcase">
<TITLE>Using the <application>Configuration Tool</application></TITLE>

<PARA>Test executables that have been linked using the
<emphasis>Build-&gt;Tests</emphasis> operation against the current
configuration can be executed by selecting <EMPHASIS>Tools-&#62;Run
Tests</EMPHASIS>.</PARA>

<PARA>When a test run is invoked, a property sheet is displayed, see
<xref linkend="programming-run-tests">. Press the <emphasis>Uncheck
All</emphasis> button and then find and check just one test,
<filename>bin_sem0</filename> for example.
</para>

<FIGURE id="programming-run-tests">
<TITLE>Run tests</TITLE>
<GRAPHIC ENTITYREF="graphic27"></GRAPHIC>
</FIGURE>

<para>
Now press the <emphasis>Properties</emphasis> button to set up
communications with the target. This will bring up a properties dialog
shown in <xref linkend="programming-run-properties">. If you have
connected the target board via a serial cable, check the
<emphasis>Serial</emphasis> radio button, and select the serial port
and baud rate for the board. If the target is connected via the
network select the <emphasis>TCP/IP</emphasis> button and enter the IP
address that the board has been given, and the port number (usually
9000).