1 files changed, 203 insertions, 0 deletions
diff --git a/docs/src/eclipse2.dox b/docs/src/eclipse2.dox
new file mode 100644
index 000000000..18c4d565a
--- /dev/null
+++ b/docs/src/eclipse2.dox
@@ -0,0 +1,203 @@
+/*
+    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).
+ * .
+ * **To be completed**
+ *
+ * @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>
+ * 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.
+ *
+ * @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.
+ */