Initial import
This commit is contained in:
NIIBE Yutaka
114
ChibiOS_2.0.2/docs/src/stacks.dox
Normal file
114
ChibiOS_2.0.2/docs/src/stacks.dox
Normal file
@@ -0,0 +1,114 @@
|
||||
/*
|
||||
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/>.
|
||||
|
||||
---
|
||||
|
||||
A special exception to the GPL can be applied should you wish to distribute
|
||||
a combined work that includes ChibiOS/RT, without being obliged to provide
|
||||
the source code for any proprietary components. See the file exception.txt
|
||||
for full details of how and when the exception can be applied.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @page article_stacks Stacks and stack sizes
|
||||
* In an RTOS like ChibiOS/RT there are several dedicated stacks, each stack
|
||||
* has a dedicated RAM space that must have a correctly sized assigned area.
|
||||
* <h2>The stacks</h2>
|
||||
* There are several stacks in the systems, some are always present, some
|
||||
* others are present only in some architectures:
|
||||
* - <b>Main stack</b>, this stack is used by the @p main() function and the
|
||||
* thread that execute it. It is not a normal thread stack because it is
|
||||
* initialized in the startup code and its size is defined in a port
|
||||
* dependent way. Details are in the various ports documentation.
|
||||
* - <b>Interrupt Stack</b>, some architectures have a dedicated interrupt
|
||||
* stack. This is an important feature in a multithreaded environment,
|
||||
* without a dedicated interrupt stack each thread has to reserve
|
||||
* enough space, for interrupts servicing, within its own stack. This space,
|
||||
* multiplied by the total threads number, can amount to a significant RAM
|
||||
* overhead.
|
||||
* - <b>Thread Stack</b>, each thread has a dedicated stack for its own
|
||||
* execution and context switch.
|
||||
* - <b>Other Stacks</b>, some architectures (ARM) can have other stacks but
|
||||
* the OS does not directly use any of them.
|
||||
* .
|
||||
* <h2>Risks</h2>
|
||||
* The most critical thing when writing an embedded multithreaded application
|
||||
* is to determine the correct stack size for main, threads and, when present,
|
||||
* interrupts.<br>
|
||||
* Assigning too much space to a stack is a waste of RAM, assigning too little
|
||||
* space leads to crashes or, worst scenario, hard to track instability.
|
||||
*
|
||||
* <h2>Assigning the correct size</h2>
|
||||
* You may try to examine the asm listings in order to calculate the exact
|
||||
* stack requirements but this requires much time, experience and patience.<br>
|
||||
* An alternative way is to use an interactive method. Follow this procedure
|
||||
* for each thread in the system:
|
||||
* - Enable the following debug options in the kernel:
|
||||
* - @p CH_DBG_ENABLE_STACK_CHECK, this enables a stack check before any
|
||||
* context switch. This option halts the system in @p chSysHalt() just
|
||||
* before a stack overflow happens. The halt condition is caused by
|
||||
* a stack overflow when the global variable @p panic_msg is set to
|
||||
* @p NULL, normally it would point to a panic message.
|
||||
* - @p CH_DBG_FILL_THREADS, this option fills the threads working area
|
||||
* with an easily recognizable pattern (0x55).
|
||||
* - Assign a large and safe size to the thread stack, as example 256 bytes
|
||||
* on 32 MCUs, 128 bytes on 8/16 bit MCUs. This is almost always too much
|
||||
* for simple threads.
|
||||
* - Run the application, if the application crashes or halts then increase
|
||||
* the stack size and repeat (you know how to use the debugger right?).
|
||||
* - Let the application run and make sure to trigger the thread in a way to
|
||||
* make it follow most or all its code paths. If the application crashes or
|
||||
* halts then increase the stack size and repeat.
|
||||
* - Stop the application using the debugger and examine the thread working
|
||||
* area (you know what a map file is, right?). You can see that the thread
|
||||
* stack overwrote the fill pattern (0x55) from the top of the working area
|
||||
* downward. You can estimate the excess stack by counting the untouched
|
||||
* locations.
|
||||
* - Trim down the stack size and repeat until the application still runs
|
||||
* correctly and you have a decent margin in the stack.
|
||||
* - Repeat for all the thread classes in the system.
|
||||
* - Turn off the debug options.
|
||||
* - Done.
|
||||
* .
|
||||
* <h2>Final Notes</h2>
|
||||
* Some useful info:
|
||||
* - Stack overflows are the most common problems source during development,
|
||||
* when in trouble with crashes or anomalous behaviors always first verify
|
||||
* stack sizes.
|
||||
* - The required stack size can, and very often does change when changing
|
||||
* compiler vendor, compiler version, compiler options, code type (ARM
|
||||
* or THUMB as example).
|
||||
* - Code compiled in THUMB mode uses more stack space compared to the
|
||||
* same code compiled in ARM mode. In GCC this is related to lack of tail
|
||||
* calls optimizations in THUMB mode, this is probably true also in other
|
||||
* compilers.
|
||||
* - Speed optimized code often requires less stack space compared to space
|
||||
* optimized code. Be careful when changing optimizations.
|
||||
* - The interrupts space overhead on the thread stacks (@p INT_REQUIRED_STACK
|
||||
* defined in @p chcore.h) is included in the total working area size
|
||||
* by the system macros @p THD_WA_SIZE() and @p WORKING_AREA().<br>
|
||||
* The correct way to reserve space into the thread stacks for interrupts
|
||||
* processing is to override the @p INT_REQUIRED_STACK default value.
|
||||
* Architectures with a dedicated interrupt stack do not require changes
|
||||
* to this value. Resizing of the global interrupt stack may be required
|
||||
* instead.
|
||||
* - Often is a good idea to have some extra space in stacks unless you
|
||||
* are really starved on RAM. Anyway, it is best to optimize stack space
|
||||
* at the very end of your development cycle.
|
||||
* .
|
||||
*/
|
||||
Reference in New Issue
Block a user