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

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

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>
+ * - Free software, GPL3 licensed.
- * <li>Free software, GPL3 licensed.</li>
+ * - Designed for realtime applications.
- * <li>Designed for realtime applications.</li>
+ * - Easily portable.
- * <li>Easily portable.</li>
+ * - Mixed programming model:
- * <li>Mixed programming model:</li>
+ *   - Synchronous, using semaphores/mutexes/condvars and/or messages.
- *   <ul>
+ *   - Asynchronous, using event sources.
- *   <li>Synchronous, using semaphores/mutexes/condvars and/or messages.</li>
+ *   - Mix of the above models, multiple threads listening to multiple event
- *   <li>Asynchronous, using event sources.</li>
+ *     sources while serving message queues.
- *   <li>Mix of the above models, multiple threads listening to multiple event
+ *   - PC simulator target included, the development can be done on the PC
- *       sources while serving message queues.</li>
- *   </ul>
- * <li>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>
+ *     MinGW demo available.
- * <li>Preemptive scheduling.</li>
+ * - Preemptive scheduling.
- * <li>128 priority levels.</li>
+ * - 128 priority levels.
- * <li>Multiple threads at the same priority level allowed.</li>
+ * - Multiple threads at the same priority level allowed.
- * <li>Round robin scheduling for threads at the same priority level.</li>
+ * - Round robin scheduling for threads at the same priority level.
- * <li>Unlimited number of threads.</li>
+ * - Unlimited number of threads.
- * <li>Unlimited number of virtual timers.</li>
+ * - Unlimited number of virtual timers.
- * <li>Unlimited number of semaphores.</li>
+ * - Unlimited number of semaphores.
- * <li>Unlimited number of mutexes.</li>
+ * - Unlimited number of mutexes.
- * <li>Unlimited number of condvars.</li>
+ * - Unlimited number of condvars.
- * <li>Unlimited number of event sources.</li>
+ * - Unlimited number of event sources.
- * <li>Unlimited number of messages in queue.</li>
+ * - Unlimited number of messages in queue.
- * <li>Unlimited number of I/O queues.</li>
+ * - Unlimited number of I/O queues.
- * <li>No static setup at compile time, there is no need to configure a maximum
+ * - No static setup at compile time, there is no need to configure a maximum
- *     number of all the above resources.</li>
+ *   number of all the above resources.
- * <li>No *need* for a memory allocator, all the kernel structures are static
+ * - No *need* for a memory allocator, all the kernel structures are static
- *     and declaratively allocated.</li>
+ *   and declaratively allocated.
- * <li>Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
+ * - Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
- *     runtime.</li>
+ *   runtime.
- * <li>Optional, thread safe, Heap Allocator subsystem.</li>
+ * - Optional, thread safe, Heap Allocator subsystem.
- * <li>Optional, thread safe, Memory Pools Allocator subsystem.</li>
+ * - Optional, thread safe, Memory Pools Allocator subsystem.
- * <li>Blocking and non blocking I/O channels with timeout and events generation
+ * - Blocking and non blocking I/O channels with timeout and events generation
- *     capability.</li>
+ *   capability.
- * <li>Minimal system requirements: about 8KiB ROM with all options enabled and
+ * - Minimal system requirements: about 8KiB ROM with all options enabled and
- *     speed optimizations on. The size can shrink under 2KiB by disabling the
+ *   speed optimizations on. The size can shrink under 2KiB by disabling the
- *     the unused subsystems and optimizing for size.</li>
+ *   the unused subsystems and optimizing for size.
- * <li>Small memory footprint, unused subsystems can be excluded by the
+ * - Small memory footprint, unused subsystems can be excluded by the
- *     memory image.</li>
+ *   memory image.
- * <li>Almost totally written in C with little ASM code required for ports.</li>
+ * - Almost totally written in C with little ASM code required for ports.
- * </ul>
  *
- * ChibiOS/RT architecture:<br><br>
+ * Related pages:
- * @subpage Concepts
+ * - @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\>().
@@ -236,6 +234,16 @@
  */
 /** @} */
 
