Code Confidence technical note 0002 - Debugging eCos applications using QEMU

This technical note describes use of the QEMU emulator for the debugging of eCos® applications. QEMU enables experimentation with eCos and eCos application development without access to target hardware. Two debugging techniques are presented. Both techniques are intended to be used with eCos i386 PC platform support and should work on both Linux® and Windows® hosts.

The first technique involves running RedBoot™ within QEMU and using the GDB stubs built into RedBoot to download application code and control execution. This technique is relatively easy to implement and provides a debugging environment similar to that of a standalone PC target connected via ethernet to the development host.

The second technique involves building the eCos application as a bootable image and using the GDB server built into QEMU to control execution. This technique provides a more robust debugging environment similar to that of a JTAG debugger where execution can be interrupted and target state inspected regardless of any issues with the application software.

Most recent Linux distributions include a QEMU package. Please refer to your distribution documentation for installation details. Users of Microsoft Windows are recommended to download a lite build of QEMU from Eric Lassauge's site:

At the time of writing, the latest version available from this site was

Using QEMU with Redboot

In order to debug eCos applications via Redboot within QEMU, it is necessary to build a bootable RedBoot image which includes the GDB stubs. For performance reasons, use of the emulated RTL8139 ethernet device for communication with GDB is recommended. An eCos configuration based on the pc_rltk8139 hardware template and the redboot packages template should therefore be created. The redboot_FLOPPY.ecm minimal configuration file should then be imported into the configuration. For convenience, the following RedBoot image (built from eCos 3.0 sources) may be used:

The relevant QEMU command line parameters for running the image within this zip file are as follows:

    -boot a -fda redboot-rtl8139-fda.bin -net nic,model=rtl8139 -net user -redir tcp:9001::9000

These parameters instruct QEMU to boot using the RedBoot image and to redirect GDB connection requests at port 9001 on the development host to port 9000 (RedBoot) within the emulated PC. eCos diagnostic output is directed to the debug port by default and presented in the GDB console window.

Before launching a debugging session, Eclipse must be configured to run QEMU as an external tool. Invoke the External Tools Configurations dialog using the External ToolsExternal Tools Configurations... menu item in the Run menu of the Eclipse workbench and create an external tool configuration as shown in the following screenshot:

Configuring QEMU as an external tool (click to zoom)

Debugging of eCos applications may be achieved by first launching (or re-launching) the QEMU RedBoot external tool and then launching a debug session, specifying TCP connection parameters appropriate for QEMU in the application's launch configuration as follows:

Specifying launch parameters for QEMU (click to zoom)

Using QEMU with a bootable eCos application image

In order to debug bootable eCos applications within QEMU, an eCos configuration based on the pc_rltk8139 hardware template should be used. The eCos Startup type (CYG_HAL_STARTUP) must then be customised, specifying type "FLOPPY" or "GRUB". For the purpose of illustration, we will assume CYG_HAL_STARTUP == "FLOPPY" since this allows a disk image suitable for QEMU to be generated very easily. Note, however, that the use of the "FLOPPY" startup type limits available RAM on the target PC to 640 KiB.

Once the eCos application has been built, a disk image of the correct size must be generated from the ELF executable file. When using the "FLOPPY" startup type, the following command may be used:

    i386-elf-objcopy -O binary --pad-to=0x16b000 executable-file ecos-fda.bin

When building an eCos application using a standard makefile, the above command should be added to the makefile as a final build step. When using a managed eCos application project, the command may be specified as a post-build step within the project properties dialog as follows:

Building a bootable image for QEMU (click to zoom)

Note that the padding parameter represents the load address (LMA) of the eCos application (specified by the linker script) plus the required length of the disk image (1440 KiB). The resulting disk image file (ecos-fda.bin) must be 1474560 bytes in length.

Before launching a debugging session, Eclipse must be configured to run QEMU as an external tool with the following parameters:

    -boot a -fda ecos-fda.bin -net nic,model=rtl8139 -net user -s -S -serial tcp::9003,server,nowait

These parameters instruct QEMU to wait for a GDB connection request at port 1234 on the development host. The eCos application itself is started from within the Eclipse debugging session. eCos diagnostic output is directed to serial port 0 by default. The final parameters of the QEMU command line allow this output to be viewed using a telnet session to port 9003 on the development host.

When using the GDB server built in to QEMU, thread-aware debugging of eCos applications may be achieved using Code Confidence™ ThreadSpy™ technology. Create a Remote eCos Application launch configuration using the Code Confidence Tools, specifying host name localhost and port 1234 as the remote target connection parameters. In the typical case where the eCos i386 architectural configuration options are unmodified, ThreadSpy may be configured as follows:

    monitor threadspy -EL --regs=0x04,0x1c,0x04 --regs=0x08,0x18,0x04 --regs=0x0c,0x14,0x04 --regs=0x10,0x10,0x04 --regs=0x14,0x0c,0x04 --regs=0x18,0x08,0x04 --regs=0x1c,0x04,0x04 --regs=0x20,0x00,0x04 --regs=0x28,0x20,0x04 --regs=0x2c,0x28,0x04 --regs=0x30,0x24,0x04

Note that it is not necessary to use a GDB load command within the launch sequence since the application image is loaded into the emulated PC by QEMU. Back…


2016-08-05 : Code Confidence announces tools update for eCos -- based on Eclipse Neon IDE. More…
2016-07-15 : Code Confidence Tools for FreeRTOS updated for Eclipse Neon IDE. More…
2015-10-02 : Hard fault exception decoding added to Code Confidence Tools for FreeRTOS. More…
2012-11-19 : Lauterbach TRACE32 PowerTools validation with Code Confidence Tools for eCos. More…