git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1775 35acf78f-673a-0410-8e92-d51de3d6d3f4

docs/src/articles.dox

@@ -21,6 +21,7 @@
  * @page articles Articles and Code Samples
  * ChibiOS/RT Articles and Code Examples:
  * - @subpage article_eclipse
+ * - @subpage article_eclipse2
  * - @subpage article_create_thread
  * - @subpage article_interrupts
  * - @subpage article_wakeup

docs/src/eclipse.dox

@@ -19,28 +19,22 @@
 
 /**
  * @page article_eclipse Setting up a free embedded IDE
- * @brief Free advanced embedded IDE for ChibiOS/RT
- * This article will explain how to setup and use a free toolchain and use it
- * with ChibiOS/RT and general embedded development. The IDE will allow you
- * to:
- * - Edit and reformat your source code.
- * - Compile and verify errors.
- * - Debug your code on the target board both in high level language and
- *   assembler.
- * - Generate documentation from your source code.
- * - Develop embedded applications with or without ChibiOS/RT.
- * .
+ * @brief Free advanced embedded IDE for ChibiOS/RT.
+ * details This article will explain how to setup a free toolchain for use with
+ * ChibiOS/RT and general embedded development.<br>
  * The guide is meant mainly for Windows users but notes about Linux and
  * MAC OSX are present where the setup differs, mostly the toolchain is
  * exactly the same.
  *
- * <h2>What this guide will not explain</h2>
+ * <h2>What this guide does not cover</h2>
  * We will not enter in details of common system tasks like and not limited to:
  * - Installing applications (unless a special procedure is required).
  * - Creating desktop shortcuts.
  * - Adding paths to the PATH variable.
  * - Creating environment variables.
  * - Any other normal PC usage task.
+ * - Use of the toolchain, the use is covered by the "@ref article_eclipse2"
+ *   article.
  * .
  *
  * <h2>Article Index</h2>
@@ -75,7 +69,7 @@
  * - Zylin plugin for on-board debugging, see @ref install_zylin section.
  * - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but
  *   you can download them from <a href="http://www.freddiechopin.info/"
- *   target="_blank">here</a>. Linux users can try 
+ *   target="_blank">here</a>. Linux users can try
  *   <a href="http://home.comcast.net/~mcatudal/" target="_blank">here</a>.
  * - <b>Optional</b>, <a href="http://www.stack.nl/~dimitri/doxygen/"
  *   target="_blank">MinGW compiler</a>, needed if you want to compile, debug
@@ -113,7 +107,7 @@
  * Eclipse is distributed into a compressed archive, there is no installation
  * procedure:
  * - Verify if you have Java installed, if not install the runtime. You may
- *   verify this using the command: java -version. Make sure you have at
+ *   verify this using the command: "java -version". Make sure you have at
  *   least version 1.6.
  * - Create an eclipse directory in your home and unpack the archive there.
  *   Windows users may unpack it into c:@\program files@\eclipse.
@@ -130,17 +124,19 @@
  * - Now you should see the welcome screen, close it and you will be in the
  *   normal C/C++ perspective.
  * - Unselect "Project->Build Automatically" unless you like insanity.
- * - Disable the "usage collector" in Window->Preferences->Usage_Data_Collector
- *   by unselecting "Enable capture".
+ * - Disable the "usage collector" in
+ *   "Window->Preferences->Usage_Data_Collector" by unselecting "Enable
+ *   capture".
  * - If you are behind a proxy or firewall (corporate users usually are)
- *   configure the correct parameters in Window->Preferences->General->Network_Connections.
- * - Let Eclipse auto update to the latest version Help->Check_for_Updates.
+ *   configure the correct parameters in
+ *   "Window->Preferences->General->Network_Connections".
+ * - Let Eclipse auto update to the latest version "Help->Check_for_Updates".
  * .
  *
  * @section install_zylin Zylin Plugin Installation
  * Eclipse requires an hardware debugger component in order to perform on board
  * execution and debug.
- * - Open Eclipse, then help->Install_New_Software...
+ * - Open Eclipse, then "Help->Install_New_Software...".
  * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt
  *   into the location field, then press OK. The Zylin plugin will appear in the
  *   available plugins view, select and install it.

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.
+ */