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

2 files changed, 113 insertions, 0 deletions

diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index a0426f41c..66268f9d7 100644
--- a/docs/src/articles.dox
+++ b/docs/src/articles.dox
@@ -29,6 +29,7 @@
  * - @subpage article_jitter

  * - @subpage article_timing

  * - @subpage article_portguide

+ * - @subpage article_design

  * .

  */

 /** @} */

diff --git a/docs/src/design.dox b/docs/src/design.dox
new file mode 100644
index 000000000..4b6780a7a
--- /dev/null
+++ b/docs/src/design.dox
@@ -0,0 +1,112 @@
+/*

+    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_design Designing an embedded application

+ * @{

+ * ChibiOS/RT offers a variety of mechanisms and primitives, often it is

+ * better to focus on a single approach for the system design and use only

+ * part of the available subsystems.<br>

+ * When designing your application you may choose among several design

+ * alternatives:

+ * - @ref nothreads

+ * - @ref messpass

+ * - @ref thdshared

+ * - @ref thdmixed

+ * .

+ * @section nothreads Single threaded superloop

+ * Correct, single thread, it is not mandatory to use the multithreading

+ * features of the OS. You may choose to implements everything as a complex

+ * state machine handled in the main thread alone. In this scenario the OS

+ * still offers a variety of useful mechanisms:

+ * - Interrupt handling.

+ * - Virtual Timers, very useful in state machines in order to handle time

+ *   triggered state transitions.

+ * - Power management.

+ * - Event Flags and/or Semaphores as communication mechanism between

+ *   interrupt handlers and the main.

+ * - I/O queues.

+ * - Memory allocation.

+ * - System time.

+ * .

+ * In this configuration the kernel size is really minimal, everything else

+ * is disabled and takes no space. You always have the option to use more

+ * threads at a later time in order to perform separate tasks.

+ *

+ * @section messpass Message Passing

+ * In this scenario there are multiple threads in the system that never

+ * share data, everything is done by exchanging messages. Each thread

+ * represents a service, the other threads can request the service by sending

+ * a message.<br>

+ * In this scenario the following subsystems can be used:

+ * - Synchronous Messages.

+ * - Mailboxes (asynchronous message queues).

+ * .

+ * The advantage of this approach is to not have to deal with mutual exclusion,

+ * each functionality is encapsulated into a server thread that sequentially

+ * serves all the requests. As example, you can have the following scenario:

+ * - A buffers allocator server.

+ * - A disk driver server.

+ * - A file system server.

+ * - One or more client threads.

+ * .

+ * Example:

+ * <br><br>

+ * @dot

+  digraph example {

+      rankdir="RL";

+      node [shape=rectangle, fontname=Helvetica, fontsize=8, fixedsize="true",

+            width="1.2", height="0.75"];

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

+      disk [label="Server Thread\nDisk Driver"];

+      buf [label="Server Thread\nBuffers Allocator"];

+      fs [label="Client&Server Thread\nFile System"];

+      cl1 [label="Client Thread"];

+      cl2 [label="Client Thread"];

+      cl3 [label="Client Thread"];

+      fs -> disk [label="I/O request", constraint=false];

+      disk -> fs [label="status", style="dotted", constraint=false];

+      fs -> buf [label="buffer request"];

+      buf -> fs [label="buffer", style="dotted"];

+      cl1 -> fs [label="FS transaction"];

+      fs -> cl1 [label="result", style="dotted"];

+      cl2 -> fs [label="FS transaction"];

+      fs -> cl2 [label="result", style="dotted"];

+      cl3 -> fs [label="FS transaction"];

+      fs -> cl3 [label="result", style="dotted"];

+  }

+ * @enddot

+ * <br><br>

+ * Note that the threads should not exchange complex messages but just

+ * pointers to data structures in order to optimize the performance.

+ * Also note that a thread can be both client and server at the same

+ * time, the FS service in the previous scenario as example.

+ *

+ * @section thdshared Threads sharing data

+ * This is the most common scenario, several threads have access to both their

+ * private data and shared data. Synchronization happens with one of the

+ * mechanisms described in the @ref article_mutual_exclusion article.<br>

+ *

+ * @section thdmixed Mixed

+ * All the above approaches can be freely mixed in a single application but

+ * usually I prefer to choose a way and consistently design the system around

+ * it. The OS is a toolbox that offers a lot of tools but you don't have

+ * to use them all necessarily.

+ */

+/** @} */