/*
    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 demo, add things one at a
 *   time and test often, if you add too many things at once then finding 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 :-)
 * .
 */