zcy
/
tinySA
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

master
gdisirio 2009-10-19 18:33:53 +00:00
parent 5cdca32dbb
commit 2c41c0d442
5 changed files with 195 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/src/articles.dox
View File

@ -18,7 +18,7 @@
*/
/**
* @page articles Articles
* @page articles Articles and Code Samples
* ChibiOS/RT Articles and Code Examples:
* - @subpage article_stacks
* - @subpage article_mutual_exclusion
@ -29,5 +29,6 @@
* - @subpage article_timing
* - @subpage article_portguide
* - @subpage article_design
* - @subpage article_create_thread
* .
*/

186
docs/src/createthread.dox Normal file
View File

@ -0,0 +1,186 @@
/*
ChibiOS/RT - Copyright (C) 2006-2007 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_create_thread How to create a thread
* At the system startup there are already two active threads:
* - <b>Idle thread</b>. This thread has the lowest priority in the system so
* it runs only when the other threads in the system are sleeping. This
* threads usually switches the system in a low power mode and does nothing
* else.
* - <b>Main thread</b>. This thread executes your @p main() function at
* startup. The main thread is created at the @p NORMALPRIO level but it
* can change its own priority if required. It is from the main thread
* that the other threads are usually created.
* .
* There are two kind of threads in ChibiOS/RT:
* - <b>Static Threads</b>. This kind of threads are statically allocated in
* memory. The memory used by the thread cannot reused except for restarting
* the threads.
* - <b>Dynamic Threads</b>. Threads created by allocating memory from a memory
* heap or a memory pool.
* .
* <h2>Creating a static thread</h2>
* In order to create a static thread a working area must be declared using
* the macro @p WORKING_AREA as shown:
* @code
static WORKING_AREA(myThreadWorkingArea, 128);
* @endcode
* This macro reserves 128 bytes of stack for the thread and space for all
* the required thread related structures. The total size and the alignment
* problems are handled inside the macro, you only need to specify the pure
* stack size.<br>
* A thread can be started by invoking @p chThdCreateStatic() as shown in this
* example:
* @code
Thread *tp = chThdCreateStatic(myThreadWorkingArea,
sizeof(myThreadWorkingArea),
NORMALPRIO, /* Initial priority. */
myThread, /* Thread function. */
NULL); /* Thread parameter. */
* @endcode
* Tre variable tp receives the pointer to the thread object, it is taken
* by other APIs as parameter.<br>
* Now a complete example:
* @code
/*
* * My simple application.
*/
#include <ch.h>
/*
* * Working area for the LED flashing thread.
*/
static WORKING_AREA(myThreadWorkingArea, 128);
/*
* * LED flashing thread.
*/
static msg_t myThread(void *arg) {
while (TRUE) {
LED_ON();
chThdSleepMilliseconds(500);
LED_OFF();
chThdSleepMilliseconds(500);
}
}
int main(int argc, char *argv[]) {
/* Starting the flashing LEDs thread.*/
(void)chThdCreateStatic(myThreadWorkingArea, sizeof(myThreadWorkingArea),
NORMALPRIO, myThread, NULL);
.
.
.
}
* @endcode
* Note that is memory allocated to myThread() is statically defined and cannot
* be reused. Static threads are ideal for safety applications because there is
* no risk of a memory allocation failure because progressive heap
* fragmentation.
*
* <h2>Creating a dynamic thread using the heap allocator</h2>
* In order to create a thread from a memory heap is very easy:
* @code
Thread *tp = chThdCreateFromHeap(NULL, /* NULL = Default heap. */
128, /* Stack size. */
NORMALPRIO, /* Initial priority. */
myThread, /* Thread function. */
NULL); /* Thread parameter. */
* @endcode
* The memory is allocated from the spawned heap and the thread is started.
* Note that the memory is not freed when the thread terminates but when the
* thread final status (its return value) is collected by the spawning thread.
* As example:
* @code
static msg_t myThread(void *arg) {
unsigned i = 10;
while (i > 0) {
LED_ON();
chThdSleepMilliseconds(500);
LED_OFF();
chThdSleepMilliseconds(500);
i--;
}
return (msg_t)i;
}
int main(int argc, char *argv[]) {
Thread *tp = chThdCreateFromHeap(NULL, 128, NORMALPRIO+1, myThread, NULL);
if (tp == NULL)
chSysHalt(); /* Memory exausted. */
/* The main thread continues its normal execution.*/
.
.
/*
* * Now waits for the spawned thread to terminate (if it has not terminated
* * already) then gets the thread exit message (msg) and returns the
* * terminated thread memory to the heap (default system heap in this
* * example).
*/
msg_t msg = chThdWait(tp);
.
.
}
* @endcode
*
* <h2>Creating a dynamic thread using the heap allocator</h2>
* A pool is a collection of equally sized memory blocks, creating a thread from
* a memry pool is very similar to the previous example but the memory of
* terminated threads is returned to the memory pool rather than to a heap:
* @code
static msg_t myThread(void *arg) {
unsigned i = 10;
while (i > 0) {
LED_ON();
chThdSleepMilliseconds(500);
LED_OFF();
chThdSleepMilliseconds(500);
i--;
}
return (msg_t)i;
}
int main(int argc, char *argv[]) {
Thread *tp = chThdCreateFromMemoryPool(myPool, NORMALPRIO+1, myThread, NULL);
if (tp == NULL)
chSysHalt(); /* Pool empty. */
/* The main thread continues its normal execution.*/
.
.
/*
* * Now waits for the spawned thread to terminate (if it has not terminated
* * already) then gets the thread exit message (msg) and returns the
* * terminated thread memory to the original memory pool.
*/
msg_t msg = chThdWait(tp);
.
.
}
* @endcode
*/

4
docs/src/stacks.dox
View File

@ -54,7 +54,9 @@
* - 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.
* 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

3
os/kernel/src/chdebug.c
View File

@ -62,7 +62,8 @@ void chDbgTrace(Thread *otp, Thread *ntp) {
/**
* @brief Pointer to the panic message.
* @details This pointer is meant to be accessed through the debugger, it is
* written once and then the system is halted.
* written once and then the system is halted. This variable can be
* set to @p NULL if the halt is caused by a stack overflow.
*/
char *panic_msg;

2
os/kernel/templates/chconf.h
View File

@ -377,6 +377,8 @@
* @note The default is @p FALSE.
* @note The stack check is performed in a architecture/port dependent way. It
* may not be implemented or some ports.
* @note The default failure mode is to halt the system with the global
* @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE