/* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. ChibiOS/RT is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. ChibiOS/RT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ /** * @page article_eclipse2 Embedded development using Eclipse * @brief Compiling and debugging ChibiOS/RT applications using Eclipse. * @details This article will explain how to use an Eclipse based toolchain * (see @ref article_eclipse) 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

* - @ref eclipse2_requirements * - @ref eclipse2_importing * - @ref eclipse2_creating * - @ref eclipse2_compiling * - @ref eclipse2_configuring * - @ref eclipse2_configuring_gdb * - @ref eclipse2_configuring_openocd * . * - @ref eclipse2_debugging * - @ref eclipse2_debugging_start * - @ref eclipse2_debugging_stop * . * . * * @section eclipse2_requirements Required Components * This guide requires: * - An Eclipse/GCC/OpenOCD based toolchain, as example the one described in * the article @ref article_eclipse. * - 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. * . * * @section eclipse2_importing 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. *

* @image html eclipse003.jpg *
* - 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. * . * * @section eclipse2_creating 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 @ref eclipse2_importing. * . * * @section eclipse2_compiling 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". *

* @image html eclipse004.jpg *
* 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. *

* @image html eclipse005.jpg *
* 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). * * @section eclipse2_configuring 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. * * @subsection eclipse2_configuring_gdb 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: *

* @image html eclipse006.jpg *
* The configuration dialog will appear, we must create a native Zylin * configuration: *

* @image html eclipse007.jpg *
* 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: * @image html eclipse008.jpg *

* The "Debugger" tab: * @image html eclipse009.jpg *

* The "Commands" tab: * @image html eclipse010.jpg *
* 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: * @code * 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 * @endcode *

* The "Common" tab: * @image html eclipse011.jpg *
* Now the debug configuration is complete. * * @subsection eclipse2_configuring_openocd 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** * * @section eclipse2_debugging 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. * * @subsection eclipse2_debugging_start 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). *

* @image html eclipse012.jpg *
* 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. *

* @image html eclipse013.jpg *
* 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. * * @subsection eclipse2_debugging_stop 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. */