Chapter 3. Debugging eCos applications

The eCosPro New Project Wizard also enables you to set up a launch configuration. The wizard offers to take connection details for your hardware target; if they are not provided at project creation time, you will be prompted for them when you first launch your project.

Should you wish to add a (further) launch configuration later, an option to do this has been provided in the eCos menu.


Launching a debug session to a remote target, particularly when connected over a serial line can be prone to spurious errors. Be sure to allow sufficiently long time between resetting your hardware target board and starting a debug session from Eclipse.


If using a GNU toolchain from an eCosPro release prior to 3.1, and connecting to a board by serial line on Windows, be sure to enter a “Cygwin-style” device name. For example, if the target was connected to Windows serial port COM4, enter the target device as /dev/com4. For GNU toolchains supplied with eCosPro 3.1 and later, you should select the Windows name for the device as normal.

If you need to follow execution of a thread into the eCos kernel or any eCos/eCosPro packages or libraries, you are advised to link your application against an eCos configuration project that has been built with optimizations turned off. To turn off optimizations, edit the CYGBLD_GLOBAL_CFLAGS setting in the eCos configuration and change the -O2 flag to -O0. For additional debug support, developers are also encouraged to add the CYGPKG_INFRA_DEBUG package to the eCos configuration and enable it.

Debug launch walkthrough

These steps follow on from the Project Creation walkthrough, showing how one might go on to use an Eclipse debug session to launch a sample Hello World application.


These steps assume that RedBoot or GDB stubs have already been installed on your hardware.

  1. Select the project to launch (myproject) in the Project Explorer view.

  2. Hover the mouse over the Debug toolbar button for a few seconds. Verify that the popup helptext shows “Debug myproject debug” and press the button.


    If you have multiple projects or multiple launch configurations this may not be the case. You can manually select the debug configuration to launch with the drop-down portion of the Debug button, or via the Debug Configurations dialog (accessed via the Run menu).

  3. Eclipse notes that you have not yet configured the connection settings for the target and prompts you to supply them as illustrated in Figure 3.1, “Edit launch configuration properties”.

    Figure 3.1. Edit launch configuration properties

    Edit launch configuration properties

  4. If you are connecting via ethernet to RedBoot on the platform or a hardware debugger, you should select TCP for the Type and specify the IP address or host name and Port number of RedBoot or the hardware debugger. The default Port number of RedBoot is 9000. Please refer to the manufacturer's documentation for information on setting up the IP address and the GDB port number of your hardware debugger.

    If you are connecting via serial to RedBoot or GDB stubs on the platform, you should select Serial for the Type and specify the Device and Speed (baud rate) used by RedBoot or the GDB stubs. For Windows hosts, the device may be COMn, while for Linux platforms this should be the full path of your serial device (e.g. /dev/ttyUSBn).

  5. Press OK. The debug launch continues and the binary is downloaded to the target. You may view the more detailed Progress tab by double-clicking on the Progress bar circled in red in Figure 3.2, “Debug Download Progress”. If you are prompted to switch to the Debug perspective, select Yes. Eclipse opens the Debug perspective and, if you left that option enabled, stops at main().

    Figure 3.2. Debug Download Progress

    Debug Download Progress


    If main() is not the entry point for your own application, it is best to disable that option. If no user-supplied main() is provided, a default eCos one will be used, which will cause your application to be stopped by a breakpoint when it runs, even though that will have no significance to your application. If you are not using main(), consider removing the CYGPKG_LIBC_STARTUP package from your eCos configuration.

  6. If you stopped at main(), press the Resume toolbar button. Execution continues; on most hardware targets the output, your Hello World message, is sent over the board's debug channel and is reported in the Console view as illustrated in Figure 3.3, “Debug Download Execution”.

    Figure 3.3. Debug Download Execution

    Debug Download Execution

GDB command files

If necessary, it is possible to override the normal launch behaviour by providing macros in a gdb command (“gdbinit”) file. The path to the file is specified on the Main sub-tab of the Debugger panel of the debug configuration dialog, as illustrated in Figure 3.4, “Specify GDB command file”.

Figure 3.4. Specify GDB command file

Specify GDB command file

The following macros will, if present, be invoked during launch:

  • setup : this macro is invoked before connection to the target hardware is attempted. Within the macro, $arg0 can be used to refer to the ELF executable file which is to be debugged and $arg1 will provide the connection parameters. (The connection parameters are in the correct format for the command "target remote $arg1".)

  • preload : this macro is invoked by CDT following connection to the target and before code download.

  • doload : this macro is invoked by CDT to download code to the target hardware.


    If the doload macro is present, the internal commands which would normally download the code onto the target are suppressed.

  • postload : this macro is invoked by CDT immediately following code download to the target hardware.

An example gdb command (“gdbinit”) file that resets a target being debugged using the OpenOCD Hardware Debugger before downloading the executable is given below:

define preload
monitor reset halt

Hardware-assisted debugging

If you wish to interactively debug an application built to execute in flash memory, or a RAM-based application operating without RedBoot or GDB stubs, you must normally use a hardware debugger such as the Ronetix PEEDI. Most hardware debuggers present a GDB protocol interface and so may be used in the same way as RedBoot or GDB stubs on a target board, but with the following differences:

  • Hardware debuggers generally do not provide thread-level debugging information. You will not be able to browse the list of active threads - indeed, your application will appear to consist of a single thread no matter how many it has - and you cannot make a breakpoint thread-specific.

  • Console output from functions like diag_printf() or when outputting to the /dev/haldiag or /dev/ttydiag devices from within eCos will not be displayed in the Eclipse console. The destination of the output depends on the specific platform port, but in many cases it will come from an RS232 serial device, if available.

  • Applications executing from flash memory cannot use ordinary (“soft”) breakpoints; they can only use hardware breakpoints.

  • Hardware breakpoints are set in essentially the same way as soft breakpoints, that is by right-clicking in the ruler of a source code window. To set a hardware breakpoint, first select C/C++ Hardware Breakpoints from the Breakpoint Type submenu, then select Toggle Breakpoint as before.


    Most targets are limited in the number of hardware breakpoints they support, and such limits are not automatically reported to gdb or to Eclipse. If you attempt set too many, your debug session is likely to become confused. If you know the limit for your target, you can provide a limit in a GDB command file (see the previous section) with the command:

    set remote hardware-watchpoint-limit N


    If you run out of hardware breakpoints unexpectedly, look for and disable the option to Automatically stop on main at startup in the debugger config panel.

  • Some hardware debuggers provide settings in their configuration files which allow developers to map requests for software breakpoints into hardware breakpoints. If you have trouble setting the type of breakpoint you expected, be sure to also check the settings in the hardware debugger's configuration file. For example, with the Ronetix PEEDI, it is configured with the CORE0_BREAKMODE directive which may be set to either soft or hard.

  • Some hardware debuggers, like OpenOCD, may require that you reset and halt the target before downloading the executable to the target. This can be achieved using the preload macro within a GDB command file (see the previous section).