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

11 files changed, 400 insertions, 25 deletions

diff --git a/docs/Doxyfile b/docs/Doxyfile
index 02ed1edb3..1ea40a3b8 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -598,7 +598,8 @@ INPUT                  = ../docs/src \
                          ../os/hal/platforms/MSP430 \
                          ../os/hal/platforms/STM32 \
                          ../os/various \
-                         ../test
+                         ../test \
+                         ../ext/ext.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -1315,6 +1316,7 @@ PREDEFINED             = __DOXYGEN__ \
                          CH_USE_MESSAGES=1 \
                          CH_USE_MAILBOXES=1 \
                          CH_USE_DYNAMIC=1 \
+                         CH_USE_REGISTRY=1 \
                          CH_DBG_ENABLE_ASSERTS=1 \
                          CH_DBG_ENABLE_CHECKS=1 \
                          CH_DBG_ENABLE_TRACE=1 \
diff --git a/docs/src/architecture.dox b/docs/src/architecture.dox
new file mode 100644
index 000000000..d9a512b10
--- /dev/null
+++ b/docs/src/architecture.dox
@@ -0,0 +1,261 @@
+/*

+    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/>.

+*/

+

+/**

+ * @page architecture Architecture

+ * @brief ChibiOS/RT General Architecture

+ * - @ref components

+ * - @ref dependencies

+ * - @ref kernel_arch

+ * - @ref hal_arch

+ * .

+ * @section components Components

+ * ChibiOS/RT is composed of several major components, each component can be

+ * composed of one of more subsystems. The main components are:

+ * - <b>Kernel</b>, this is the platform independent part of the OS kernel.

+ * - <b>HAL</b>, this component contains a set of abstract device drivers

+ *   that offer a common I/O API to the application across all the support

+ *   platforms. The HAL code is totally portable across platforms.

+ * - <b>Port</b>, this is the platform dependent part of the OS kernel. This

+ *   component is responsible of the system startup, interrupts abstraction,

+ *   lock/unlock primitives, context switch related structures and code.<br>

+ *   The component usually contains very little code because the OS is very

+ *   portable but the quality of the implementation of the Port component

+ *   affects heavily the performance of the ported OS. It is probably the

+ *   most critical part of the whole OS.

+ * - <b>Platform</b>, this component contains a set of device drivers

+ *   implementations.

+ * - <b>Various</b>, a library of various extra components that do not belong

+ *   to any particular component but can make life easier while developing an

+ *   embedded application.

+ * .

+ * @section dependencies Dependencies

+ * The following diagram shows the relationships among the various components

+ * that compose the system:<br><br>

+ * @dot

+  digraph example {

+    node [shape=rectangle, fontname=Helvetica, fontsize=8,

+          fixedsize="true", width="1.0", height="0.25"];

+    edge [fontname=Helvetica, fontsize=8];

+

+    Application [label="Application"];

+    HAL [label="HAL"];

+    Platform [label="Platform"];

+    Kernel [label="Kernel"];

+    Port [label="Port"];

+    HW [label="Hardware", style="filled", width="3.0", height="0.3"];

+

+    Application -> Kernel;

+    Application -> HAL;

+    Application -> HW [label=" (not recommended)"];

+    HAL -> Platform;

+    HAL -> Kernel;

+    Platform -> Kernel;

+    Platform -> HW;

+    Kernel -> Port;

+    Port -> HW;

+  }

+ * @enddot

+ *

+ * @section kernel_arch Kernel Architecture

+ * The kernel itself is very modular and is composed of several subsystems,

+ * most subsystems are optional and can be switched of in the kernel

+ * configuration file @p chconf.h.<br>

+ * The current kernel subsystems are divided in five categories:

+ * - @ref base, this category contains the mandatory kernel

+ *   subsystems:

+ *   - @ref system, low level locks, initialization.

+ *   - @ref time, virtual timers and time APIs.

+ *   - @ref scheduler, scheduler APIs, all the higher level synchronization

+ *     mechanism are implemented through this subsystem, it is very flexible

+ *     but not recommended for direct use in user code.

+ *   - @ref threads, thread-related APIs.

+ *   .

+ *   Base services diagram:<br><br>

+ * @dot

+  digraph example {

+    node [shape=rectangle, fontname=Helvetica, fontsize=8,

+          fixedsize="true", width="1.0", height="0.25"];

+    edge [fontname=Helvetica, fontsize=8];

+

+    Threads -> Scheduler;

+    Scheduler-> System;

+    Scheduler-> Timers;

+    System-> Timers;

+  }

+ * @enddot

+ * - @ref synchronization, this category contains the synchronization-related

+ *   subsystems, each one of the provided mechanism can be configured out of

+ *   the kernel if not needed.

+ *   - @ref semaphores, counter semaphores subsystem.

+ *   - @ref mutexes, mutexes subsystem with support to the priority inheritance

+ *     algorithm (fully implemented, any depht).

+ *   - @ref condvars, condition variables, together with mutexes the condition

+ *     variables allow the implementation of monitor constructs.

+ *   - @ref events, event sources and event flags with flexible support for

+ *     and/or conditions and automatic dispatching to handler functions.

+ *   - @ref messages, lightweight synchronous messages.

+ *   - @ref mailboxes, asynchronous messages queues.

+ *   .

+ *   All the synchronization mechanisms are built on top of the Scheduler APIs

+ *   except Mailboxes that are build on top of Semaphores and Condition

+ *   Variables that implicitly refer to Mutexes:<br><br>

+ * @dot

+  digraph example {

+    node [shape=rectangle, fontname=Helvetica, fontsize=8,

+          fixedsize="true", width="1.0", height="0.25"];

+    edge [fontname=Helvetica, fontsize=8];

+

+    Semaphores -> Scheduler;

+    Mutexes -> Scheduler;

+    Condvars -> Scheduler;

+    Condvars -> Mutexes;

+    Events -> Scheduler;

+    Messages -> Scheduler;

+    Mailboxes -> Semaphores;

+  }

+ * @enddot

+ * - @ref memory, memory management, multiple non-alternative schemes are

+ *   available:

+ *   - @ref memcore, centralized core memory manager, this subsystems is used

+ *     by the other allocators in order to get chunks of memory in a consistent

+ *     way.

+ *   - @ref heaps, central heap manager using a first fit strategy, it also

+ *     allow the creation of multiple heaps in order to handle non uniform

+ *     memory areas.

+ *   - @ref pools, very fast fixed size objects allocator.

+ *   - @ref threads (dynamic), usually threads are static objects in ChibiOS/RT

+ *     but there is the option for dynamic threads management, please see the

+ *     article @ref article_lifecycle.

+ *   .

+ *   The various allocators follow a precise hierarchy:<br><br>

+ * @dot

+  digraph example {

+    node [shape=rectangle, fontname=Helvetica, fontsize=8,

+          fixedsize="true", width="1.0", height="0.25"];

+    edge [fontname=Helvetica, fontsize=8];

+

+    Core [label="Core Allocator"];

+    Dynamic [label="Dynamic Threads"];

+    Heaps [label="Dynamic Heaps"];

+    Pools [label="Memory Pools"];

+    C [label="C-runtime"];

+

+    Dynamic -> Heaps;

+    Dynamic -> Pools;

+    Heaps -> Core;

+    Pools -> Core;

+    C -> Core;

+  }

+ * @enddot

+ *   Please also see the article @ref article_manage_memory.

+ * - @ref io_support, the kernel also provides mechanisms and abstract data

+ *   interfaces that can be used by non-kernel components, the HAL as example.

+ *   - @ref data_streams, abstract streams interface.

+ *   - @ref io_channels, abstract I/O channels that inherits from the abstract

+ *     stream interface.

+ *   - @ref io_queues, generic, byte wide, I/O queues APIs.

+ *   .

+ * - @ref debug, debug services and APIs. The @ref registry susystem can be

+ *   seen as part of the debug category even if it finds use in non-debug

+ *   roles.

+ * .

+ * @section hal_arch HAL Architecture

+ * The HAL is a collection of abstract device drivers, it relies on the

+ * Platform component for the low level implementation on specific

+ * hardware.<br>

+ * The current internal HAL organization is the following:<br><br>

+ * @dot

+  digraph example {

+    rankdir="LR";

+

+    node [shape=rectangle, fontname=Helvetica, fontsize=8,

+          fixedsize="true", width="1.0", height="0.25"];

+    edge [fontname=Helvetica, fontsize=8];

+

+    subgraph cluster_HAL {

+      node [shape=rectangle, fontname=Helvetica, fontsize=8,

+            fixedsize="true", width="0.6", height="0.25"];

+      ADC [label="ADC"];

+      CAN [label="CAN"];

+      HAL [label="HAL"];

+      MAC [label="MAC"];

+      PAL [label="PAL"];

+      PWM [label="PWM"];

+      SER [label="SER"];

+      SPI [label="SPI"];

+      MMC_SD [label="MMC/SD"];

+      color = blue;

+      label = "HAL";

+    }

+

+    subgraph cluster_Platform {

+      node [shape=rectangle, fontname=Helvetica, fontsize=8,

+            fixedsize="true", width="0.6", height="0.25"];

+      ADC_LLD [label="ADC_LLD"];

+      CAN_LLD [label="CAN_LLD"];

+      HAL_LLD [label="HAL_LLD"];

+      MAC_LLD [label="MAC_LLD"];

+      PAL_LLD [label="PAL_LLD"];

+      PWM_LLD [label="PWM_LLD"];

+      SER_LLD [label="SER_LLD"];

+      SPI_LLD [label="SPI_LLD"];

+      color = blue;

+      label = "Platform";

+    }

+

+    node [shape=rectangle, fontname=Helvetica, fontsize=8,

+          fixedsize="true", width="1", height="0.5"];

+    edge [fontname=Helvetica, fontsize=8];

+

+    Application [label="Application"];

+    HW [label="Hardware", style="filled"];

+

+    ADC -> ADC_LLD;

+    CAN -> CAN_LLD;

+    HAL -> HAL_LLD;

+    MAC -> MAC_LLD;

+    PAL -> PAL_LLD;

+    PWM -> PWM_LLD;

+    SER -> SER_LLD;

+    SPI -> SPI_LLD;

+    MMC_SD -> SPI [constraint=false];

+

+    Application -> ADC;

+    Application -> CAN;

+    Application -> HAL;

+    Application -> MAC;

+    Application -> PAL;

+    Application -> PWM;

+    Application -> SER;

+    Application -> SPI;

+    Application -> MMC_SD;

+    ADC_LLD -> HW;

+    CAN_LLD -> HW;

+    HAL_LLD -> HW;

+    MAC_LLD -> HW;

+    PAL_LLD -> HW;

+    PWM_LLD -> HW;

+    SER_LLD -> HW;

+    SPI_LLD -> HW;

+  }

+ * @enddot

+ * <br>

+ * See @ref IO for details about the various HAL subsystems.

+ */

diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index bcdb62b6c..f8a40e2f7 100644
--- a/docs/src/articles.dox
+++ b/docs/src/articles.dox
@@ -25,6 +25,7 @@
  * - @subpage article_wakeup

  * - @subpage article_manage_memory

  * - @subpage article_stacks

+ * - @subpage article_lifecycle

  * - @subpage article_mutual_exclusion

  * - @subpage article_atomic

  * - @subpage article_saveram

diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox
index b6a9e8630..e1d5f6156 100644
--- a/docs/src/concepts.dox
+++ b/docs/src/concepts.dox
@@ -18,8 +18,8 @@
 */

 

 /**

- * @page concepts Concepts and Architecture

- * @brief ChibiOS/RT Concepts and Architecture

+ * @page concepts Kernel Concepts

+ * @brief ChibiOS/RT Kernel Concepts

  * - @ref naming

  * - @ref api_suffixes

  * - @ref interrupt_classes

@@ -28,7 +28,6 @@
  * - @ref thread_states

  * - @ref priority

  * - @ref warea

- * - @ref architecture

  * .

  * @section naming Naming Conventions

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

@@ -52,10 +51,10 @@
  * @section interrupt_classes Interrupt Classes

  * In ChibiOS/RT there are three logical interrupt classes:

  * - <b>Regular Interrupts</b>. Maskable interrupt sources that cannot

- *   preempt the kernel code and are thus able to invoke operating system APIs

- *   from within their handlers. The interrupt handlers belonging to this class

- *   must be written following some rules. See the @ref system APIs group and

- *   @ref article_interrupts.

+ *   preempt (small parts of) the kernel code and are thus able to invoke

+ *   operating system APIs from within their handlers. The interrupt handlers

+ *   belonging to this class must be written following some rules. See the

+ *   @ref system APIs group and @ref article_interrupts.

  * - <b>Fast Interrupts</b>. Maskable interrupt sources with the ability

  *   to preempt the kernel code and thus have a lower latency and are less

  *   subject to jitter, see @ref article_jitter. Such sources are not

@@ -246,17 +245,4 @@
  * .

  * See the @ref core documentation for details, the area may change on

  * the various ports and some structures may not be present (or be zero-sized).

- *

- * @section architecture Architectural Diagram

- * The following diagram shows the relationships among the hardware, the

- * various ChibiOS/RT subsystems and the application code.

- * <br><br>

- * @image html arch.png

- * <br>

- * In this diagram the device drivers are at the same level of the application

- * code because both have access to the system services and can directly

- * access the hardware.<br>

- * Of course it is possible to create in the application architecture several

- * extra layers, this is just not part of the kernel architecture but part of

- * the overall system design.

  */

