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

4 files changed, 207 insertions, 94 deletions

diff --git a/docs/Doxyfile b/docs/Doxyfile
index 8877df0fb..a3d8f860b 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -18,7 +18,7 @@ FULL_PATH_NAMES = NO
 STRIP_FROM_PATH = "C:/Documents and Settings/Administrator/"
 STRIP_FROM_INC_PATH = 
 SHORT_NAMES = NO
-JAVADOC_AUTOBRIEF = YES
+JAVADOC_AUTOBRIEF = NO
 QT_AUTOBRIEF = NO
 MULTILINE_CPP_IS_BRIEF = NO
 INHERIT_DOCS = NO
@@ -84,7 +84,7 @@ WARN_LOGFILE =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT = ../src/include ../src/templates ../src ../docs/ch.txt ../src/lib ../ports/ARM7 ../ports/ARM7-AT91SAM7X/port.dox ../ports/ARM7-LPC214x/port.dox ../ports/ARMCM3 ../ports/ARMCM3-STM32F103/port.dox ../ports/MSP430 ../ports/AVR 
+INPUT = ../src/include ../src/templates ../src ../docs/ch.txt ../docs/src ../src/lib ../ports/ARM7 ../ports/ARM7-AT91SAM7X/port.dox ../ports/ARM7-LPC214x/port.dox ../ports/ARMCM3 ../ports/ARMCM3-STM32F103/port.dox ../ports/MSP430 ../ports/AVR 
 INPUT_ENCODING = UTF-8
 FILE_PATTERNS = *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py *.ddf
 RECURSIVE = YES
diff --git a/docs/ch.txt b/docs/ch.txt
index e31bd932d..5048cf5f6 100644
--- a/docs/ch.txt
+++ b/docs/ch.txt
@@ -7,59 +7,57 @@
  * means small Real Time Operating System.

  * Source <a href="http://en.wikipedia.org/wiki/Chibi" target="_blank">Wikipedia</a>.

  * @section ch_features Features

- * <ul>

- * <li>Free software, GPL3 licensed.</li>

- * <li>Designed for realtime applications.</li>

- * <li>Easily portable.</li>

- * <li>Mixed programming model:</li>

- *   <ul>

- *   <li>Synchronous, using semaphores/mutexes/condvars and/or messages.</li>

- *   <li>Asynchronous, using event sources.</li>

- *   <li>Mix of the above models, multiple threads listening to multiple event

- *       sources while serving message queues.</li>

- *   </ul>

- * <li>PC simulator target included, the development can be done on the PC

+ * - Free software, GPL3 licensed.

+ * - Designed for realtime applications.

+ * - Easily portable.

+ * - Mixed programming model:

+ *   - Synchronous, using semaphores/mutexes/condvars and/or messages.

+ *   - Asynchronous, using event sources.

+ *   - Mix of the above models, multiple threads listening to multiple event

+ *     sources while serving message queues.

+ *   - PC simulator target included, the development can be done on the PC

  *     using MinGW.<br>

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

- *     MinGW demo available.</li>

- * <li>Preemptive scheduling.</li>

- * <li>128 priority levels.</li>

- * <li>Multiple threads at the same priority level allowed.</li>

- * <li>Round robin scheduling for threads at the same priority level.</li>

- * <li>Unlimited number of threads.</li>

- * <li>Unlimited number of virtual timers.</li>

- * <li>Unlimited number of semaphores.</li>

- * <li>Unlimited number of mutexes.</li>

- * <li>Unlimited number of condvars.</li>

- * <li>Unlimited number of event sources.</li>

- * <li>Unlimited number of messages in queue.</li>

- * <li>Unlimited number of I/O queues.</li>

- * <li>No static setup at compile time, there is no need to configure a maximum

- *     number of all the above resources.</li>

- * <li>No *need* for a memory allocator, all the kernel structures are static

- *     and declaratively allocated.</li>

- * <li>Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at

- *     runtime.</li>

- * <li>Optional, thread safe, Heap Allocator subsystem.</li>

- * <li>Optional, thread safe, Memory Pools Allocator subsystem.</li>

- * <li>Blocking and non blocking I/O channels with timeout and events generation

- *     capability.</li>

- * <li>Minimal system requirements: about 8KiB ROM with all options enabled and

- *     speed optimizations on. The size can shrink under 2KiB by disabling the

- *     the unused subsystems and optimizing for size.</li>

- * <li>Small memory footprint, unused subsystems can be excluded by the

- *     memory image.</li>

- * <li>Almost totally written in C with little ASM code required for ports.</li>

