From 2fc7d70a735c84daa85a92a9a0fb23c0997f8355 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 23 Mar 2010 15:45:30 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1775 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/rsc/eclipse003.jpg | Bin 0 -> 42621 bytes docs/rsc/eclipse004.jpg | Bin 0 -> 49163 bytes docs/rsc/eclipse005.jpg | Bin 0 -> 45472 bytes docs/rsc/tool002.jpg | Bin 47175 -> 47193 bytes docs/src/articles.dox | 1 + docs/src/eclipse.dox | 34 ++++---- docs/src/eclipse2.dox | 203 ++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 219 insertions(+), 19 deletions(-) create mode 100644 docs/rsc/eclipse003.jpg create mode 100644 docs/rsc/eclipse004.jpg create mode 100644 docs/rsc/eclipse005.jpg create mode 100644 docs/src/eclipse2.dox diff --git a/docs/rsc/eclipse003.jpg b/docs/rsc/eclipse003.jpg new file mode 100644 index 000000000..a5cee7998 Binary files /dev/null and b/docs/rsc/eclipse003.jpg differ diff --git a/docs/rsc/eclipse004.jpg b/docs/rsc/eclipse004.jpg new file mode 100644 index 000000000..4d3fc2a85 Binary files /dev/null and b/docs/rsc/eclipse004.jpg differ diff --git a/docs/rsc/eclipse005.jpg b/docs/rsc/eclipse005.jpg new file mode 100644 index 000000000..63ce31e19 Binary files /dev/null and b/docs/rsc/eclipse005.jpg differ diff --git a/docs/rsc/tool002.jpg b/docs/rsc/tool002.jpg index 22cf726bb..c36767ea3 100644 Binary files a/docs/rsc/tool002.jpg and b/docs/rsc/tool002.jpg differ 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.
* 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. * - *

What this guide will not explain

+ *

What this guide does not cover

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

Article Index

@@ -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 here. Linux users can try + * target="_blank">here. Linux users can try * here. * - Optional, MinGW compiler, 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 . +*/ + +/** + * @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). + * . + * **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. + *
**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).
+ * 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. + */ -- cgit v1.2.3