diff --git a/docs/src/goals.dox b/docs/src/goals.dox
index f41308e26..eb1b2bd81 100644
--- a/docs/src/goals.dox
+++ b/docs/src/goals.dox
@@ -69,7 +69,7 @@
  * <h3>Fast and compact</h3>

  * Note, first "fast" then "compact", the focus is on speed and execution

  * efficiency and then on code size. This does not mean that the OS is large,

- * the kernel size with all the subsystems activated is around <b>5.2KiB</b>

+ * the kernel size with all the subsystems activated weighs around <b>5.3KiB</b>

  * and can shrink down around to <b>1.2Kib</b> in a minimal configuration

  * (STM32, Cortex-M3). It would be possible to make something even smaller but:

  * -# It would be pointless, it is already @a really small.

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

+    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/>.

+*/

+

+/**

+ * @page article_lifecycle Threads Lifecycle

+ * In ChibiOS/RT threads are divided in two categories:

+ * - Static threads. The memory used for static threads is allocated at

+ *   compile time so static threads are always there, there is no management

+ *   to be done.

+ * - Dynamic threads. Dynamic threads are allocated at runtime from one of

+ *   the available allocators (see @ref heaps, @ref pools).

+ * .

+ * Dynamic threads create the problem of who is responsible of releasing

+ * their memory because a thread cannot dispose its own memory.<br>

+ * This is handled in ChibiOS/RT through the mechanism of "thread references",

+ * When the @p CH_USE_DYNAMIC option is enabled the threads becomes objects

+ * with a reference counter. The memory of a thread, if dynamic, is released

+ * when the last reference to the thread is released while the thread is in

+ * its @p THD_STATE_FINAL state.<br>

+ * The following diagram explains the mechanism:

+ * @dot

+  digraph example {

+    rankdir="LR";

+    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];

+    edge [fontname=Helvetica, fontsize=8];

+

+    init [label="No thread", style="bold"];

+    alive [label="Alive"];

+    final [label="Terminated"];

+    detached [label="Detached", style="bold"];

+

+    init -> alive [label="chThdCreateX()"];

+    alive -> alive [label="chThdAddRef()"];

+    alive -> alive [label="chThdRelease()\n[ref > 0]"];

+    alive -> detached [label="chThdRelease()\n[ref == 0]"];

+    alive -> init [label="chThdWait()\n[ref == 0]"];

+    alive -> final [label="chThdExit()\nreturn"];

+    final -> final [label="chThdAddRef()"];

+    final -> final [label="chThdRelease()\nchThdWait()\n[ref > 0]"];

+    final -> init [label="chThdRelease()\nchThdWait()\n[ref == 0]"];

+  }

+ * @enddot

+ * <br>

+ * As you can see the simplest way to ensure that the memory is released is

+ * that another threads performs a @p chThdWait() on the dynamic thread.<br>

+ * If all the references to the threads are released while the thread is

+ * still alive then the thread goes in a "detached" state and its memory

+ * cannot be recovered unless there is a dedicated task in the system that

+ * scans the threads through the @ref registry subsystem and frees the

+ * terminated ones.

+ */

