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

7 files changed, 219 insertions, 19 deletions

diff --git a/docs/rsc/eclipse003.jpg b/docs/rsc/eclipse003.jpg
new file mode 100644
index 000000000..a5cee7998
--- /dev/null
+++ b/docs/rsc/eclipse003.jpg
diff --git a/docs/rsc/eclipse004.jpg b/docs/rsc/eclipse004.jpg
new file mode 100644
index 000000000..4d3fc2a85
--- /dev/null
+++ b/docs/rsc/eclipse004.jpg
diff --git a/docs/rsc/eclipse005.jpg b/docs/rsc/eclipse005.jpg
new file mode 100644
index 000000000..63ce31e19
--- /dev/null
+++ b/docs/rsc/eclipse005.jpg
diff --git a/docs/rsc/tool002.jpg b/docs/rsc/tool002.jpg
index 22cf726bb..c36767ea3 100644
--- a/docs/rsc/tool002.jpg
+++ b/docs/rsc/tool002.jpg
diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index c2f9475a2..f6f02e811 100644
--- a/docs/src/articles.dox
+++ b/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

diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox
index 09165f6ff..5b58bf5fe 100644
--- a/docs/src/eclipse.dox
+++ b/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.

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.

+ */