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

2 files changed, 139 insertions, 0 deletions

diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index f6f02e811..5aff3203e 100644
--- a/docs/src/articles.dox
+++ b/docs/src/articles.dox
@@ -22,6 +22,7 @@
  * ChibiOS/RT Articles and Code Examples:

  * - @subpage article_eclipse

  * - @subpage article_eclipse2

+ * - @subpage article_debug

  * - @subpage article_create_thread

  * - @subpage article_interrupts

  * - @subpage article_wakeup

diff --git a/docs/src/debug.dox b/docs/src/debug.dox
new file mode 100644
index 000000000..46a67dfb2
--- /dev/null
+++ b/docs/src/debug.dox
@@ -0,0 +1,138 @@
+/*

+    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_debug Debugging ChibiOS/RT applications

+ * ChibiOS/RT offers several mechanisms that can help in the debug phase of

+ * the development cycle.

+ *

+ * <h2>What this guide does not cover</h2>

+ * This guide assumes knowledge in following areas:

+ * - General knowledge of embedded development.

+ * - RTOS concepts.

+ * - Setup of your specific target hardware and toolchain.

+ * - Knowledge of your toolchain. The guide will explain what you need to do,

+ *   not how it is done using you specific debugger, compiler, JTAG probe and

+ *   target hardware.

+ * .

+ * <h2>Helpful debugging configuration settings</h2>

+ * There are several settings in your kernel configuration file

+ * (see @ref templates/chconf.h) that you may want to  enable during

+ * debugging and in general during the whole development process.

+ * - @p CH_OPTIMIZE_SPEED=FALSE, this disables inlining into the kernel code

+ *   and makes it easier to debug using your debugger, you may also want

+ *   to reduce or disable compiler optimizations (-O0 using GCC).

+ * - @p CH_DBG_ENABLE_CHECKS=TRUE, this setting enables the checks on the

+ *   API parameters, useful to understand if you are passing wrong parameters

+ *   to the OS functions.

+ * - @p CH_DBG_ENABLE_ASSERTS=TRUE, this setting enables the OS internal

+ *   consistency checks, this can trap several kind of errors in the user

+ *   code (or in the kernel itself).

+ * - @p CH_DBG_ENABLE_STACK_CHECK=TRUE, this setting enables checks on

+ *   threads stack overflow. Note that this option is not available in

+ *   all ports, check your port documentation. If not supported then it

+ *   is silently ignored, see also the article @ref article_stacks.

+ * - @p CH_DBG_FILL_THREADS=TRUE, this setting enables the threads workspace

+ *   filling, this can help examining the stack usage from your debugger.

+ * .

+ * Note that all the failed checks lock the kernel into the @p port_halt()

+ * function. In order to assess what triggered the lock the global variable

+ * @p panic_msg must be inspected using the debugger, the variable is a

+ * pointer to an error message (a zero terminated string), the pointer may

+ * contain @p NULL if the lock was triggered by a stack overflow.

+ *

+ * <h2>Common errors and symptoms</h2>

+ * There are some common errors while using an RTOS, use the following

+ * table as a check list, if your problem is not a generic programming error

+ * then probably it is one of the following common RTOS/embedded related

+ * mistakes:

+ * - Insufficient stack allocated to one or more threads.<br>

+ *   Common symptoms:

+ *   - Target instability.

+ *   - Target locked into the @p port_halt() function.

+ *   - Target trapped into an exception handler (architecture dependent).

+ *   - Target apparent self reset (not real resets usually).

+ *   .

+ * - Insufficient stack allocated to the IRQ stack (in those architectures

+ *   that have a separate IRQ stack, ARM as example).<br>

+ *   Common symptoms:

+ *   - Target instability.

+ *   - Target trapped into an exception handler (architecture dependent).

+ *   - Target apparent self reset (not real resets usually).

+ *   .

+ * - Use of a non reentrant function from within an interrupt handler, as

+ *   example most C runtime functions.<br>

+ *   Common symptoms:

+ *   - Target instability.

+ *   - Unexpected application behavior.

+ *   .

+ * - Missing use of a mutual exclusion mechanism to protect data

+ *   (or non reentrant code) shared among multiple threads and/or

+ *   threads and interrupt handlers, see also the article

+ *   @ref article_mutual_exclusion.<br>

+ *   Common symptoms:

+ *   - Target instability.

+ *   - Unexpected application behavior.

+ *   .

+ * - Use of S-class or I-class APIs outside a proper lock state, see the

+ *   @ref concepts article, specifically the @ref api_suffixes and

+ *   @ref system_states sections.<br>

+ *   Common symptoms:

+ *   - Target instability.

+ *   - Target trapped into an exception handler (architecture dependent).

+ *   - Target apparent self reset (not real resets usually).

+ *   .

+ * - Use of a non I-class API from an interrupt handler, see the

+ *   @ref concepts article, specifically the @ref api_suffixes and

+ *   @ref system_states sections.<br>

+ *   Common symptoms:

+ *   - Target instability.

+ *   - Target trapped into an exception handler (architecture dependent).

+ *   - Target apparent self reset (not real resets usually).

+ *   .

+ * - Wrong threads priority assignment. One of the most critical things

+ *   to do when designing an RTOS based application is to assign correct

+ *   priorities to the threads in the system.<br>

+ *   Common symptoms:

+ *   - Excessive or unpredictable response times.

+ *   - Threads that appear to be never executed (CPU intensive threads at

+ *     higher priority).

+ *   .

+ * .

+ * <h2>General suggestions</h2>

+ * For the less expert users, there are several things you may do in order

+ * to minimize the need for debugging:

+ * - Read carefully the documentation first.

+ * - Try to find a code examples for things are you going to do, good sources

+ *   are: the documentation, the test code, under "./test" you will

+ *   find examples for almost any API in the ChibiOS/RT kernel and most

+ *   common RTOS related tasks, under "./testhal" there are examples

+ *   regarding the various device drivers, the various demos contain

+ *   good code samples too).

+ * - Start your application from an existing demos, add things one piece at

+ *   time and test often, if you add too many things at once a small problem

+ *   can become a debugging nightmare. Follow the cycle: think, implement,

+ *   test, repeat.

+ * - If you are stuck for too much time then consider asking for advice.

+ * - Report bugs and problems, bugs can be fixed, problems can become new

+ *   articles in the documentation (this and other documentation articles

+ *   spawned from questions in the forum or in the tracker).

+ * - Never give up :-)

+ * .

+ */