programming.sgml

开放源码实时操作系统源码.

</para>

<FIGURE id="programming-run-properties">
<TITLE>Properties dialog box</TITLE>
<GRAPHIC ENTITYREF="graphic25"></GRAPHIC>
</FIGURE>

<para>
Click OK on this dialog and go back to the <emphasis>Run
Tests</emphasis> dialog. Press the <emphasis>Run</emphasis> button and
the selected test will be downloaded and run. The
<emphasis>Output</emphasis> tab will show you how this is
progressing. If it seems to stop for a long time, check that the
target board is correctly connected, and that <productname>eCos</productname> has been correctly
configured -- especially the start-up type.
</para>

<para>
When the program runs you should see a couple of line similar to this appear:
</para>

<PROGRAMLISTING>
PASS:&lt;Binary Semaphore 0 OK&gt;
EXIT:&lt;done&gt;
</PROGRAMLISTING>

<para>
This indicates that the test has run successfully.
</para>

<PARA>See <xref linkend="config-tool-test-execution"> for
further details.</PARA>

</SECT1>

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

<SECT1 id="using-commandline-testcase">
<TITLE>Using the command line</TITLE>

<PARA>Start a command shell (such as a Cygwin shell window in Windows)
with the environment variables set as described in the toolchain
documentation.  Change to the directory in which you set up your build
tree, and invoke <!-- <index></index> --> GDB on the test
program.</PARA>

<PARA>To run the <!-- <index></index> -->bin_sem0 test (which will
test the kernel for the correct creation and destruction of binary
semaphores) type: </PARA>

<PROGRAMLISTING>
$ <replaceable>TARGET-</replaceable>gdb -nw install/tests/kernel/<replaceable>&Version;</replaceable>/tests/bin_sem0
</PROGRAMLISTING>

<PARA>You should see output similar to the following in the command
window:</PARA>

<PROGRAMLISTING>
GNU gdb THIS-GDB-VERSION
Copyright 2001 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=THIS-HOST --target=THIS-TARGET".
(gdb)
</PROGRAMLISTING>

<PARA>If you are trying to run a synthetic target test on <!--
<index></index> -->Linux, skip the following connection and download
steps. Otherwise, connect to the target by typing: </PARA>

<PROGRAMLISTING>
(gdb) set remotebaud 38400
(gdb) target remote /dev/ttyS0
</PROGRAMLISTING>
<PARA>on Linux or</PARA>
<PROGRAMLISTING>
(gdb) set remotebaud 38400
(gdb) target remote com1
</PROGRAMLISTING>
<PARA>on Windows or</PARA>
<PROGRAMLISTING>
(gdb) target sim
</PROGRAMLISTING>
<para>to use a simulator in either host O/S.</para>

<para>
Check the documentation for the target board for the actual baud rate
to use when connecting to real targets.
</para>

<PARA>
You will see output similar to the following: </PARA>

<programlisting width=72>
Remote debugging using /dev/ttyS1
0x0000d50c in ?? ()
    at <replaceable>BASE_DIR</replaceable>/kernel/<replaceable>&Version;</replaceable>/src/common/kapi.cxx:345

Current language:  auto; currently c++
(gdb) 
</programlisting>

<para>
Or if you are using the simulator:
</para>

<PROGRAMLISTING>
Connected to the simulator.
(gdb)
</PROGRAMLISTING>

<PARA>Now download the program to the target with</PARA>

<PROGRAMLISTING>
(gdb) load
</PROGRAMLISTING>

<PARA>You should see output similar to the following on your screen: </PARA>

<PROGRAMLISTING>
Loading section .text, size 0x4b04 lma 0x108000
Loading section .rodata, size 0x738 lma 0x10cb08
Loading section .data, size 0x1c0 lma 0x10d240
Start address 0x108000, load size 21500
Transfer rate: 24571 bits/sec, 311 bytes/write.
(gdb)
</PROGRAMLISTING>

<PARA>You are now ready to run your program. If you type: </PARA>

<PROGRAMLISTING>
(gdb) continue
</PROGRAMLISTING>

<PARA>you will see output similar to the following: </PARA>

<PROGRAMLISTING>
Continuing.
PASS:&lt;Binary Semaphore 0 OK&gt;
EXIT:&lt;done&gt;
</PROGRAMLISTING>

<NOTE>
<PARA> If you are using a simulator or the synthetic target rather
	    than real hardware, you must use the GDB command
	    &ldquo;run&rdquo; rather than &ldquo;continue&rdquo; to
	    start your program.</PARA>
</NOTE>

<PARA>You can terminate your GDB session with
<EMPHASIS>Control+C</EMPHASIS>, otherwise it will sit in the
&ldquo;idle&rdquo; thread and use up CPU time. This is not a problem
with real targets, but may have undesirable effects in simulated or
synthetic targets. Type <command>quit</command> and you are
done. </PARA>

</SECT1>

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

<SECT1 id="testing-filters">
<TITLE>Testing Filters</TITLE>

<PARA>While most test cases today run solely in the target environment,
some packages may require external testing infrastructure and/or
feedback from the external environment to do complete testing.</PARA>

<PARA>The serial package is an example of this. The network package
also contains some tests that require programs to be run on a
host. See the network <citetitle>Tests and Demonstrations</citetitle>
section in the network documentation in the <citetitle><productname>eCos</productname> Reference
Guide</citetitle>. Here we will concentrate on the serial tests since
these are applicable to more targets.
</para>

<PARA>Since the serial line is also used for communication with
GDB, a  filter is inserted in the communication pathway between
GDB and the serial device which is connected to the hardware target.
The filter forwards all communication between the two, but also
listens for special commands embedded in the data stream from the
target.</PARA>

