diff options
Diffstat (limited to 'docs/src')
-rw-r--r-- | docs/src/articles.dox | 1 | ||||
-rw-r--r-- | docs/src/debug.dox | 138 |
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 :-)
+ * .
+ */
|