From 75792b3d6af243e043e66b1b2f7199229d430ef8 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 21 Apr 2010 14:11:12 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1882 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/debug.dox | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 docs/src/debug.dox (limited to 'docs/src') 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 . +*/ + +/** + * @page article_debug Debugging ChibiOS/RT applications + * ChibiOS/RT offers several mechanisms that can help in the debug phase of + * the development cycle. + * + *

What this guide does not cover

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

Helpful debugging configuration settings

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

Common errors and symptoms

+ * 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.
+ * 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).
+ * 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.
+ * 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.
+ * 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.
+ * 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.
+ * 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.
+ * Common symptoms: + * - Excessive or unpredictable response times. + * - Threads that appear to be never executed (CPU intensive threads at + * higher priority). + * . + * . + *

General suggestions

+ * 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 :-) + * . + */ -- cgit v1.2.3