<PARA>When such a command is seen, the filter stops forwarding data
to GDB from the target and enters a special mode. In this mode
the test case running on the target is able to control the filter,
commanding it to run various tests. While these tests run, GDB is
isolated from the target.</PARA>

<PARA>As the test completes (or if the filter detects a target crash)
the communication path between GDB and the hardware target is re-established,
allowing GDB to resume control.</PARA>

<PARA>In theory, it is possible to extend the filter to provide
a generic framework for other target-external testing components,
thus decoupling the testing infrastructure from the (possibly limited)
communication means provided by the target (serial, JTAG, Ethernet,
etc). </PARA>

<PARA>Another advantage is that the host tools do not need to
know about the various testing environments required by the <productname>eCos</productname>
packages, since all contact with the target continues to happen
via GDB.</PARA>

</sect1>

</CHAPTER>


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

<CHAPTER ID="BUILDING-AND-RUNNING-SAMPLE-APPLIATIONS"><!-- <conditionaltext> -->
<TITLE><!-- <xref> -->Building and <!-- <index></index> -->Running Sample Applications</TITLE>

<PARA>The example programs in this tutorial are included, along
with a <filename>Makefile</filename>, in the <filename>examples</filename> directory
of the <productname>eCos</productname> distribution. The first program you will run is a <EMPHASIS>hello
world</EMPHASIS>-style application, then you will run a more complex
application that demonstrates the creation of threads and the use
of cyg_thread_delay(), and finally you will run
one that uses clocks and alarm handlers.</PARA>

<PARA>The <filename>Makefile</filename> depends on an externally
defined variable to find the <productname>eCos</productname> library and header files. This
variable is <literal>INSTALL_DIR</literal> and must be set to the
pathname of the install directory created in <xref
linkend="using-configtool-windows-linux">.
</PARA>

<para>
<literal>INSTALL_DIR</literal> may be either be set in the shell
environment or may be supplied on the command line. To set it in the
shell do the following in a <command>bash</command> shell:
</para>

<programlisting width=72>
$ export INSTALL_DIR=BASE_DIR/ecos-work/arm_install
</programlisting>

<para>
You can then run <command>make</command> without any extra parameters
to build the examples.
</para>

<para>
Alternatively, if you can do the following:
</para>

<programlisting width=72>
$ make INSTALL_DIR=BASE_DIR/ecos-work/arm_install
</programlisting>

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

<SECT1 id="ecos-hello-world">
<TITLE><productname>eCos</productname> Hello World</TITLE>

<PARA>The following code is found in the file <FILENAME><!-- <index></index> -->hello.c</FILENAME>
in the <FILENAME>examples</FILENAME> directory: </PARA>

<SECT2>
<TITLE><productname>eCos</productname><!-- <index></index> --> hello world program listing</TITLE>

<PROGRAMLISTING>
/* this is a simple hello world program */
#include &lt;stdio.h&#62;
int main(void)
{
 printf("Hello, eCos world!\n");
 return 0;
}
</PROGRAMLISTING>

<PARA>To compile this or any other program that is not part of the
<productname>eCos</productname> distribution, you can follow the procedures described below. Type
this explicit compilation command (assuming your current working
directory is also where you built the <productname>eCos</productname> kernel):</PARA>

<PROGRAMLISTING>
$ <replaceable>TARGET-</replaceable>gcc -g -I<replaceable>BASE_DIR</replaceable>/ecos-work/install/include hello.c -L<replaceable>BASE_DIR</replaceable>/ecos-work/install/lib -Ttarget.ld -nostdlib
</PROGRAMLISTING>

<PARA>The compilation command above contains some standard GCC
options (for example, <OPTION>-g</OPTION> enables debugging), as well
as some mention of paths
(<OPTION>-I<replaceable>BASE_DIR</replaceable>/ecos-work/install/include</OPTION> allows files
like <FILENAME>cyg/kernel/kapi.h</FILENAME> to be found, and
<OPTION>-L<replaceable>BASE_DIR</replaceable>/ecos-work/install/lib</OPTION> allows the linker to
find <OPTION>-Ttarget.ld</OPTION>). </PARA>

<PARA>The executable program will be called <FILENAME>a.out</FILENAME>. </PARA>

<NOTE>
<PARA>Some target systems require special options to be passed to
gcc to compile correctly for that system. Please examine the Makefile
in the examples directory to see if this applies to your target.</PARA>
</NOTE>

<PARA>You can now run the resulting program using GDB in exactly the
same the way you ran the test case before. The procedure will be the
same, but this time run
<command><replaceable>TARGET-</replaceable>gdb</command> specifying
<option>-nw a.out</option> on the command line:</PARA>

<PROGRAMLISTING>
$ <replaceable>TARGET-</replaceable>gdb -nw a.out
</PROGRAMLISTING>

<PARA>For targets other than the synthetic linux target, you should
now run the usual GDB commands described earlier. Once this is done,
typing the command "continue" at the (gdb) prompt ("run" for
simulators) will allow the program to execute and print the string
"Hello, eCos world!" on your screen.</PARA>

<PARA>On the synthetic linux target, you may use the "run" command
immediately - you do not need to connect to the target, nor use the
"load" command.<!-- <conditionaltext> --></PARA>

</SECT2>
</SECT1>

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

<SECT1 id="sample-twothreads">
<TITLE>A Sample Program with Two Threads</TITLE>

<PARA>Below is a program that uses some of <productname>eCos</productname>' system calls. It
creates two threads, each of which goes into an infinite loop in which
it sleeps for a while (using cyg_thread_delay()).  This code is found
in the file <filename><!-- <index></index> -->twothreads.c</filename>
in the examples directory.</PARA>

<SECT2>
<TITLE><productname>eCos</productname> <!-- <index></index> -->two-threaded program listing</TITLE>