ChibiOS/RT: Embedded development using Eclipse

Compiling and debugging ChibiOS/RT applications using Eclipse.

This article will explain how to use an Eclipse based toolchain (see Setting up a free embedded IDE) to develop ChibiOS/RT based applications. This guide will allow you to:

Importing ChibiOS/RT demos into the Eclipse environment.
Edit and reformat your source code.
Compile and examine errors and warnings.
Upload your program on the target board.
Debug your code on the target board both in high level language and assembler.
Develop embedded applications with or without ChibiOS/RT.

What this guide does not cover

This guide assumes knowledge in following areas:

OpenOCD setup is not covered by this guide because the setup changes depending on the JTAG probe used, the target MCU and also the target board. The guide will show the setup for a specific JTAG probe and a specific target, a valuable source for the OpenOCD setup is the dedicated forum, most questions you may have about OpenOCD have most likely already been answered there.
Hardware setup.

In general this guide is not a replacement for the Eclipse, GCC, Make, binutils, newlib, GDB, OpenOCD user manuals, the guide simply aims to give you a faster start.

Article Index

Required Components

This guide requires:

An Eclipse/GCC/OpenOCD based toolchain, as example the one described in the article Setting up a free embedded IDE.
An Olimex ARM-USB-OCD JTAG probe, this guide applies to any other ARM JTAG probe as long it is supported by OpenOCD.
An Olimex STM32-P103 target board, this guide applies to any other ARM target except for the OpenOCD setup part.
A terminal emulator for capturing the board serial output, Windows users may use Hyper Terminal, Linux and MAC OS-X users may use CuteCom. All ChibiOS/RT demos generate on the serial port a test report when a button on the target board is pressed, other demos may activate a command shell on the serial port, in both cases a terminal emulator is required.

Importing existing ChibiOS/RT demos into Eclipse

The first step is to import a project into the Eclipse environment. ChibiOS/RT demos do not include Eclipse project files but just a normal Makefile. Eclipse is able to import a Makefile project and create its own project file so this is not a problem. This is how it is done:

Open you Eclipse environment and select the workspace created into the ChibiOS/RT project directory.
From within Eclipse select "File->New->C_Project", a dialog box will show.
Select "Makefile_project->Empty_Project" in the "Project type:" box.
Select "-- Other Toolchain --" in the "Toolchains:" box.
Unselect the "Use default location" check box.
Select the demo directory using the "Browse..." button. Something like "C:\Projects\ChibiOS-RT\demos\ARMCM3-STM32F103-GCC" will appear in the "Location:" box.
In the project name box put the same name of the directory containing the demo, ARMCM3-STM32F103-GCC in this example.
Press the "Finish" button and the project will be created and shown in the "Project Explorer".
Right click on the imported project and select "Index->Rebuild", this will make Eclipse build its internal symbols database.
Repeat the above steps for each ChibiOS/RT demo you want to import in Eclipse, all the demos that have a makefile can be imported.

Creating a new ChibiOS/RT application

If you want to create a new application it is recommended that you create a Makefile project first then you can import it into eclipse using the above procedure. Makefile projects have the advantage that can be compiled everywhere even without Eclipse. Creation steps:

Create your own development directory under the ChibiOS/RT installation directory, as example "chibios/myprojects".
Copy an existing demo, of course choose a demo using your same target, under the new directory and rename it, as example "chibios/myprojects/myapplication".
Customize the Makefile if needed, usually you just need to do this if your application is composed by more than one source file. You may also want to remove the ChibiOS/RT test code from your application.
Once your makefile is ready, import the project under the Eclipse workspace using the procedure described in Importing existing ChibiOS/RT demos into Eclipse.

Compiling and Cleaning applications

Once imported, an application can be compiled by using the "Build All" in the toolbar or by right clicking on the project and selecting "Build Project". In order to clean a project (removing all the temporary and binary files) right click on the project and select "Clean Project".

The compilation result is visible as a complete log in the "Console" window, the detail of all errors an warnings is available in the "Problems" window.

The build process produces the binary files specified in the Makefile, all the ChibiOS/RT demos produce binary files named ch.elf, ch.bin and/or ch.hex. The image must be loaded on the target board in order to execute it. The build process usually creates also some other useful files containing details about the built application (usually named ch.map and ch.dmp).

Preparing for Debug

In order to debug your application a debug configuration must be created. The configuration instructs GDB (the source debugger used by Eclipse) on how to load the image, load the symbols and place the initial breakpoint in the make function. Note that GDB performs its function by connecting to a "GDB server", the DGB server implements the low level communication with the target device through the JTAG probe. In our scenario the GDB server functionality is performed by OpenOCD, this mean that OpenOCD must be running while performing a debug session within Eclipse.

Creating a GDB Debug Configuration

A target specific debug configuration is required in order to:

Establish a connection with the GDB server.
Stop and reset the target.
Upload the binary code in Flash or RAM.
Set an initial breakpoint in the main function.
Start the target (which will immediately stop on the breakpoint).

The first thing to do is to open the "Debug Configurations..." dialog:

The configuration dialog will appear, we must create a native Zylin configuration:

Now we must give the configuration a name, "ARMCM3-STM32F103-GCC (flash and run)" in this example, then setup the various configuration pages as follow:

The "Main" tab:

The "Debugger" tab:

The "Commands" tab:

Note that the "Commands" tab contains the part that changes depending on the target. The complete commands sequence (it is not fully visible in the image) for STM32 is:

 monitor soft_reset_halt
 monitor wait_halt
 monitor poll
 monitor flash probe 0
 monitor stm32x mass_erase 0
 monitor flash write_bank 0 ch.bin 0
 monitor soft_reset_halt
 symbol-file ch.elf
 thbreak main
 continue

The "Common" tab:

Now the debug configuration is complete.

Configuring and running OpenOCD

OpenOCD must be run, with appropriate parameters, before starting your debug session. Please refer to the OpenOCD documentation in order to properly launch it for your target.
**To be completed**

Debugging

Now we are ready to debug an application on the target. Note that Eclipse have a mechanism called "Perspectives", you edit and compile your source code while you are in the "C/C++ perspective" while the debugging is performed in the "Debug perspective". You can switch perspective at any time, even while there is an active debug session. If you install more of the many Eclipse extension plugins (there are thousands) you may have even more perspectives available.

Starting a Debug Session

In order to start a debugging session first make sure that OpenOCD is running then press the drop down menu on the right side of the debug icon in the toolbar (the small green bug) and select your debug configuration (we created just one but you may have multiple debug configurations in your project, as example I usually create another debug configuration that just starts the target without uploading the code).

The debugger will be initialized, you will see the operation in progress on the console then Eclipse will switch to the debug perspective and you will see your program stopped on the default breakpoint in the main function.

From there you can perform all the usual debugging tasks, set breakpoints, single step execution, variables, memory and registers inspection etc. Please refer to the Eclipse documentation about those "normal" operations. Note that if the debugging start procedure hangs then there is probably an error in your configuration or problems with the target, read the console log and/or the OpenOCD output in order to understand where the problem is.

Stopping a Debug Session

From the debug perspective press the stop button (small red square) in the debug window, the target will be stopped and you may both return to the C/C++ perspective or start it again.