From 1eebe078ffbb85c3fb8a14db4d241502b27145bf Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 7 Jan 2010 15:23:38 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1509 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 3 +- docs/src/concepts.dox | 4 +- docs/src/goals.dox | 4 +- docs/src/main.dox | 4 +- docs/src/memory.dox | 2 +- docs/src/wakeup.dox | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 157 insertions(+), 8 deletions(-) create mode 100644 docs/src/wakeup.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index ca35c3f14..caf332d32 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -20,8 +20,9 @@ /** * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: - * - @subpage article_interrupts * - @subpage article_create_thread + * - @subpage article_interrupts + * - @subpage article_wakeup * - @subpage article_manage_memory * - @subpage article_stacks * - @subpage article_mutual_exclusion diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index d6364513b..49c96b2c8 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -34,8 +34,8 @@ * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, - * @a Mtx, @a Cond, @a Evt, @a Msg, @a Stream, @a IO, @a IQ, @a OQ, @a Dbg, - * @a Core, @a Heap, @a Pool. + * @a Mtx, @a Cond, @a Evt, @a Msg, @a SequentialStream, @a IO, @a IQ, @a OQ, + * @a Dbg, @a Core, @a Heap, @a Pool. * * @section api_suffixes API Names Suffixes * The suffix can be one of the following: diff --git a/docs/src/goals.dox b/docs/src/goals.dox index bcce60922..e312b526a 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -42,7 +42,7 @@ * *

Static design

* Everything in the kernel is static, nowhere memory is allocated or freed, - * there are two allocator subsystems but those are options and not part of + * there are three allocator subsystems but those are options and not part of * core OS. Safety is something you design in, not something you can add later. * *

No tables, arrays or other fixed structures

@@ -84,5 +84,5 @@ * committing to use it. Test results on all the supported platforms and * performance metrics are included in each ChibiOS/RT release. The test * code is released as well, all the included demos are capable of executing - * the test suite and the OS benchmarks. + * the test suite and the OS benchmarks, see @ref testsuite. */ diff --git a/docs/src/main.dox b/docs/src/main.dox index 4ce9b64b1..ddf608c3f 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -42,8 +42,8 @@ * number of all the above objects. * - PC simulator target included, the development can be done on a PC * under Linux or Windows.
- * Timers, I/O channels and other HW resources are simulated in a - * Win32 process and the application code does not need to be aware of it. + * Timers, I/O channels and other HW resources are simulated in a guest OS + * process and the application code does not need to be aware of it. * - No *need* for a memory allocator, all the kernel structures are static * and declaratively allocated. * - Optional, thread safe, Heap Allocator subsystem. diff --git a/docs/src/memory.dox b/docs/src/memory.dox index 727a95b2b..cf8495bcc 100644 --- a/docs/src/memory.dox +++ b/docs/src/memory.dox @@ -35,7 +35,7 @@ * *

The three subsystems

* This is a small comparison table regarding the three subsystems, C-runtime - * and static objects are thrown there for comparison:

+ * and static objects are thrown in there for comparison:

* * diff --git a/docs/src/wakeup.dox b/docs/src/wakeup.dox new file mode 100644 index 000000000..82766932b --- /dev/null +++ b/docs/src/wakeup.dox @@ -0,0 +1,148 @@ +/* + 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 . +*/ + +/** + * @page article_wakeup How to wake up a thread from an interrupt handler + * Waking up a thread after an hardware event is one of the most common tasks + * that an RTOS must be able to perform efficiently. In ChibiOS/RT there are + * several mechanisms that can be used, often each mechanism is best suited + * in a specific scenario. + * + *

Synchronously waking up a specific thread

+ * A common situation is to have to synchronously wake up a specific thread. + * This can be accomplished without the use of any specific synchronization + * primitive, it uses the very efficient low level scheduler APIs, note that + * you can also optionally send a simple message from the IRQ handler to + * the thread. + * @code +static Thread *tp = NULL; + +void mythread(void *p) { + + while (TRUE) { + msg_t msg; + + // Waiting for the IRQ to happen. + chSysLock(); + tp = chThdSelf(); + chSchGoSleepS(PRSUSPENDED); + msg = chThdSelf()->p_rdymsg; // Retrieving the message, optional + chSysUnlock(); + // Perform processing here. + } +} + +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Wakes up the thread. + chSysLockFromIsr(); + if (tp != NULL) { + tp->p_rdymsg = (msg_t)55; // Sending the message, optional + chSchReadyI(tp); + tp = NULL; + } + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Synchronously waking up one of the waiting threads

+ * Lets assume you have a queue of waiting threads, you want to wake up + * the threads one by one in FIFO order, if there are no waiting threads + * then nothing happens.
+ * This can be accomplished using a @p Semaphore object initialized to zero: + * @code +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // If there is at least one waiting thread then signal it. + chSysLockFromIsr(); + if (chSemGetCounterI(&mysem) < 0) + chSemSignalI(&mysem); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Synchronously waking up all the waiting threads

+ * In this scenario you want to synchronously wake up all the waiting threads, + * if there are no waiting threads then nothing happens.
+ * This can be accomplished using a @p Semaphore object initialized to zero: + * @code +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Wakes up all the threads waiting on the semaphore. + chSysLockFromIsr(); + chSemResetI(&mysem); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Asynchronously waking up a specific thread

+ * If you have to asynchronously wake up a specific thread then a simple + * event flags can be used. + * @code +static Thread *tp; + +void mythread(void *p) { + + tp = chThdSelf(); + while (TRUE) { + // Checks if an IRQ happened else wait. + chEvtWaitAny((eventmask_t)1); + // Perform processing here. + } +} + +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Wakes up the thread. + chSysLockFromIsr(); + chEvtSignalI(tp, (eventmask_t)1); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Asynchronously waking up one or more threads

+ * By using event sources it is possible to asynchronously wake up one or more + * listener threads. The mechanism requires a single initialized + * @p EventSource object, all the threads registered as listeners on the + * event source will be broadcasted. + * @code +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Pends an event flag on all the listening threads. + chSysLockFromIsr(); + chEvtBroadcastI(&my_event_source); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + */ -- cgit v1.2.3