- * </ul>

+ *     MinGW demo available.

+ * - Preemptive scheduling.

+ * - 128 priority levels.

+ * - Multiple threads at the same priority level allowed.

+ * - Round robin scheduling for threads at the same priority level.

+ * - Unlimited number of threads.

+ * - Unlimited number of virtual timers.

+ * - Unlimited number of semaphores.

+ * - Unlimited number of mutexes.

+ * - Unlimited number of condvars.

+ * - Unlimited number of event sources.

+ * - Unlimited number of messages in queue.

+ * - Unlimited number of I/O queues.

+ * - No static setup at compile time, there is no need to configure a maximum

+ *   number of all the above resources.

+ * - No *need* for a memory allocator, all the kernel structures are static

+ *   and declaratively allocated.

+ * - Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at

+ *   runtime.

+ * - Optional, thread safe, Heap Allocator subsystem.

+ * - Optional, thread safe, Memory Pools Allocator subsystem.

+ * - Blocking and non blocking I/O channels with timeout and events generation

+ *   capability.

+ * - Minimal system requirements: about 8KiB ROM with all options enabled and

+ *   speed optimizations on. The size can shrink under 2KiB by disabling the

+ *   the unused subsystems and optimizing for size.

+ * - Small memory footprint, unused subsystems can be excluded by the

+ *   memory image.

+ * - Almost totally written in C with little ASM code required for ports.

  *

- * ChibiOS/RT architecture:<br><br>

- * @subpage Concepts

+ * Related pages:

+ * - @subpage Concepts

+ * - @subpage Articles

  */

 

 /**

  * @page Concepts Concepts

  * @{

+ * @brief ChibiOS/RT Concepts and Architecture

  * @section naming Naming Conventions

  * ChibiOS/RT APIs are all named following this convention:

  * @a ch\<group\>\<action\>\<suffix\>().

@@ -237,6 +235,16 @@
 /** @} */

 

 /**

+ * @page Articles Articles

+ * @{

+ * @brief ChibiOS/RT Articles and Code Examples

+ *

+ * - @subpage article_atomic

+ * - @subpage article_saveram

+ */

+/** @} */

+

