</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>RunTests</emphasis> dialog. Press the <emphasis>Run</emphasis> button andthe selected test will be downloaded and run. The<emphasis>Output</emphasis> tab will show you how this isprogressing. If it seems to stop for a long time, check that thetarget board is correctly connected, and that <productname>eCos</productname> has been correctlyconfigured -- 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"> forfurther 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 toolchaindocumentation.  Change to the directory in which you set up your buildtree, and invoke <!-- <index></index> --> GDB on the testprogram.</PARA><PARA>To run the <!-- <index></index> -->bin_sem0 test (which willtest the kernel for the correct creation and destruction of binarysemaphores) 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 commandwindow:</PARA><PROGRAMLISTING>GNU gdb THIS-GDB-VERSIONCopyright 2001 Free Software Foundation, Inc.GDB is free software, covered by the GNU General Public License, and you arewelcome 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 downloadsteps. 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 rateto use when connecting to real targets.</para><PARA>You will see output similar to the following: </PARA><programlisting width=72>Remote debugging using /dev/ttyS10x0000d50c in ?? ()    at <replaceable>BASE_DIR</replaceable>/kernel/<replaceable>&Version;</replaceable>/src/common/kapi.cxx:345Current 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 0x108000Loading section .rodata, size 0x738 lma 0x10cb08Loading section .data, size 0x1c0 lma 0x10d240Start address 0x108000, load size 21500Transfer 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 problemwith real targets, but may have undesirable effects in simulated orsynthetic targets. Type <command>quit</command> and you aredone. </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/orfeedback from the external environment to do complete testing.</PARA><PARA>The serial package is an example of this. The network packagealso contains some tests that require programs to be run on ahost. See the network <citetitle>Tests and Demonstrations</citetitle>section in the network documentation in the <citetitle><productname>eCos</productname> ReferenceGuide</citetitle>. Here we will concentrate on the serial tests sincethese are applicable to more targets.</para><PARA>Since the serial line is also used for communication withGDB, a  filter is inserted in the communication pathway betweenGDB and the serial device which is connected to the hardware target.The filter forwards all communication between the two, but alsolistens for special commands embedded in the data stream from thetarget.</PARA><PARA>When such a command is seen, the filter stops forwarding datato GDB from the target and enters a special mode. In this modethe test case running on the target is able to control the filter,commanding it to run various tests. While these tests run, GDB isisolated 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 providea 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 toknow about the various testing environments required by the <productname>eCos</productname>packages, since all contact with the target continues to happenvia 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, alongwith a <filename>Makefile</filename>, in the <filename>examples</filename> directoryof the <productname>eCos</productname> distribution. The first program you will run is a <EMPHASIS>helloworld</EMPHASIS>-style application, then you will run a more complexapplication that demonstrates the creation of threads and the useof cyg_thread_delay(), and finally you will runone that uses clocks and alarm handlers.</PARA><PARA>The <filename>Makefile</filename> depends on an externallydefined variable to find the <productname>eCos</productname> library and header files. Thisvariable is <literal>INSTALL_DIR</literal> and must be set to thepathname of the install directory created in <xreflinkend="using-configtool-windows-linux">.</PARA><para><literal>INSTALL_DIR</literal> may be either be set in the shellenvironment or may be supplied on the command line. To set it in theshell 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 parametersto 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. Typethis explicit compilation command (assuming your current workingdirectory 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 GCCoptions (for example, <OPTION>-g</OPTION> enables debugging), as wellas some mention of paths(<OPTION>-I<replaceable>BASE_DIR</replaceable>/ecos-work/install/include</OPTION> allows fileslike <FILENAME>cyg/kernel/kapi.h</FILENAME> to be found, and<OPTION>-L<replaceable>BASE_DIR</replaceable>/ecos-work/install/lib</OPTION> allows the linker tofind <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 togcc to compile correctly for that system. Please examine the Makefilein 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 thesame the way you ran the test case before. The procedure will be thesame, 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 shouldnow run the usual GDB commands described earlier. Once this is done,typing the command "continue" at the (gdb) prompt ("run" forsimulators) 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" commandimmediately - 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. Itcreates two threads, each of which goes into an infinite loop in whichit sleeps for a while (using cyg_thread_delay()).  This code is foundin 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>