diff --git a/docs/src/main.dox b/docs/src/main.dox
index a5ae9a8ca..39601e563 100644
--- a/docs/src/main.dox
+++ b/docs/src/main.dox
@@ -60,6 +60,7 @@
  * <h2>Related pages</h2>

  * - @subpage lic_faq

  * - @subpage goals

+ * - @subpage architecture

  * - @subpage concepts

  * - @subpage articles

  * - @subpage testsuite

diff --git a/ext/ext.dox b/ext/ext.dox
new file mode 100644
index 000000000..4994f02de
--- /dev/null
+++ b/ext/ext.dox
@@ -0,0 +1,38 @@
+/*

+    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/>.

+*/

+

+/**

+ * @defgroup external External Components

+ * ChibiOS/RT supports several external libraries through support interfaces

+ * and/or demos. Credit should be given to the original authors for making

+ * available such useful code.<br>

+ * The current list of supported component is:

+ * - <b>uIP</b>, by Adam Dunkels at the Swedish Institute of Computer Science,

+ *   <a href="http://www.sics.se/~adam/uip/index.php/Main_Page"

+ *      target="_blank">link</a>.

+ * - <b>lwIP</b>, many authors,

+ *   <a href="http://savannah.nongnu.org/projects/lwip/"

+ *   target="_blank">link</a>.

+ * - <b>FatFs</b>, by "ChaN",

+ *   <a href="http://elm-chan.org"

+ *   target="_blank">link</a>.

+ * .

+ * External components and libraries are not directly supported and are used

+ * "as is" or with minor integration patching.

+ */

diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox
index e93ac8c5e..5ca6005f6 100644
--- a/os/kernel/kernel.dox
+++ b/os/kernel/kernel.dox
@@ -283,8 +283,8 @@
  */

 

 /**

- * @defgroup data_streams Streams

- * @brief Streams.

+ * @defgroup data_streams Data Streams

+ * @brief Abstract Data Streams.

  * @details This module define an abstract interface for generic data streams.

  * Note that no code is present, streams are just abstract classes-like

  * structures, you should look at the systems as to a set of abstract C++

@@ -297,7 +297,7 @@
  */

 

 /**

- * @defgroup io_channels I/O Abstract Channels

+ * @defgroup io_channels I/O Channels

  * @brief Abstract I/O Channels.

  * @details This module defines an abstract interface for I/O channels by

  * extending the @p BaseSequentialStream interface. Note that no code is

@@ -337,6 +337,12 @@
  */

 

 /**

+ * @defgroup registry Registry

+ * Threads Registry related APIs.

+ * @ingroup kernel

+ */

+

+/**

  * @defgroup debug Debug

  * Debug APIs and procedures.

  * @ingroup kernel

diff --git a/os/various/various.dox b/os/various/various.dox
index 19d7987d9..1a8130f4d 100644
--- a/os/various/various.dox
+++ b/os/various/various.dox
@@ -39,6 +39,15 @@
  */

 

 /**

+ * @defgroup memory_streams Memory Streams

+ * @brief Memory Streams.

+ * @details This module allows to use a memory area (RAM or ROM) using a

+ * @ref data_streams interface.

+ *

+ * @ingroup various

+ */

+

+/**

  * @defgroup event_timer Periodic Events Timer

  * @brief Periodic Event Timer.

  * @details This timer generates an event at regular intervals. The

diff --git a/readme.txt b/readme.txt
index 44cb6e0dd..1da146276 100644
--- a/readme.txt
+++ b/readme.txt
@@ -74,6 +74,10 @@
 - NEW: Added a MemoryStream class under ./os/various.

 - CHANGE: Removed an instance of a structure without name from test.h for

   increased portability of the test suite.

+- NEW: Added Mac OS-X support for the simulator. The Linux simulator has

+  been renamed to Posix simulator in order to include this change in a

+  single project.

+- NEW: New articles, sections and various improvements to the documentation.

 

 *** 1.5.1 ***

 - FIX: Fixed insufficient stack space for the idle thread in the ARMCM3 port