+/**

  * @defgroup Ports Ports

  * @{

  * This section describes the technical details for the various supported

@@ -351,7 +359,7 @@
  * @defgroup Heap Heap

  * @{

  * Heap Allocator related APIs.

- * <b>Operation mode</b><br><br>

+ * <h2>Operation mode</h2>

  * The heap allocator implements a first-fit strategy and its APIs are

  * functionally equivalent to the usual @p malloc() and @p free(). The main

  * difference is that the heap APIs are thread safe.<br>

@@ -369,7 +377,7 @@
  * @defgroup MemoryPools Memory Pools

  * @{

  * Memory Pools related APIs.

- * <b>Operation mode</b><br><br>

+ * <h2>Operation mode</h2>

  * The Memory Pools APIs allow to allocate/free fixed size objects in

  * <b>constant time</b> and reliably without memory fragmentation problems.<br>

  * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be

@@ -383,21 +391,16 @@
  * @defgroup Semaphores Semaphores

  * @{

  * Semaphores and threads synchronization.

- * <b>Operation mode</b><br><br>

+ * <h2>Operation mode</h2>

  * A semaphore is a threads synchronization object, some operations

- * are defined on semaphores:<br>

- * <ul>

- *   <li><b>Signal</b>: The semaphore counter is increased and if the result

- *     is non-positive then a waiting thread is removed from the semaphore

- *     queue and made ready for execution.

- *   </li>

- *   <li><b>Wait</b>: The semaphore counter is decreased and if the result

- *     becomes negative the thread is queued in the semaphore and suspended.

- *   </li>

- *   <li><b>Reset</b>: The semaphore counter is reset to a non-negative value

- *     and all the threads in the queue are released.

- *   </li>

- * </ul>

+ * are defined on semaphores:

+ * - <b>Signal</b>: The semaphore counter is increased and if the result

+ *   is non-positive then a waiting thread is removed from the semaphore

+ *   queue and made ready for execution.

+ * - <b>Wait</b>: The semaphore counter is decreased and if the result

+ *   becomes negative the thread is queued in the semaphore and suspended.

+ * - <b>Reset</b>: The semaphore counter is reset to a non-negative value

+ *   and all the threads in the queue are released.

  * Semaphores can be used as guards for mutual exclusion code zones but

  * also have other uses, queues guards and counters as example.<br>

  * In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES

@@ -411,30 +414,26 @@
  * @defgroup Mutexes Mutexes

  * @{

  * Mutexes and threads synchronization.

- * <b>Operation mode</b><br><br>

+ * <h2>Operation mode</h2>

  * A mutex is a threads synchronization object, some operations are defined

- * on mutexes:<br>

- * <ul>

- *   <li><b>Lock</b>: The mutex is checked, if the mutex is not owned by some

- *     other thread then it is locked else the current thread is queued on the

- *     mutex in a list ordered by priority.

- *   </li>

- *   <li><b>Unlock</b>: The mutex is released by the owner and the highest

- *     priority thread waiting in the queue, if any, is resumed and made owner

- *     of the mutex.

- *   </li>

- * </ul>

+ * on mutexes:

+ * - <b>Lock</b>: The mutex is checked, if the mutex is not owned by some

+ *   other thread then it is locked else the current thread is queued on the

+ *   mutex in a list ordered by priority.

+ * - <b>Unlock</b>: The mutex is released by the owner and the highest

+ *   priority thread waiting in the queue, if any, is resumed and made owner

+ *   of the mutex.

  * In order to use the Event APIs the @p CH_USE_MUTEXES option must be

  * specified in @p chconf.h.<br>

  *

- * <b>Constraints</b><br><br>

+ * <h2>Constraints</h2>

  * In ChibiOS/RT the Unlock operations are always performed in Lock-reverse

  * order. The Unlock API does not even have a parameter, the mutex to unlock

  * is taken from an internal stack of owned mutexes.

  * This both improves the performance and is required by the priority

  * inheritance mechanism.

  *

- * <b>The priority inversion problem</b><br><br>

+ * <h2>The priority inversion problem</h2>

  * The mutexes in ChibiOS/RT implements the <b>full</b> priority

  * inheritance mechanism in order handle the priority inversion problem.<br>

  * When a thread is queued on a mutex, any thread, directly or indirectly,

@@ -451,7 +450,7 @@
  * @defgroup CondVars Conditional Variables

  * @{

  * Conditional Variables and threads synchronization.

- * <b>Operation mode</b><br><br>

+ * <h2>Operation mode</h2>

  * The condition variable is a synchronization object meant to be used inside

  * a zone protected by a @p Mutex. Mutexes and CondVars together can implement

  * a Monitor construct.<br>

@@ -465,8 +464,8 @@
 /**

  * @defgroup Events Events

  * @{

- * Event Sources and Event Listeners.<br>

- * <b>Operation mode</b><br><br>

+ * Event Sources and Event Listeners.

+ * <h2>Operation mode</h2>

  * An Event Source is a special object that can be signaled by a thread or

  * an interrupt service routine. Signaling an Event Source has the effect

  * that all the threads registered on the Event Source will receive

@@ -488,8 +487,8 @@
 /**

  * @defgroup Messages Messages

  * @{

- * Synchronous Messages.<br>

- * <b>Operation Mode</b><br><br>

+ * Synchronous inter-thread Messages.

+ * <h2>Operation Mode</h2>

  * Messages are an easy to use and fast IPC mechanism, threads can both serve

  * messages and send messages to other threads, the mechanism allows data to

  * be carryed in both directions. Data is not copyed between the client and

@@ -517,19 +516,17 @@
  * routine) and an upper side (upper driver, accessed by the application

  * threads).<br>

  * There are several kind of queues:<br>

- * <ul>

- * <li><b>Input queue</b>, unidirectional queue where the writer is the

- *     lower side and the reader is the upper side.</li>

- * <li><b>Output queue</b>, unidirectional queue where the writer is the

- *     upper side and the reader is the lower side.</li>

- * <li><b>Half duplex queue</b>, bidirectional queue where the buffer is shared

- *     between a receive and a transmit queues. This means that concurrent

- *     buffered input and output operations are not possible, this is perfectly

- *     acceptable for a lot of applications however, as example an RS485 driver.

- * <li><b>Full duplex queue</b>, bidirectional queue where read and write

- *     operations can happen at the same time. Full duplex queues

- *     are implemented by pairing an input queue and an output queue together.

- * </ul>

+ * - <b>Input queue</b>, unidirectional queue where the writer is the

+ *   lower side and the reader is the upper side.

+ * - <b>Output queue</b>, unidirectional queue where the writer is the

+ *   upper side and the reader is the lower side.

+ * - <b>Half duplex queue</b>, bidirectional queue where the buffer is shared

+ *   between a receive and a transmit queues. This means that concurrent

+ *   buffered input and output operations are not possible, this is perfectly

+ *   acceptable for a lot of applications however, as example an RS485 driver.

+ * - <b>Full duplex queue</b>, bidirectional queue where read and write

+ *   operations can happen at the same time. Full duplex queues

+ *   are implemented by pairing an input queue and an output queue together.

  * In order to use the I/O queues the @p CH_USE_QUEUES option must

  * be specified in @p chconf.h.<br>

  * In order to use the half duplex queues the @p CH_USE_QUEUES_HALFDUPLEX

diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox
new file mode 100644
index 000000000..0f678448b
--- /dev/null
+++ b/docs/src/atomic.dox
@@ -0,0 +1,50 @@
+/**

+ * @page article_atomic Invoking multiple primitives as a single atomic operation

+ * @{

+ * It is often necessary to invoke multiple operations involving a

+ * reschedulation as a single atomic operation.<br>

+ * ChibiOS/RT already implements APIs that perform complex operations, as

+ * example the API @p chSemSignalWait() performs two operations atomically.<br>

+ * If more complex operations are required in your application then it is

+ * possible to build macro-operations, see the following example:

+ * @code

+  chSysLock();

+ 

+  chSemSignalI(&sem1);

+  chSemSignalI(&sem2);

+  if (tp != NULL) {

+    chThdResumeI(tp);

+    tp = NULL;

+  }

+  chSchRescheduleS();

+ 

+  chSysUnlock();

+ * @endcode

+ * The above example performs a signal operation on two semaphores, optionally

+ * resumes a thread, and performs a final reschedulation. The three operations

+ * are performed atomically.<br>

+ * An hypotetical @p chSemSignalSignalWait() operation could be implemented as

+ * follow:

+ * @code

+  chSysLock();

+ 

+  chSemSignalI(&sem1);

+  chSemSignalI(&sem2);

+  /*

+   * The "if" is required because the chSemWaitS() does not always internally

+   * reschedule.

+   */

