<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

<article id="cdt-guide">
<artheader>
<title>Eclipse/CDT for eCos application development</title>
<author><firstname>John</firstname><surname>Dallaway</surname></author>
<copyright><year>2003, 2004, 2005, 2006, 2007</year><holder>eCosCentric Limited</holder></copyright>
<legalnotice>
<title>Documentation licensing terms</title>
<para>This material may be distributed only subject to the terms and conditions set forth in the <productname>eCosPro</productname> Software License Agreement v2.0.</para>
</legalnotice>
</artheader>

<sect1 id="cdt-guide-intro">
<title>Introduction</title>

<para>
<productname>Eclipse</productname> is an open-source framework and workbench for the implementation of Integrated Development Environments (IDEs).
<productname>CDT</productname> is a set of additional code modules (plug-ins) for the <productname>Eclipse</productname> framework which provide C/C++ editing and debugging facilities.
This document describes the process of configuring <productname>Eclipse</productname> and <productname>CDT</productname> for <productname>eCos</productname> application development.
Some familiarity with <productname>Eclipse</productname> and <productname>CDT</productname> is assumed.
More general user guides for the <productname>Eclipse</productname> workbench and for C/C++ development using <productname>CDT</productname> are accessible via the <emphasis>Help-&gt;Help Contents</emphasis> menu item within the <productname>Eclipse</productname> workbench.
</para>

<para>
<emphasis>eCosCentric</emphasis> provides modified versions of certain <productname>CDT</productname> plug-ins and additional plug-ins suitable for the building and debugging of <productname>eCos</productname> applications running on remote hardware using <productname>GDB</productname>.
Enhancements include:
</para>

<itemizedlist>
<listitem>
<para>The facility to download executable code to remote targets</para>
</listitem>
<listitem>
<para>The management of remote target communication timeouts during long downloads</para>
</listitem>
<listitem>
<para>The facility to use a BDM parallel port interface for debugging (specific targets only)</para>
</listitem>
<listitem>
<para>The robust handling of remote target communication failures</para>
</listitem>
<listitem>
<para>The presentation of eCos thread information while debugging</para>
</listitem>
<listitem>
<para>The facility to insert hardware-assisted breakpoints where supported by the GDB stub</para>
</listitem>
<listitem>
<para>The integration of GNU cross-development toolchains for C/C++ projects</para>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="cdt-guide-projects">
<title>Creating eCos application projects</title>

<para>
<productname>eCos</productname> application development requires the use of GNU toolchain components including the <productname>GCC</productname> compiler, <productname>LD</productname> linker and <productname>GDB</productname> debugger.
<productname>CDT</productname> assumes that the locations of all compilation and debugging tools are either specified absolutely within makefiles and dialog boxes or that their locations are listed in the <emphasis>PATH</emphasis> environment variable.
The <emphasis>eCosCentric</emphasis> installer will ensure that the GNU toolchain supplied with the <productname>eCosPro Developer's Kit</productname> is on the <emphasis>PATH</emphasis> when you invoke <productname>Eclipse</productname> via the appropriate <productname>eCosPro</productname> start menu item.
</para>

<para>
CDT supports the creation of both <emphasis>Managed Make</emphasis> and <emphasis>Standard Make</emphasis> C/C++ projects for <productname>eCos</productname> application development.
The use of Managed Make projects is recommended for new users. Standard Make projects provide greater flexibility for those familiar with the creation of GNU makefiles.
</para>

<sect2 id="cdt-guide-projects-managed">
<title>Managed Make projects</title>
<para>To create a new <productname>Eclipse</productname> <emphasis>Managed Make</emphasis> project for <productname>eCos</productname> application development, invoke the <emphasis>New Project</emphasis> wizard using the <emphasis>File-&gt;New-&gt;Project...</emphasis> menu item.
Select <emphasis>C Project</emphasis> or <emphasis>C++ Project</emphasis> from the tree of project types within the <emphasis>New Project</emphasis> wizard depending on whether the project will contain any C++ code.
On the next page of the wizard, enter the project name and select the <emphasis>Executable</emphasis> or <emphasis>Static Library</emphasis> project type.
Due to limitations within the GNU toolchain, the project name and project location should not contain any spaces.
Finally, select the <productname>eCos</productname> GNU toolchain for the relevant processor architecture and click <emphasis>Finish</emphasis>.
</para>