+/**
+ * @page Articles Articles
+ * @{
+ * @brief ChibiOS/RT Articles and Code Examples
+ *
+ * - @subpage article_atomic
+ * - @subpage article_saveram
+ */
+/** @} */
+
 /**
  * @defgroup Ports Ports
  * @{
@@ -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>
+ * are defined on semaphores:
- * <ul>
+ * - <b>Signal</b>: The semaphore counter is increased and if the result
- *   <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
- *     is non-positive then a waiting thread is removed from the semaphore
+ *   queue and made ready for execution.
- *     queue and made ready for execution.
+ * - <b>Wait</b>: The semaphore counter is decreased and if the result
- *   </li>
+ *   becomes negative the thread is queued in the semaphore and suspended.
- *   <li><b>Wait</b>: The semaphore counter is decreased and if the result
+ * - <b>Reset</b>: The semaphore counter is reset to a non-negative value
- *     becomes negative the thread is queued in the semaphore and suspended.
+ *   and all the threads in the queue are released.
- *   </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>
  * 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>
+ * on mutexes:
- * <ul>
+ * - <b>Lock</b>: The mutex is checked, if the mutex is not owned by some
- *   <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
- *     other thread then it is locked else the current thread is queued on the
+ *   mutex in a list ordered by priority.
- *     mutex in a list ordered by priority.
+ * - <b>Unlock</b>: The mutex is released by the owner and the highest
- *   </li>
+ *   priority thread waiting in the queue, if any, is resumed and made owner
- *   <li><b>Unlock</b>: The mutex is released by the owner and the highest
+ *   of the mutex.
- *     priority thread waiting in the queue, if any, is resumed and made owner
- *     of the mutex.
- *   </li>
- * </ul>
  * 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>
+ * Event Sources and Event Listeners.
- * <b>Operation mode</b><br><br>
+ * <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>
+ * Synchronous inter-thread Messages.
- * <b>Operation Mode</b><br><br>
+ * <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>
+ * - <b>Input queue</b>, unidirectional queue where the writer is the
- * <li><b>Input queue</b>, unidirectional queue where the writer is the
+ *   lower side and the reader is the upper side.
- *     lower side and the reader is the upper side.</li>
+ * - <b>Output queue</b>, unidirectional queue where the writer is the
- * <li><b>Output queue</b>, unidirectional queue where the writer is the
+ *   upper side and the reader is the lower side.
- *     upper side and the reader is the lower side.</li>
+ * - <b>Half duplex queue</b>, bidirectional queue where the buffer is shared
- * <li><b>Half duplex queue</b>, bidirectional queue where the buffer is shared
+ *   between a receive and a transmit queues. This means that concurrent
- *     between a receive and a transmit queues. This means that concurrent
+ *   buffered input and output operations are not possible, this is perfectly
- *     buffered input and output operations are not possible, this is perfectly
+ *   acceptable for a lot of applications however, as example an RS485 driver.
- *     acceptable for a lot of applications however, as example an RS485 driver.
+ * - <b>Full duplex queue</b>, bidirectional queue where read and write
- * <li><b>Full duplex queue</b>, bidirectional queue where read and write
+ *   operations can happen at the same time. Full duplex queues
- *     operations can happen at the same time. Full duplex queues
+ *   are implemented by pairing an input queue and an output queue together.
- *     are implemented by pairing an input queue and an output queue together.
- * </ul>
  * 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

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.
+ */
+/** @} */

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.
+ */
+/** @} */

ports/ARMCM3/chcore.c

@@ -84,6 +84,8 @@ CH_IRQ_HANDLER void SysTickVector(void) {
 
 /**
  * The SVC vector is used for commanded context switch.
+ * @param otp the thread to be switched out
+ * @param ntp the thread to be switched it
  */
 /** @cond never */
 __attribute__((naked))

readme.txt

@@ -85,6 +85,8 @@ Win32-MinGW            - ChibiOS/RT simulator and demo into a WIN32 process,
 - Introduced the concept of interrupt classes, see the documentation.
 - Introduced the concept of system states, see the documentation.
 - Huge improvements to the ports documentation.
+- Articles and notes previously in the wiki now merged in the general
+  documentation, the wiki entries are obsolete and will be removed.
 
 *** 1.0.0rc2 ***
 - FIX: Removed unused variable "retaddr" from the Cortex-M3 port.