+  if (chSemGetCounter(&sem3) <= 0)

+    chSemWaitS(&Sem3);

+  else {

+    chSemFastWaitS(&sem3);

+    chSchRescheduleS();

+  }

+ 

+  chSysUnlock();

+ * @endcode

+ * In general multiple I-Class APIs can be included and the block is terminated

+ * by an S-Class API that performs a reschedulation. Optionally a

+ * @p chSchRescheduleS() is present at the very end of the block.

+ */

+/** @} */

diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox
new file mode 100644
index 000000000..fec810c81
--- /dev/null
+++ b/docs/src/saveram.dox
@@ -0,0 +1,66 @@
+/**

+ * @page article_saveram Saving RAM by declaring thread functions "noreturn"

+ * @{

+ * One of the problems, when writing embedded multi-threaded applications,

+ * is that the thread functions do save the registers in the function

+ * entry code even if the system does not require it, exiting such

+ * a function would terminate the thread so there is no need to preserve

+ * the register values. This can waste tens of bytes for each thread.<br>

+ * Consider the following code: 

+ * @code

+#include <ch.h>

+ 

+static WORKING_AREA(waMyThread, 64);

+ 

+static t_msg MyThread(void *arg) {

+ 

+  while (!chThdShoudTerminate()) {

+    /* Do thread inner work */

+  }

+  return 1;

+}

+ 

+main() {

+  chSysInit();

+  ...

+  chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), MyThread, NULL);

+  ...

+  chSysPause();

+}

+ * @endcode

+ * The resulting ASM code for the thread function would be something like this:

+ * @code

+MyThread:

+        stmfd   sp!, {r4, r5, r6, lr}

+        ...

+        ldmfd   sp!, {r4, r5, r6, pc}

+ * @endcode

+ * Being that function a thread there is no need to save those registers, in

+ * embedded applications often the RAM is a scarce resource. That space can be

+ * saved by modifying the code as follow, using some advanced GCC extensions: 

+ * @code

+#include <ch.h>

+ 

+static BYTE8 waMyThread[UserStackSize(64)];

+ 

+__attribute__((noreturn)) void MyThread(void *arg) {

+ 

+  while (!chThdShoudTerminate()) {

+    /* Do thread inner work */

+  }

+  chThdExit(1);

+}

+ 

+main() {

+  chSysInit();

+  ...

+  chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), (t_tfunc)MyThread, NULL);

+  ...

+  chSysPause();

+}

+ * @endcode

+ * This will make GCC believe that the function cannot return and there is no

+ * need to save registers. The code will be a bit less readable and less

+ * portable on other compilers however.

+ */

+/** @} */