<para>
The <productname>eCos</productname> install tree containing the <productname>eCos</productname> library and header files is specified by modifying the value of the <filename>eCosInstallDir</filename> <emphasis>build variable</emphasis> within the project's <emphasis>Properties</emphasis> dialog box.
Select the project name in the <emphasis>C/C++ Projects</emphasis> view and then invoke the <emphasis>Properties</emphasis> dialog using the <emphasis>File-&gt;Properties</emphasis> menu item.
Select <emphasis>C/C++ Build-&gt;Variables</emphasis>, check the <emphasis>Show system variables</emphasis> box, select the <filename>eCosInstallDir</filename> variable and then click on the <emphasis>Edit</emphasis> button.
Specify the path to an existing <productname>eCos</productname> install tree as the value of the build variable and click <emphasis>OK</emphasis>.

You will need to repeat the above procedure for each configuration of your project.
Select a configuration using the <emphasis>Configuration</emphasis> drop-down list box near the top of the dialog box and modify the <filename>eCosInstallDir</filename> build variable appropriately.
</para>
</sect2>

<sect2 id="cdt-guide-projects-standard">
<title>Standard Make projects</title>
<para>
To create a new <productname>Eclipse</productname> <emphasis>Standard Make</emphasis> project for <productname>eCos</productname> application development, invoke the <emphasis>New Project</emphasis> wizard using the <emphasis>File-&gt;New-&gt;Project...</emphasis> menu item.
Select <emphasis>C Project</emphasis> or <emphasis>C++ Project</emphasis> from the tree of project types within the <emphasis>New Project</emphasis> wizard depending on whether the project will contain any C++ code.
On the next page of the wizard, enter the project name and select the <emphasis>Makefile project-&gt;eCos Application Project</emphasis> project type.
Due to limitations within the GNU toolchain, the project name and project location should not contain any spaces.
Finally, select the <productname>eCos</productname> GNU toolchain for the relevant processor architecture and click <emphasis>Finish</emphasis>.
</para>

<para>
The resulting project will include a <filename>Makefile</filename> file containing two makefile variables which the user should edit to adapt the makefile to a specific project:
</para>

<itemizedlist>
<listitem>
<para><emphasis>TARGET</emphasis> - the application executable file name (with no suffix) or static library filename (with <filename>.a</filename> suffix).</para>
</listitem>
<listitem>
<para><emphasis>SOURCES</emphasis> - a space-separated list of C, C++ and assembly source files (<filename>*.c *.cc *.cpp *.cxx *.S</filename>) to be built.</para>
</listitem>
</itemizedlist>

<para>
The makefile includes rules to generate and use header file dependency information automatically.
This dependency information is stored in files with a <filename>.d</filename> suffix.
</para>

<para>
The <productname>eCos</productname> install tree containing the <productname>eCos</productname> library and header files is specified by defining a <emphasis>build variable</emphasis> within the project's <emphasis>Properties</emphasis> dialog box.
Select the project name in the <emphasis>C/C++ Projects</emphasis> view and then invoke the <emphasis>Properties</emphasis> dialog using the <emphasis>File-&gt;Properties</emphasis> menu item.
Select <emphasis>C/C++ Build-&gt;Variables</emphasis> and then click on the <emphasis>Add</emphasis> button.
Enter the variable name <filename>eCosInstallDir</filename> and set the <emphasis>type</emphasis> to <emphasis>directory</emphasis> within the <emphasis>Define a new build variable</emphasis> dialog box.
Specify the path to an existing <productname>eCos</productname> install tree as the value of the build variable and click <emphasis>OK</emphasis>.
</para>

</sect2>
</sect1>

<sect1 id="cdt-guide-debugging">
<title>Debugging eCos applications</title>

