250 lines
12 KiB
Plaintext
250 lines
12 KiB
Plaintext
/*
|
|
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 <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/**
|
|
* @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.
|
|
* .
|
|
*
|
|
* <h2>What this guide does not cover</h2>
|
|
* 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
|
|
* <a href="http://forum.sparkfun.com/viewforum.php?f=18" target="_blank">
|
|
* dedicated forum</a>, 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.
|
|
*
|
|
* <h2>Article Index</h2>
|
|
* - @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
|
|
* <a href="http://cutecom.sourceforge.net/" target="_blank">CuteCom</a>.
|
|
* 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.
|
|
* <br><br>
|
|
* @image html eclipse003.jpg
|
|
* <br>
|
|
* - 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".
|
|
* <br><br>
|
|
* @image html eclipse004.jpg
|
|
* <br>
|
|
* 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.
|
|
* <br><br>
|
|
* @image html eclipse005.jpg
|
|
* <br>
|
|
* 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:
|
|
* <br><br>
|
|
* @image html eclipse006.jpg
|
|
* <br>
|
|
* The configuration dialog will appear, we must create a native Zylin
|
|
* configuration:
|
|
* <br><br>
|
|
* @image html eclipse007.jpg
|
|
* <br>
|
|
* 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:
|
|
* <br><br>
|
|
* The "Main" tab:
|
|
* @image html eclipse008.jpg
|
|
* <br><br>
|
|
* The "Debugger" tab:
|
|
* @image html eclipse009.jpg
|
|
* <br><br>
|
|
* The "Commands" tab:
|
|
* @image html eclipse010.jpg
|
|
* <br>
|
|
* 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
|
|
* <br><br>
|
|
* The "Common" tab:
|
|
* @image html eclipse011.jpg
|
|
* <br>
|
|
* 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.
|
|
* <br>**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).
|
|
* <br><br>
|
|
* @image html eclipse012.jpg
|
|
* <br>
|
|
* 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.
|
|
* <br><br>
|
|
* @image html eclipse013.jpg
|
|
* <br>
|
|
* 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.
|
|
*/
|