<sect2 id="cdt-guide-debugging-setup">
<title>Setup</title>

<para>
Prior to debugging an <productname>eCos</productname> application, it is necessary to generate a suitable <productname>Eclipse</productname> debug configuration.
The debug configuration specifies the name of the executable file and how the contents of this file may be downloaded to the remote target and launched.
To create a debug configuration, invoke the <emphasis>Debug</emphasis> dialog box using the <emphasis>Run-&gt;Open Debug Dialog...</emphasis> menu item.
Select <emphasis>C/C++ Local Application</emphasis>, click on the <emphasis>New launch configuration</emphasis> icon to create the new configuration and then give it a meaningful name such as "ARM target on /dev/ttyS1". Then proceed with the following steps:</para>

<itemizedlist>
<listitem>
<para>On the <emphasis>Main</emphasis> tab, click on the <emphasis>Browse...</emphasis> button to select the project from which the executable file is created and then click on the  <emphasis>Search Project...</emphasis> button to select the C/C++ application executable file to be debugged.</para>
</listitem>
<listitem>
<para>On the <emphasis>Debugger</emphasis> tab, select <emphasis>gdb Remote Debugger</emphasis> as the debugger, enter the name of the GDB debugger (eg <filename>arm-elf-gdb</filename>) on the <emphasis>Main</emphasis> pane and then select the appropriate connection parameters from the <emphasis>Connection</emphasis> pane.</para>
</listitem>
</itemizedlist>

<para>
On Windows-hosted installations, it is also necessary to specify a path mapping for POSIX-style file paths before debugging.
Invoke the <emphasis>Preferences</emphasis> dialog box using the <emphasis>Window-&gt;Preferences...</emphasis> menu item and select the <emphasis>C/C++-&gt;Debug-&gt;Common Source Lookup Path</emphasis> item from the tree of preferences.
Click <emphasis>Add...</emphasis> and choose <emphasis>Path Mapping</emphasis>.
A new path mapping entry will immediately appear in the <emphasis>Common Source Lookup Path</emphasis> tree.
Click <emphasis>Edit...</emphasis> to modify this item, give the path mapping a meaningful name such as "Cygwin root" and then click <emphasis>Add...</emphasis> to specify the mapping paths.
Enter a single forward slash character ("<filename>/</filename>") as the <emphasis>Compilation path</emphasis> and browse to the <emphasis>Local file system path</emphasis> directory corresponding to the POSIX-style root directory (typically <filename>C:\cygwin</filename>).
This path mapping ensures that the POSIX-style source code references in eCos application executable files are interpreted correctly by <productname>CDT</productname>.
</para>
</sect2>

<sect2 id="cdt-guide-debugging-hardware">
<title>Hardware debuggers</title>
<para>
When using hardware debuggers such as those using a JTAG or BDM interface, it may be necessary to override the default behaviour of CDT for launching a debugging session.
For example, an external tool may be required to install code into Flash memory prior to debugging.
The eCosCentric plug-ins allow the user to perform such customisation by specifying a <emphasis>GDB command file</emphasis> on the <emphasis>Main</emphasis> pane of the <emphasis>Debug</emphasis> dialog box.
The following optional GDB macros may be defined within the GDB command file:</para>

<itemizedlist>
<listitem>
<para><emphasis>setup</emphasis> - this macro is invoked by CDT before connection to the target hardware is attempted.
Within the macro, <filename>$arg0</filename> can be used to refer to the ELF executable file which is to be debugged and <filename>$arg1</filename> will provide the connection parameters.</para>
</listitem>
<listitem>
<para><emphasis>preload</emphasis> - this macro is invoked by CDT following connection to the target and before code download.</para>
</listitem>
<listitem>
<para><emphasis>doload</emphasis> - this macro is invoked by CDT to download code to the target hardware. The presence of this macro will suppress the default CDT code download behaviour.</para>
</listitem>
<listitem>
<para><emphasis>postload</emphasis> - this macro is invoked by CDT immediately following code download to the target hardware.</para>
</listitem>
</itemizedlist>

</sect2>
</sect1>

</article>
