Removed redundant articles in the generated documentation.

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

28 files changed, 8 insertions, 3215 deletions

diff --git a/docs/src/architecture.dox b/docs/src/architecture.dox
deleted file mode 100644
index d71a43fc8..000000000
--- a/docs/src/architecture.dox
+++ /dev/null
@@ -1,274 +0,0 @@
-/*

-    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"];

-    Board [label="Board Setup"];

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

-

-    Application -> Kernel;

-    Application -> HAL;

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

-    HAL -> Platform;

-    HAL -> Kernel;

-    Board -> HW;

-    Platform -> Kernel;

-    Platform -> Board;

-    Platform -> HW;

-    Kernel -> Port;

-    Port -> Board [label="Optional", style="dotted"];

-    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 depth).

- *   - @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.1", height="0.25"];

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

-

-    Semaphores -> Scheduler;

-    Mutexes -> Scheduler;

-    Condvars -> Scheduler;

-    Condvars -> Mutexes;

-    Events -> Scheduler;

-    Messages -> Scheduler;

-    "Binary Semaphores" -> Semaphores;

-    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

- *     allows 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];

-

-    Application [label="Application", width="2.0"];

-    RAM [label="RAM", style="filled", width="2.0"];

-    Core [label="Core Allocator"];

-    Dynamic [label="Dynamic Threads"];

-    Heaps [label="Dynamic Heaps"];

-    Pools [label="Memory Pools"];

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

-

-    Application -> Dynamic;

-    Application -> Heaps;

-    Application -> Pools;

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

-    Application -> Core;

-    Dynamic -> Heaps;

-    Dynamic -> Pools;

-    Heaps -> Core;

-    Pools -> Core;

-    C -> Core;

-    Core -> RAM

-  }

- * @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 subsystem 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
deleted file mode 100644
index c34e34d43..000000000
--- a/docs/src/articles.dox
+++ /dev/null
@@ -1,66 +0,0 @@
-/*

-    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 articles Articles and Code Samples

- * ChibiOS/RT Articles and Code Samples:

- * - @subpage page_general

- * - @subpage page_kb

- * - @subpage page_howtos

- * .

- */

-

-/**

- * @page page_general General

- * Articles and guides not necessarily related to ChibiOS/RT.

- * - @subpage article_eclipse

- * - @subpage article_eclipse2

- * - @subpage article_jitter

- * .

- */

-

-/**

- * @page page_kb Knowledge Base

- * Articles and guides about ChibiOS/RT.

- * - @subpage article_integrationguide

- * - @subpage article_portguide

- * - @subpage article_events

- * - @subpage article_debug

- * - @subpage article_stacks

- * - @subpage article_roundrobin

- * - @subpage article_lifecycle

- * - @subpage article_mutual_exclusion

- * - @subpage article_atomic

- * - @subpage article_saveram

- * - @subpage article_timing

- * - @subpage article_design

- * .

- */

-

-/**

- * @page page_howtos How To's

- * Articles describing how to implement specific tasks using ChibiOS/RT.

- * - @subpage article_create_thread

- * - @subpage article_interrupts

- * - @subpage article_wakeup

- * - @subpage article_manage_memory

- * - @subpage article_stop_os

- * .

- */

-

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

-    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_atomic Invoking multiple primitives as a single atomic operation

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

- * reschedule 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);

-  chMtxUnlockS();

-  chSchRescheduleS();

-

-  chSysUnlock();

- * @endcode

- * The above example performs a signal operation on two semaphores, unlocks the

- * last acquired mutex and finally performs a reschedule. All the operations

- * are performed atomically.<br>

- * An hypothetical @p chSemSignalSignalWait() operation could be implemented as

- * follow:

- * @code

-  chSysLock();

-

-  chSemSignalI(&sem1);

-  chSemSignalI(&sem2);

-  chSemWaitS(&Sem3);  /* May reschedule or not. */

-  chSchRescheduleS(); /* This one reschedules if necessary. */

-

-  chSysUnlock();

- * @endcode

- * In general multiple @ref I-Class and (non rescheduling) @ref S-Class APIs

- * can be included and the block is terminated by a rescheduling @ref S-Class

- * API. An extra @p chSchRescheduleS() can be present at the very end of the

- * block, it only reschedules if a reschedule is still required.

- */

diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox
index 35c086506..bcb6a5b97 100644
--- a/docs/src/concepts.dox
+++ b/docs/src/concepts.dox
@@ -54,11 +54,15 @@
  *   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.

+ *   @ref system APIs group and the web article

+ *   <a href="http://chibios.sourceforge.net/dokuwiki/doku.php?id=chibios:howtos:interrupts">

+ *   How to write interrupt handlers</a>.

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

- *   supported on all the architectures.<br>

+ *   subject to jitter, see the web article

+ *   <a href="http://chibios.sourceforge.net/dokuwiki/doku.php?id=chibios:articles:jitter">

+ *   Response Time and Jitter</a>.

+ *   Such sources are not supported on all the architectures.<br>

  *   Fast interrupts are not allowed to invoke any operating system API from

  *   within their handlers. Fast interrupt sources may, however, pend a lower

  *   priority regular interrupt where access to the operating system is

@@ -394,6 +398,6 @@
  * - Interrupt Stack.

  * - Internal Context.

  * .

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

+ * See the port documentation for details, the area may change on

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

  */

diff --git a/docs/src/createthread.dox b/docs/src/createthread.dox
deleted file mode 100644
index f3b8e8362..000000000
--- a/docs/src/createthread.dox
+++ /dev/null
@@ -1,187 +0,0 @@
-/*

-    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_create_thread How to create a thread

- * At the system startup there are already two active threads:

- * - <b>Idle thread</b>. This thread has the lowest priority in the system so

- *   it runs only when the other threads in the system are sleeping. This

- *   threads usually switches the system in a low power mode and does nothing

- *   else.

- * - <b>Main thread</b>. This thread executes your @p main() function at

- *   startup. The main thread is created at the @p NORMALPRIO level but it

- *   can change its own priority if required. It is from the main thread

- *   that the other threads are usually created.

- * .

- * There are two kind of threads in ChibiOS/RT:

- * - <b>Static Threads</b>. This kind of threads are statically allocated in

- *   memory. The memory used by the thread cannot reused except for restarting

- *   the threads.

- * - <b>Dynamic Threads</b>. Threads created by allocating memory from a memory

- *   heap or a memory pool.

- * .

- * <h2>Creating a static thread</h2>

- * In order to create a static thread a working area must be declared using

- * the macro @p WORKING_AREA as shown:

- * @code

-static WORKING_AREA(myThreadWorkingArea, 128);

- * @endcode

- * This macro reserves 128 bytes of stack for the thread and space for all

- * the required thread related structures. The total size and the alignment

- * problems are handled inside the macro, you only need to specify the pure

- * stack size.<br>

- * A thread can be started by invoking @p chThdCreateStatic() as shown in this

- * example:

- * @code

-  Thread *tp = chThdCreateStatic(myThreadWorkingArea,

-                                 sizeof(myThreadWorkingArea),

-                                 NORMALPRIO,    /* Initial priority.    */

-                                 myThread,      /* Thread function.     */

-                                 NULL);         /* Thread parameter.    */

- * @endcode

- * The variable tp receives the pointer to the thread object, it is taken

- * by other APIs as parameter.<br>

- * Now a complete example:

- * @code

-/*

-* * My simple application.

- */

-

-#include <ch.h>

-

-/*

-* * Working area for the LED flashing thread.

- */

-static WORKING_AREA(myThreadWorkingArea, 128);

-

-/*

-* * LED flashing thread.

- */

-static msg_t myThread(void *arg) {

-

-  while (TRUE) {

-    LED_ON();

-    chThdSleepMilliseconds(500);

-    LED_OFF();

-    chThdSleepMilliseconds(500);

-  }

-}

-

-int main(int argc, char *argv[]) {

-

-  /* Starting the flashing LEDs thread.*/

-  (void)chThdCreateStatic(myThreadWorkingArea, sizeof(myThreadWorkingArea),

-                          NORMALPRIO, myThread, NULL);

-  .

-  .

-  .

-}

- * @endcode

- * Note that the memory allocated to myThread() is statically defined and

- * cannot be reused. Static threads are ideal for safety applications because

- * there is no risk of a memory allocation failure because progressive heap

- * fragmentation.

- *

- * <h2>Creating a dynamic thread using the heap allocator</h2>

- * In order to create a thread from a memory heap is very easy:

- * @code

-  Thread *tp = chThdCreateFromHeap(NULL,            /* NULL = Default heap. */

-                                   THD_WA_SIZE(128),/* Stack size.          */

-                                   NORMALPRIO,      /* Initial priority.    */

-                                   myThread,        /* Thread function.     */

-                                   NULL);           /* Thread parameter.    */

- * @endcode

- * The memory is allocated from the spawned heap and the thread is started.

- * Note that the memory is not freed when the thread terminates but when the

- * thread final status (its return value) is collected by the spawning thread.

- * As example:

- * @code

-static msg_t myThread(void *arg) {

-

-  unsigned i = 10;

-  while (i > 0) {

-    LED_ON();

-    chThdSleepMilliseconds(500);

-    LED_OFF();

-    chThdSleepMilliseconds(500);

-    i--;

-  }

-  return (msg_t)i;

-}

-

-int main(int argc, char *argv[]) {

-

-  Thread *tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(128), NORMALPRIO+1,

-                                   myThread, NULL);

-  if (tp == NULL)

-    chSysHalt();    /* Memory exausted. */

-  

-  /* The main thread continues its normal execution.*/

-  .

-  .

-  /*

-*   * Now waits for the spawned thread to terminate (if it has not terminated

-*   * already) then gets the thread exit message (msg) and returns the

-*   * terminated thread memory to the heap (default system heap in this

-*   * example).

-   */

-  msg_t msg = chThdWait(tp);

-  .

-  .

-}

- * @endcode

- *

- * <h2>Creating a dynamic thread using the memory pool allocator</h2>

- * A pool is a collection of equally sized memory blocks, creating a thread from

- * a memry pool is very similar to the previous example but the memory of

- * terminated threads is returned to the memory pool rather than to a heap:

- * @code

-static msg_t myThread(void *arg) {

-

-  unsigned i = 10;

-  while (i > 0) {

-    LED_ON();

-    chThdSleepMilliseconds(500);

-    LED_OFF();

-    chThdSleepMilliseconds(500);

-    i--;

-  }

-  return (msg_t)i;

-}

-

-int main(int argc, char *argv[]) {

-

-  Thread *tp = chThdCreateFromMemoryPool(myPool, NORMALPRIO+1, myThread, NULL);

-  if (tp == NULL)

-    chSysHalt();    /* Pool empty. */

-  

-  /* The main thread continues its normal execution.*/

-  .

-  .

-  /*

-*   * Now waits for the spawned thread to terminate (if it has not terminated

-*   * already) then gets the thread exit message (msg) and returns the

-*   * terminated thread memory to the original memory pool.

-   */

-  msg_t msg = chThdWait(tp);

-  .

-  .

-}

- * @endcode

- */

diff --git a/docs/src/credits.dox b/docs/src/credits.dox
deleted file mode 100644
index d0a40cb04..000000000
--- a/docs/src/credits.dox
+++ /dev/null
@@ -1,97 +0,0 @@
-/*

-    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 credits Copyright and Credits

- * @brief Copyright and Credits

- *

- * <h2>Copyright Statement</h2>

-@verbatim

-    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.

-@endverbatim

- *

- * <h2>Contributions and Copyright Assignment</h2>

- * If you plan to contribute code to the ChibiOS/RT project then there is a

- * requirement you should be aware of: contributing code for inclusion in

- * the ChibiOS/RT <b>main line</b> requires  assigning the copyright on the

- * contributed code to me (Giovanni Di Sirio).<br>

- * This may sound a bit strange but is pretty standard for this kind of

- * projects, there are several reasons for this requirement:

- * - ChibiOS/RT will probably also become a commercial product and it would

- *   not be possible to re-license the code without ownership. Note that the

- *   commercial product would not be a different or better product, just the

- *   same GPL product made available, on request, under a different license.

- *   The code will always be available to you under the current licensing

- *   terms.

- * - Ownership is required when changing the licensing terms and this happens

- *   each time the project goes from development/unstable to stable and

- *   back because the addition/removal of the GPL linking exception.

- * - It will be easier for the project adopters to have a single ownership

- *   point in case of licensing issues (both GPL or commercial).

- * - Losing the ownership on the code could preclude me the opportunity to

- *   make this project a full time job as I hope.

- * - I definitely don't want to have to sort out copyright related issues

- *   in the future so better be clear than sorry.

- * .

- * Note that contributions will always be welcome even without such copyright

- * assignment, the difference is that the contributed code would not be

- * merged into the main line, it will still made available as contributed

- * code with the contributor(s) copyright notice intact.<br>

- * Submissions of code with copyright notice should only happen through

- * email, please do not commit code with copyright notices directly on

- * the repository.<br>

- * When submitting code please <b>state clearly your intention to keep the

- * copyright</b> on your work by adding your own copyright notice within the

- * source code and by clearly mentioning your intentions in the message. Code

- * contributed without copyright notice will be considered donated.<br>

- * If in doubt with licensing issues please don't hesitate to contact me

- * in order to sort out any problem you may have.<br>

- * Of course the copyright assignment does not mean you would not be

- * recognized for your hard work, see the following section.

- *

- * <h2>Credits</h2>

- * I want to thank all the people that directly or indirectly contributed

- * to the project, I beg pardon if someone is missing:

- * - <b>Adamo Reggiani</b>, working on the Fujitsu port.

- * - <b>Alexander Kozaruk</b>, AT91SAM7S256 demo and description files for

- *   the Olimex SAM7-P256 board.

- * - <b>Brian Weaver</b>, STM8 port, STM8 and STM32 testing and improvements.

- * - <b>Egon Carusi</b>, STM32 port improvements, testing and bug fixes.

- * - <b>Enrico Cavazza</b>, working on the Fujitsu port and a GUI subsystem.

- * - <b>Eric Weddington</b>, because his work on WinAVR and helping me sorting

- *   out issues with the ChibiOS/RT license.

- * - <b>Isidoro Orabona</b>, co-developer of the ChibiOS/RT grandfather back

- *   in 1988, it is a long long story involving a 6502 and a Z80...

- * - <b>Jacek</b>, Ride7 demo for STM32 Primer.

- * - <b>Leon Woestenberg</b>, CondVars idea and implementation, documentation

- *   improvements and a lot of other ideas, he also helped with the lwIP port

- *   (he is one of the developers of that project too).

- * - <b>Leszek Bednarz</b>, H8S and ColdFire ports and drivers maintainer.

- * - <b>Liam Staskawicz</b>, Posix simulator, AT91SAM7x and STM32 related

- *   contributions, general improvements, many bug fixes and excellent

- *   suggestions.

- * - <b>Michael Fischer</b>, because the work on YAGARTO and the excellent

- *   feedback.

- * - <b>Riccardo Scanu</b>, another long story, this time involving reverse

- *   engineering and giant robots...

- * - <b>Vladimir</b>, first tested and fixed the AVR port, I don't know the

- *   surname but he has been the first contributor.

- * - <b>Walter Goossens</b>, several fixes to the LPC21xx support.

- * .

- */

diff --git a/docs/src/debug.dox b/docs/src/debug.dox
deleted file mode 100644
index 341e852c6..000000000
--- a/docs/src/debug.dox
+++ /dev/null
@@ -1,138 +0,0 @@
-/*

-    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_debug Debugging ChibiOS/RT applications

- * ChibiOS/RT offers several mechanisms that can help in the debug phase of

- * the development cycle.

- *

- * <h2>What this guide does not cover</h2>

- * This guide assumes knowledge in following areas:

- * - General knowledge of embedded development.

- * - RTOS concepts.

- * - Setup of your specific target hardware and toolchain.

- * - Knowledge of your toolchain. The guide will explain what you need to do,

- *   not how it is done using you specific debugger, compiler, JTAG probe and

- *   target hardware.

- * .

- * <h2>Helpful debugging configuration settings</h2>

- * There are several settings in your kernel configuration file

- * (see @ref templates/chconf.h) that you may want to  enable during

- * debugging and in general during the whole development process.

- * - @p CH_OPTIMIZE_SPEED=FALSE, this disables inlining into the kernel code

- *   and makes it easier to debug using your debugger, you may also want

- *   to reduce or disable compiler optimizations (-O0 using GCC).

- * - @p CH_DBG_ENABLE_CHECKS=TRUE, this setting enables the checks on the

- *   API parameters, useful to understand if you are passing wrong parameters

- *   to the OS functions.

- * - @p CH_DBG_ENABLE_ASSERTS=TRUE, this setting enables the OS internal

- *   consistency checks, this can trap several kind of errors in the user

- *   code (or in the kernel itself).

- * - @p CH_DBG_ENABLE_STACK_CHECK=TRUE, this setting enables checks on

- *   threads stack overflow. Note that this option is not available in

- *   all ports, check your port documentation. If not supported then it

- *   is silently ignored, see also the article @ref article_stacks.

- * - @p CH_DBG_FILL_THREADS=TRUE, this setting enables the threads workspace

- *   filling, this can help examining the stack usage from your debugger.

- * .

- * Note that all the failed checks lock the kernel into the @p port_halt()

- * function. In order to assess what triggered the lock the global variable

- * @p panic_msg must be inspected using the debugger, the variable is a

- * pointer to an error message (a zero terminated string), the pointer may

- * contain @p NULL if the lock was triggered by a stack overflow.

- *

- * <h2>Common errors and symptoms</h2>

- * There are some common errors while using an RTOS, use the following

- * table as a check list, if your problem is not a generic programming error

- * then probably it is one of the following common RTOS/embedded related

- * mistakes:

- * - Insufficient stack allocated to one or more threads.<br>

- *   Common symptoms:

- *   - Target instability.

- *   - Target locked into the @p port_halt() function.

- *   - Target trapped into an exception handler (architecture dependent).

- *   - Target apparent self reset (not real resets usually).

- *   .

- * - Insufficient stack allocated to the IRQ stack (in those architectures

- *   that have a separate IRQ stack, ARM as example).<br>

- *   Common symptoms:

- *   - Target instability.

- *   - Target trapped into an exception handler (architecture dependent).

- *   - Target apparent self reset (not real resets usually).

- *   .

- * - Use of a non reentrant function from within an interrupt handler, as

- *   example most C runtime functions.<br>

- *   Common symptoms:

- *   - Target instability.

- *   - Unexpected application behavior.

- *   .

- * - Missing use of a mutual exclusion mechanism to protect data

- *   (or non reentrant code) shared among multiple threads and/or

- *   threads and interrupt handlers, see also the article

- *   @ref article_mutual_exclusion.<br>

- *   Common symptoms:

- *   - Target instability.

- *   - Unexpected application behavior.

- *   .

- * - Use of S-class or I-class APIs outside a proper lock state, see the

- *   @ref concepts article, specifically the @ref api_suffixes and

- *   @ref system_states sections.<br>

- *   Common symptoms:

- *   - Target instability.

- *   - Target trapped into an exception handler (architecture dependent).

- *   - Target apparent self reset (not real resets usually).

- *   .

- * - Use of a non I-class API from an interrupt handler, see the

- *   @ref concepts article, specifically the @ref api_suffixes and

- *   @ref system_states sections.<br>

- *   Common symptoms:

- *   - Target instability.

- *   - Target trapped into an exception handler (architecture dependent).

- *   - Target apparent self reset (not real resets usually).

- *   .

- * - Wrong threads priority assignment. One of the most critical things

- *   to do when designing an RTOS based application is to assign correct

- *   priorities to the threads in the system.<br>

- *   Common symptoms:

- *   - Excessive or unpredictable response times.

- *   - Threads that appear to be never executed (CPU intensive threads at

- *     higher priority).

- *   .

- * .

- * <h2>General suggestions</h2>

- * For the less expert users, there are several things you may do in order

- * to minimize the need for debugging:

- * - Read carefully the documentation first.

- * - Try to find a code examples for things are you going to do, good sources

- *   are: the documentation, the test code, under "./test" you will

- *   find examples for almost any API in the ChibiOS/RT kernel and most

- *   common RTOS related tasks, under "./testhal" there are examples

- *   regarding the various device drivers, the various demos contain

- *   good code samples too).

- * - Start your application from an existing demo, add things one at a

- *   time and test often, if you add too many things at once then finding a

- *   small problem can become a debugging nightmare. Follow the cycle: think,

- *   implement, test, repeat.

- * - If you are stuck for too much time then consider asking for advice.

- * - Report bugs and problems, bugs can be fixed, problems can become new

- *   articles in the documentation (this and other documentation articles

- *   spawned from questions in the forum or in the tracker).

- * - Never give up :-)

- * .

- */

diff --git a/docs/src/design.dox b/docs/src/design.dox
deleted file mode 100644
index 80a5b8af8..000000000
--- a/docs/src/design.dox
+++ /dev/null
@@ -1,110 +0,0 @@
-/*

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

- */

diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox
deleted file mode 100644
index 4e2dfe0fc..000000000
--- a/docs/src/eclipse.dox
+++ /dev/null
@@ -1,169 +0,0 @@
-/*

-    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_eclipse Setting up a free embedded IDE

- * @brief Free advanced embedded IDE for ChibiOS/RT.

- * details This article will explain how to setup a free toolchain for use with

- * ChibiOS/RT and general embedded development.<br>

- * The guide is meant mainly for Windows users but notes about Linux and

- * MAC OSX are present where the setup differs, mostly the toolchain is

- * exactly the same.

- *

- * <h2>What this guide does not cover</h2>

- * We will not enter in details of common system tasks like and not limited to:

- * - Installing applications (unless a special procedure is required).

- * - Creating desktop shortcuts.

- * - Adding paths to the PATH variable.

- * - Creating environment variables.

- * - Any other normal PC usage task.

- * - Use of the toolchain, the use is covered by the @ref article_eclipse2

- *   article.

- * .

- *

- * <h2>Article Index</h2>

- * - @ref required_components

- * - @ref install_chibios

- * - @ref install_compiler

- * - @ref install_eclipse

- * - @ref install_zylin

- * - @ref install_openocd

- * - @ref install_doxygen

- * - @ref install_graphviz

- * - @ref install_eclox

- * .

- *

- * @section required_components Required Components

- * The first thing to do is to download all the required components, beginners

- * should avoid the optional components initially:

- * - A JTAG probe supporting GDB and OpenOCD, a list of compatible devices is

- *   available on the <a href="http://openocd.berlios.de/web/" target="_blank">

- *   OpenOCD home page</a>, more exactly

- *   <a href="http://openocd.berlios.de/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware"

- *   target="_blank">here</a>.

- * - <a href="https://sourceforge.net/projects/chibios/" target="_blank">

- *   ChibiOS/RT latest stable release</a>.

- * - <a href="http://www.java.com/en/" target="_blank">Java runtime</a>, you

- *   probably already have this installed.

- * - <a href="http://www.eclipse.org/downloads/" target="_blank">Eclipse IDE

- *   for C/C++ Developers</a>

- * - <a href="http://www.yagarto.de/" target="_blank">YAGARTO ARM toolchain

- *   for Windows</a>, note that you need both the compiler and the tools (make

- *   and binutils).

- * - Zylin plugin for on-board debugging, see @ref install_zylin section.

- * - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but

- *   you can download them from <a href="http://www.freddiechopin.info/"

- *   target="_blank">here</a>. Linux users can try

- *   <a href="http://home.comcast.net/~mcatudal/" target="_blank">here</a>.

- * - <b>Optional</b>, <a href="http://www.stack.nl/~dimitri/doxygen/"

- *   target="_blank">MinGW compiler</a>, needed if you want to compile, debug

- *   and run the simulator from within Eclipse. Linux users do not need this

- *   one because all Linux distributions include the native GCC.

- * - <b>Optional</b>, <a href="http://www.stack.nl/~dimitri/doxygen/"

- *   target="_blank">Doxygen</a>, it is only required if you want to

- *   generate documentation from source files.

- * - <b>Optional</b>, <a href="http://www.graphviz.org/" target="_blank">

- *   Graphwiz</a>, it is only required if you want to generate diagrams

- *   within documentation from source files.

- * - <b>Optional</b>, <a href="http://home.gna.org/eclox/" target="_blank">

- *   Eclox</a>, it is only required if you want to generate documentation

- *   from source files from within Eclipse.

- * .

- *

- * @section install_chibios ChibiOS/RT Installation

- * Just unzip it into a directory in your home folder, Windows users may

- * consider c:@\projects@\chibios. It is strongly suggested to not put version

- * numbers into the ChibiOS/RT directory name because Eclipse workspaces

- * have absolute paths inside and you don't want to setup everything again

- * each time a new ChibiOS/RT version is released, use plain "chibios".

- *

- * @section install_compiler GCC ARM Compiler Installation

- * Simply follow the YAGARTO installation guide. Linux/MACOS users have several

- * other options:

- * - Download the latest CodeSourcery free Linux package.

- * - Build it yourself, Liam recommended a build script

- *   <a href="http://github.com/esden/summon-arm-toolchain" target="_blank">

- *   here</a>, it looks interesting.

- * .

- * Make sure that the compiler binaries directory is listed  in the PATH

- * variable or Eclipse would not be able to locate it.

- *

- * @section install_eclipse Eclipse Installation

- * Eclipse is distributed into a compressed archive, there is no installation

- * procedure:

- * - Verify if you have Java installed, if not install the runtime. You may

- *   verify this using the command: "java -version". Make sure you have at

- *   least version 1.6.

- * - Create an eclipse directory in your home and unpack the archive there.

- *   Windows users may unpack it into c:@\program files@\eclipse.

- * - Create a desktop shortcut or other way to launch the Eclipse executable

- *   easily.

- * - Launch Eclipse.

- * - Eclipse will ask you a directory for its initial workspace, make it point

- *   to the ChibiOS/RT root directory (you may have as many workspaces you

- *   want, keep this for later), make sure to select the check box or it will

- *   ask you again each time.

- *   <br><br>

- *   @image html tool001.jpg

- *   <br>

- * - Now you should see the welcome screen, close it and you will be in the

- *   normal C/C++ perspective.

- * - Unselect "Project->Build Automatically" unless you like insanity.

- * - Disable the "usage collector" in

- *   "Window->Preferences->Usage_Data_Collector" by unselecting "Enable

- *   capture".

- * - If you are behind a proxy or firewall (corporate users usually are)

- *   configure the correct parameters in

- *   "Window->Preferences->General->Network_Connections".

- * - Let Eclipse auto update to the latest version "Help->Check_for_Updates".

- * .

- *

- * @section install_zylin Zylin Plugin Installation

- * Eclipse requires an hardware debugger component in order to perform on board

- * execution and debug.

- * - Open Eclipse, then "Help->Install_New_Software...".

- * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt

- *   into the location field, then press OK. The Zylin plugin will appear in the

- *   available plugins view, select and install it.

- *   <br><br>

- *   @image html tool002.jpg

- * .

- *

- * @section install_openocd OpenOCD Installation

- * Windows users just have to use the installer. Linux user should follow the

- * normal installation procedure for deb or rpm packages, of course it is also

- * possible to build it from the source code.

- *

- * @section install_doxygen Doxygen Installation

- * Just use the installer, Linux users probably have Doxygen already available

- * from the repositories. Make sure that the Doxygen binaries directory

- * is listed in the PATH variable or Eclipse would not be able to locate it.

- *

- * @section install_graphviz Graphviz Installation

- * Just use the installer, Linux users probably have Graphviz already available

- * from the repositories. Make sure that the Graphviz binaries directory

- * is listed in the PATH variable or Doxygen would not be able to locate it.

- *

- * @section install_eclox Eclox Installation

- * Use the same installation steps used for the Zylin plugin except use

- * http://download.gna.org/eclox/update as URL. Install "Eclox" not "Eclox

- * Hot".

- * After installing Eclox you will be able to compile Doxygen documentation

- * using the button with the blue @@ inside.

- */

diff --git a/docs/src/eclipse2.dox b/docs/src/eclipse2.dox
deleted file mode 100644
index 88a222fc8..000000000
--- a/docs/src/eclipse2.dox
+++ /dev/null
@@ -1,249 +0,0 @@
-/*

-    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_eclipse2 Embedded development using Eclipse

- * @brief Compiling and debugging ChibiOS/RT applications using Eclipse.

- * @details This article will explain how to use an Eclipse based toolchain

- * (see @ref article_eclipse) to develop ChibiOS/RT based applications.

- * This guide will allow you to:

- * - Importing ChibiOS/RT demos into the Eclipse environment.

- * - Edit and reformat your source code.

- * - Compile and examine errors and warnings.

- * - Upload your program on the target board.

- * - Debug your code on the target board both in high level language and

- *   assembler.

- * - Develop embedded applications with or without ChibiOS/RT.

- * .

- *

- * <h2>What this guide does not cover</h2>

- * This guide assumes knowledge in following areas:

- * - OpenOCD setup is not covered by this guide because the setup changes

- *   depending on the JTAG probe used, the target MCU and also the target

- *   board. The guide will show the setup for a specific JTAG probe and a

- *   specific target, a valuable source for the OpenOCD setup is the

- *   <a href="http://forum.sparkfun.com/viewforum.php?f=18" target="_blank">

- *   dedicated forum</a>, most questions you may have about OpenOCD have

- *   most likely already been answered there.

- * - Hardware setup.

- * .

- * In general this guide is not a replacement for the Eclipse, GCC, Make,

- * binutils, newlib, GDB, OpenOCD user manuals, the guide simply aims to

- * give you a faster start.

- *

- * <h2>Article Index</h2>

- * - @ref eclipse2_requirements

- * - @ref eclipse2_importing

- * - @ref eclipse2_creating

- * - @ref eclipse2_compiling

- * - @ref eclipse2_configuring

- *   - @ref eclipse2_configuring_gdb

- *   - @ref eclipse2_configuring_openocd

- *   .

- * - @ref eclipse2_debugging

- *   - @ref eclipse2_debugging_start

- *   - @ref eclipse2_debugging_stop

- *   .

- * .

- *

- * @section eclipse2_requirements Required Components

- * This guide requires:

- * - An Eclipse/GCC/OpenOCD based toolchain, as example the one described in

- *   the article @ref article_eclipse.

- * - An Olimex ARM-USB-OCD JTAG probe, this guide applies to any other ARM

- *   JTAG probe as long it is supported by OpenOCD.

- * - An Olimex STM32-P103 target board, this guide applies to any other ARM

- *   target except for the OpenOCD setup part.

- * - A terminal emulator for capturing the board serial output, Windows users

- *   may use Hyper Terminal, Linux and MAC OS-X users may use

- *   <a href="http://cutecom.sourceforge.net/" target="_blank">CuteCom</a>.

- *   All ChibiOS/RT demos generate on the serial port a test report when a

- *   button on the target board is pressed, other demos may activate a command

- *   shell on the serial port, in both cases a terminal emulator is required.

- * .

- *

- * @section eclipse2_importing Importing existing ChibiOS/RT demos into Eclipse

- * The first step is to import a project into the Eclipse environment.

- * ChibiOS/RT demos do not include Eclipse project files but just a normal

- * Makefile. Eclipse is able to import a Makefile project and create

- * its own project file so this is not a problem. This is how it is done:

- * - Open you Eclipse environment and select the workspace created into the

- *   ChibiOS/RT project directory.

- * - From within Eclipse select "File->New->C_Project", a dialog box will show.

- * - Select "Makefile_project->Empty_Project" in the "Project type:" box.

- * - Select "-- Other Toolchain --" in the "Toolchains:" box.

- * - Unselect the "Use default location" check box.

- * - Select the demo directory using the "Browse..." button. Something like

- *   "C:\Projects\ChibiOS-RT\demos\ARMCM3-STM32F103-GCC" will appear in the

- *   "Location:" box.

- * - In the project name box put the same name of the directory containing

- *   the demo, ARMCM3-STM32F103-GCC in this example.

- *   <br><br>

- *   @image html eclipse003.jpg

- *   <br>

- * - Press the "Finish" button and the project will be created and shown in

- *   the "Project Explorer".

- * - Right click on the imported project and select "Index->Rebuild", this

- *   will make Eclipse build its internal symbols database.

- * - Repeat the above steps for each ChibiOS/RT demo you want to import in

- *   Eclipse, all the demos that have a makefile can be imported.

- * .

- *

- * @section eclipse2_creating Creating a new ChibiOS/RT application

- * If you want to create a new application it is recommended that you create

- * a Makefile project first then you can import it into eclipse using the above

- * procedure. Makefile projects have the advantage that can be compiled

- * everywhere even without Eclipse. Creation steps:

- * - Create your own development directory under the ChibiOS/RT installation

- *   directory, as example "chibios/myprojects".

- * - Copy an existing demo, of course choose a demo using your same target,

- *   under the new directory and rename it, as example

- *   "chibios/myprojects/myapplication".

- * - Customize the Makefile if needed, usually you just need to do this if

- *   your application is composed by more than one source file. You may also

- *   want to remove the ChibiOS/RT test code from your application.

- * - Once your makefile is ready, import the project under the Eclipse

- *   workspace using the procedure described in @ref eclipse2_importing.

- * .

- *

- * @section eclipse2_compiling Compiling and Cleaning applications

- * Once imported, an application can be compiled by using the "Build All" in

- * the toolbar or by right clicking on the project and selecting "Build

- * Project". In order to clean a project (removing all the temporary and binary

- * files) right click on the project and select "Clean Project".

- * <br><br>

- *   @image html eclipse004.jpg

- * <br>

- * The compilation result is visible as a complete log in the "Console" window,

- * the detail of all errors an warnings is available in the "Problems" window.

- * <br><br>

- *   @image html eclipse005.jpg

- * <br>

- * The build process produces the binary files specified in the Makefile, all

- * the ChibiOS/RT demos produce binary files named ch.elf, ch.bin and/or

- * ch.hex. The image must be loaded on the target board in order to execute

- * it. The build process usually creates also some other useful files

- * containing details about the built application (usually named ch.map and

- * ch.dmp).

- *

- * @section eclipse2_configuring Preparing for Debug

- * In order to debug your application a debug configuration must be created.

- * The configuration instructs GDB (the source debugger used by Eclipse) on

- * how to load the image, load the symbols and place the initial breakpoint

- * in the make function. Note that GDB performs its function by connecting

- * to a "GDB server", the DGB server implements the low level communication

- * with the target device through the JTAG probe. In our scenario the GDB

- * server functionality is performed by OpenOCD, this mean that OpenOCD must

- * be running while performing a debug session within Eclipse.

- *

- * @subsection eclipse2_configuring_gdb Creating a GDB Debug Configuration

- * A target specific debug configuration is required in order to:

- * - Establish a connection with the GDB server.

- * - Stop and reset the target.

- * - Upload the binary code in Flash or RAM.

- * - Set an initial breakpoint in the main function.

- * - Start the target (which will immediately stop on the breakpoint).

- * .

- * The first thing to do is to open the "Debug Configurations..." dialog:

- *   <br><br>

- *   @image html eclipse006.jpg

- *   <br>

- * The configuration dialog will appear, we must create a native Zylin

- * configuration:

- *   <br><br>

- *   @image html eclipse007.jpg

- *   <br>

- * Now we must give the configuration a name, "ARMCM3-STM32F103-GCC (flash and

- * run)" in this example, then setup the various configuration pages as follow:

- * <br><br>

- * The "Main" tab:

- * @image html eclipse008.jpg

- * <br><br>

- * The "Debugger" tab:

- * @image html eclipse009.jpg

- * <br><br>

- * The "Commands" tab:

- * @image html eclipse010.jpg

- * <br>

- * Note that the "Commands" tab contains the part that changes depending on

- * the target. The complete commands sequence (it is not fully visible in the

- * image) for STM32 is:

- * @code

- * monitor soft_reset_halt

- * monitor wait_halt

- * monitor poll

- * monitor flash probe 0

- * monitor stm32x mass_erase 0

- * monitor flash write_bank 0 ch.bin 0

- * monitor soft_reset_halt

- * symbol-file ch.elf

- * thbreak main

- * continue

- * @endcode  

- * <br><br>

- * The "Common" tab:

- * @image html eclipse011.jpg

- * <br>

- * Now the debug configuration is complete.

- *

- * @subsection eclipse2_configuring_openocd Configuring and running OpenOCD

- * OpenOCD must be run, with appropriate parameters, before starting your

- * debug session. Please refer to the OpenOCD documentation in order to

- * properly launch it for your target.

- * <br>**To be completed**

- *

- * @section eclipse2_debugging Debugging

- * Now we are ready to debug an application on the target. Note that Eclipse

- * have a mechanism called "Perspectives", you edit and compile your source

- * code while you are in the "C/C++ perspective" while the debugging is

- * performed in the "Debug perspective". You can switch perspective at any

- * time, even while there is an active debug session. If you install more of

- * the many Eclipse extension plugins (there are thousands) you may have even

- * more perspectives available.

- *

- * @subsection eclipse2_debugging_start Starting a Debug Session

- * In order to start a debugging session first make sure that OpenOCD is

- * running then press the drop down menu on the right side of the

- * debug icon in the toolbar (the small green bug) and select your

- * debug configuration (we created just one but you may have multiple

- * debug configurations in your project, as example I usually create

- * another debug configuration that just starts the target without

- * uploading the code).

- * <br><br>

- * @image html eclipse012.jpg

- * <br>

- * The debugger will be initialized, you will see the operation in progress on

- * the console then Eclipse will switch to the debug perspective and you will

- * see your program stopped on the default breakpoint in the main function.

- * <br><br>

- * @image html eclipse013.jpg

- * <br>

- * From there you can perform all the usual debugging tasks, set breakpoints,

- * single step execution, variables, memory and registers inspection etc.

- * Please refer to the Eclipse documentation about those "normal" operations.

- * Note that if the debugging start procedure hangs then there is probably

- * an error in your configuration or problems with the target, read the

- * console log and/or the OpenOCD output in order to understand where the

- * problem is.

- *

- * @subsection eclipse2_debugging_stop Stopping a Debug Session

- * From the debug perspective press the stop button (small red square) in the

- * debug window, the target will be stopped and you may both return to the

- * C/C++ perspective or start it again.

- */

diff --git a/docs/src/events.dox b/docs/src/events.dox
deleted file mode 100644
index 27de187e4..000000000
--- a/docs/src/events.dox
+++ /dev/null
@@ -1,124 +0,0 @@
-/*

-    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_events Events Explained

- * Events are an important feature in ChibiOS/RT, most device drivers generate

- * events in order to notify the application that something happened at the

- * I/O level.<br>

- * While event flags are not something unknown in other operating systems,

- * their peculiar implementation in ChibiOS/RT requires a more in depth

- * explanation.<br>

- * Lets start with the events related terminology:

- * - <b>Event Source</b>, an @p EventSource is a system object that can be

- *   broadcasted asynchronously in response of a system event, as example,

- *   when the CAN driver receives a packet from the CAN bus it broadcasts

- *   an event source in order to inform the registered threads that a packet

- *   has just arrived.

- * - <b>Broadcast</b>, the operation performed on an event source in order

- *   to inform the registered threads that an event just occurred.

- *   Broadcasting can happened both in interrupt handlers and in threads.

- * - <b>Event Listener</b>, a system object that associates a @p Thread object

- *   to an event source. The process of associating a @p Thread to an

- *   @p EventSource using an @p EventListener is called registration.

- * - <b>Registration</b>, action performed by a thread in order to be informed

- *   of events from a specific event source. Of course a thread can be

- *   registered on more than one event source by using multiple

- *   @p EventListener objects. Threads can also unregister from an event

- *   source.

- * - <b>Pending Events</b>, event flags waiting to be served by a thread.

- * - <b>Add</b>, the broadcast operation adds (logical or) an events

- *   mask to all the registered threads.

- * - <b>Wait</b>, synchronous operation performed by a thread in order to

- *   wait a specific combination of events. The API offers a variety of

- *   wait functions, please refer to the events API documentation.

- * .

- * Note that events are asynchronously generated, as example in an interrupt

- * handler, but are synchronously served.

- *

- * <h2>Events related data structures</h2>

- * The following diagram explains the relationship between an event source,

- * its list of event listeners and the registered threads.

- * @dot

-  digraph example {

-    rankdir="LR";

-

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

-          fixedsize="true", width="1.0", height="0.5"];

-    edge [fontname=Helvetica, fontsize=8, sep=3.0];

-

-    es [shape=record, label="EventSource | es_next", style="bold"];

-

-    subgraph cluster_0 {

-      fontname=Helvetica;

-      label = "Listeners List";

-      color = blue;

-      node [shape=record, fontname=Helvetica, fontsize=8,

-            fixedsize="true", width="1.5", height="1.0"];

-      el4 [label="EventListener 4 | el_mask: 0x0001 | el_listener | el_next"];

-      el3 [label="EventListener 3 | el_mask: 0x0C00 | el_listener | el_next"];

-      el2 [label="EventListener 2 | el_mask: 0x0001 | el_listener | el_next"];

-      el1 [label="EventListener 1 | el_mask: 0x0004 | el_listener | el_next"];

-      el1 -> el2 -> el3 -> el4 [label=" el_next", constraint=false];

-    }

-

-    subgraph cluster_1 {

-      fontname=Helvetica;

-      label = "Registered Threads";

-      color = blue;

-      node [shape=record, fontname=Helvetica, fontsize=8,

-            fixedsize="true", width="1.5", height="0.8"];

-      t1 [label="Thread 1 | p_epending:0x0000 | p_ewmask:0xFFFF"];

-      t2 [label="Thread 2 | p_epending:0x000F | p_ewmask:0x0C01"];

-      t3 [label="Thread 3 | p_epending:0x0008 | p_ewmask:0x0001"];

-      t4 [label="Thread 4 | p_epending:0x0000 | p_ewmask:0xFFFF"];

-    }

-

-    es -> el1 [label=" es_next"];

-    el4 -> es [label=" el_next"];

-    el1 -> t1 [label="el_listener"];

-    el2 -> t2 [label="el_listener"];

-    el3 -> t3 [label="el_listener"];

-    el4 -> t4 [label="el_listener"];

-  }

- * @enddot

- * Note that each event listener has a different bit mask to be added on

- * its associated thread when the event source is broadcasted, this means

- * that each thread can define its own event identifiers independently. A

- * broadcast operation can also add more than one bit on the

- * registered threads.<br>

- * The threads have a variety of wait primitives, they can wait for one

- * or more event flags, and can also specify AND/OR conditions, as example

- * a thread can wait for any of the specified events or wait for all the

- * specified events.<br>

- * The field @p p_epending is the mask of the currently pending events,

- * the field @p p_ewmask is the mask of the events the thread is interested

- * on in that moment (AND or OR condition depending on the invoked

- * wait API).

- *

- * <h2>Use Scenarios</h2>

- * Events are best used when one of more of the following conditions are

- * required:

- * - Having to wait on multiple conditions, Events are the only mechanism

- *   that easily allow that.

- * - Synchronous response to one or more asynchronous events.

- * - Single threaded applications working in a event driver environment (but

- *   events are not limited to single threaded applications).

- * .

- */

diff --git a/docs/src/goals.dox b/docs/src/goals.dox
deleted file mode 100644
index 6dc8f0034..000000000
--- a/docs/src/goals.dox
+++ /dev/null
@@ -1,88 +0,0 @@
-/*

-    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 goals Project Goals

- * <h2>Another RTOS?</h2>

- * The first question to be answered is: there was really the need for YET

- * ANOTHER RTOS?<br>

- * There are several reasons:

- * - The ChibiOS/RT ancestor was created more than 15 years ago and while it

- *   had far less features than the current product it was complete and

- *   functioning. ChibiOS/RT is just a new (and silly) name given to

- *   something created when there were not many free RTOSes around (actually

- *   none, at least none in my knowledge, there was no widespread Internet

- *   at that time).

- * - When, after a while, I needed a RTOS again, none of the existing FOSS

- *   projects met my expectations or my ideas of how a RTOS should be, not

- *   even close (see below). I decided that work on that old project was

- *   a better idea than contribute to, or fork, something else.

- * - I wanted another toy.

- * .

- * <h2>Why is it different?</h2>

- * Well, there are some design choices that should be explained and contribute

- * to make ChibiOS/RT a peculiar design. Nothing really new in itself but

- * the whole is interesting:

- *

- * <h3>Static design</h3>

- * Everything in the kernel is static, nowhere memory is allocated or freed,

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

- *

- * <h3>No tables, arrays or other fixed structures</h3>

- * The kernel has no internal tables, there is nothing that must be configured

- * at compile time or that can overflow at run time. No upper bounds, the

- * internal structures are all dynamic even if all the objects are statically

- * allocated.

- *

- * <h3>No error conditions and no error checks</h3>

- * All the system APIs have no error conditions, all the previous points are

- * finalized to this objective. Everything you can invoke in the kernel is

- * designed to not fail unless you pass garbage as parameters, stray pointers

- * as examples. The APIs are not slowed down by parameter checks,

- * parameter checks (and consistency checks) do exist but only when the

- * debug switch is activated.<br>

- * All the static core APIs always succeed if correct parameters are passed.

- * Exception to this are the optional allocators APIs that, of course,

- * can report memory exhausted.

- *

- * <h3>Very simple APIs</h3>

- * Each API should have the parameters you would expect for that function and

- * do just one thing with no options.

- *

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

- * -# I would not trade efficiency or features in order to save few bytes.

- * .

- * About the "fast" part, the kernel is able to start/exit over

- * <b>220,000 threads per second</b> on a 72MHz STM32.

- * The Context Switch takes <b>1.2 microseconds</b> on the same STM32.

- *

- * <h3>Tests and metrics</h3>

- * I think it is nice to know how an OS is tested and how it performs before

- * 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, see @ref testsuite.

- */

diff --git a/docs/src/integrationguide.dox b/docs/src/integrationguide.dox
deleted file mode 100644
index dd91d8cf8..000000000
--- a/docs/src/integrationguide.dox
+++ /dev/null
@@ -1,95 +0,0 @@
-/*

-    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_integrationguide Integration Guide

- * All the delivered ChibiOS/RT demos are stand alone applications so if

- * you just start your application from an existing demo there isn't any

- * integration effort, you are simply using the existing makefiles, the

- * default startup files etc, minimal effort.<br>

- * The matter is very different if you are going to integrate the OS into

- * a different runtime framework or if you want to use a different build

- * system, in that case you have the problem to integrate the OS source

- * code into your application.

- *

- * <h2>What this guide does not cover</h2>

- * This guide has a limited scope, the following topics are handled elsewhere:

- * - Porting the OS to different architectures or different compilers is

- *   not covered in this guide, see @ref article_portguide instead.

- * - This guide does not describe any specific environment or development

- *   tool, it is assumed you already know in detail the environment you

- *   want to work with.

- * .

- *

- * <h2>Article Index</h2>

- * - @ref integrationguide_kernel

- * - @ref integrationguide_hal

- * .

- * @section integrationguide_kernel Integrating the Kernel

- * This section covers the scenario where you want to use the ChibiOS/RT

- * kernel into an existing application. In order to accomplish this you need

- * to import in your project two components:

- * - The portable kernel.

- * - The port layer for your microcontroller.

- * .

- * See the @ref architecture for more details.

- * You need to add the following files to your build process:

- * - All the source files contained under <tt>./os/kernel/src</tt>, note that

- *   you should add all of them even if you don't plan to use some of the

- *   subsystems. Unused subsystems can be excluded from the kernel

- *   configuration file @p chconf.h.

- * - All the source files contained under

- *   <tt>./os/ports/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.

- *   Note that those could be both C source files and assembler source files

- *   and that some architectures have an extra directories layer containing

- *   files required for a specific platform.

- * .

- * You also need to add to the compiler options the following paths for

- * searching header files:

- * - The portable kernel headers <tt>./os/kernel/include</tt>.

- * - The port layer headers

- *   <tt>./os/ports/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.

- * .

- * @section integrationguide_hal Integrating the HAL

- * If, in addition to the kernel as described in the previous section, you also

- * need to integrate the HAL into your application you also need to import

- * the following components:

- * - HAL portable files.

- * - Platform specific files.

- * .

- * See the @ref architecture for more details.

- * You need to add the following files to your build process:

- * - All the source files contained under <tt>./os/hal/src</tt>, note that

- *   you should add all of them even if you don't plan to use some of the

- *   subsystems. Unused drivers can be excluded from the HAL configuration

- *   file @p halconf.h.

- * - All the source files contained under

- *   <tt>./os/hal/platforms/<i>@<platform@></i></tt>.

- * - All the source files contained under

- *   <tt>./boards/<i>@<board_model@></i></tt>.

- * .

- * You also need to add to the compiler options the following paths for

- * searching header files:

- * - The portable HAL headers <tt>./os/hal/include</tt>.

- * - The platform layer headers

- *   <tt>./os/hal/platforms/<i>@<platform@></i></tt>.

- * - The board description headers

- *   <tt>./boards/<i>@<board_model@></i></tt>.

- * .

- */

diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox
deleted file mode 100644
index bceea96c4..000000000
--- a/docs/src/interrupts.dox
+++ /dev/null
@@ -1,69 +0,0 @@
-/*

-    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_interrupts How to write interrupt handlers

- * Since version 1.1.0 ChibiOS/RT offers a cross-platform method for writing

- * interrupt handlers. Port-related and compiler-related details are

- * encapsulated within standard system macros.

- *

- * <h2>Writing Regular Interrupt handlers</h2>

- * A Regular Interrupts handler (see @ref interrupt_classes) must be written

- * using the following general form:

- * @code

-CH_IRQ_HANDLER(myIRQ) {

-  CH_IRQ_PROLOGUE();

-  

-  // IRQ handling code, preemptable if the architecture supports it.

-  

-  chSysLockFromIsr();

-  // Invocation of some I-Class system APIs, never preemptable.

-  chSysUnlockFromIsr();

-  

-  // More IRQ handling code, again preemptable.

-

-  CH_IRQ_EPILOGUE();

-}

- * @endcode

- *

- * <h2>Writing Fast Interrupt handlers</h2>

- * In those architectures (@ref ARM7 and @ref ARMCMx) supporting Fast

- * Interrupts (see @ref interrupt_classes) handlers must be written

- * using the following general form:

- * @code

-CH_FAST_IRQ_HANDLER(myIRQ) {

-

-  // Fast IRQ handling code, preemptable if the architecture supports it.

-  // The invocation of any API is forbidden here because fast interrupt

-  // handlers can preempt the kernel even within its critical zones in

-  // order to minimize latency.

-}

- * @endcode

- *

- * <h2>Handlers naming</h2>

- * A note about the handler name "myIRQ", in some ports it must be a

- * vector number rather than a function name, it could also be a name from

- * within a predefined set, see the notes about the various ports.

- *

- * <h2>Important Notes</h2>

- * - There is an important application note about ARM7 interrupt handlers,

- *   please read about it in the ARM7 port section: @ref ARM7_IH

- * .

- */

- 
\ No newline at end of file
diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox
deleted file mode 100644
index 759425b4e..000000000
--- a/docs/src/jitter.dox
+++ /dev/null
@@ -1,135 +0,0 @@
-/*

-    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_jitter Response Time and Jitter

- * Response time jitter is one of the most sneaky source of problems when

- * designing a real time system. When using a RTOS like ChibiOS/RT one must

- * be aware of what the jitter is and how it can affect the performance of the

- * system. A good place to start is this

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

- * article</a>.

- *

- * <h2>Interrupt handlers execution time</h2>

- * The total execution time of an interrupt handler includes:

- * - Hardware interrupts latency, this parameter is pretty much fixed and

- *   characteristic of the system.

- * - Fixed handler overhead, as example registers stacking/unstacking.

- * - Interrupt specific handler code execution time, as example, in a serial

- *   driver, this is the time used by the handler to transfer data from/to

- *   the UART.

- * - OS overhead. Any operating system requires to run some extra code

- *   in interrupt handlers in order to handle correct preemption and Context

- *   Switching.

- * .

- * <h2>Interrupt Response Time</h2>

- * The Interrupt Response Time is the time from an interrupt event and the

- * execution of the handler code. Unfortunately this time is not constant

- * in most cases, see the following graph:

- *

- * @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];

-      int [label="Interrupt"];

-      busy [label="Busy"];

-      served [label="Interrupt\nServed"];

-      int -> served [label="Not Busy (minimum latency)"];

-      int -> busy [label="Not Ready"];

-      busy -> busy [label="Still Busy\n(added latency)"];

-      busy -> served [label="Finally Ready"];

-  }

- * @enddot

- *

- * In this scenario the jitter (busy state) is represented by the sum of:

- * - Higher or equal priority interrupt handlers execution time combined.

- *   This time can go from zero to the maximum randomly. This value can be

- *   guaranteed to be zero only if the interrupt has the highest priority in

- *   the system.

- * - Highest execution time among lower priority handlers. This value is zero

- *   on those architectures (Cortex-M3 as example) where interrupt handlers

- *   can be preempted by higher priority sources.

- * - Longest time in a kernel lock zone that can delay interrupt servicing.

- *   This value is zero for fast interrupt sources, see @ref system_states.

- * .

- * <h2>Threads Flyback Time</h2>

- * This is the time between an event, as example an interrupt, and the

- * execution of the thread that will process it. Imagine the following

- * graph as the continuation of the previous one.

- *

- * @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];

-      served [label="Interrupt\nServed"];

-      busy [label="Busy"];

-      thread [label="Thread\nAwakened"];

-      served -> busy [label="Not highest Priority"];

-      busy -> busy [label="Higher priority Threads\n(added latency)"];

-      busy -> thread [label="Highest Priority"];

-      served -> thread [label="Highest Priority (minimum latency)"];

-  }

- * @enddot

- *

- * In this scenario all the jitter sources previously discussed are also

- * present and there is the added jitter caused by the activity of the

- * higher priority threads.

- *

- * <h2>Jitter Mitigation</h2>

- * For each of the previously described jitter sources there are possible

- * mitigation actions.

- *

- * <h3>Interrupt handlers optimization</h3>

- * An obvious mitigation action is to optimize the interrupt handler code as

- * much as possible for speed.<br>

- * Complex actions should never be performed in interrupt handlers.

- * An handler should just serve the interrupt and wakeup a dedicated thread in

- * order to handle the bulk of the work.<br>

- * Another possible mitigation action is to evaluate if a specific interrupt

- * handler really needs to interact with the OS, if the handler uses full

- * stand-alone code then it is possible to remove the OS related overhead.<br>

- *

- * <h3>Kernel lock zones</h3>

- * The OS kernel protects some critical internal data structure by disabling

- * (fully in simple architecture, to some extent in more advanced

- * microcontrollers) the interrupt sources. Because of this the kernel itself

- * is a jitter cause, a good OS design minimizes the jitter generated by the

- * kernel by using adequate data structures, algorithms and coding

- * practices.<br>

- * A good OS design is not the whole story, some OS primitives may generate

- * more or less jitter depending on the system state, as example the maximum

- * number of threads on a certain queue, the maximum number of nested mutexes

- * and so on. Some algorithms employed internally can have constant execution

- * time but others may have linear execution time or be even more complex.

- *

- * <h3>Higher priority threads activity</h3>

- * At thread level, the response time is affected by the interrupt-related

- * jitter but mainly by the activity of the higher priority threads and

- * contention on protected resources.<br>

- * It is possible to improve the system overall response time and reduce jitter

- * by carefully assigning priorities to the various threads and carefully

- * designing mutual exclusion zones.<br>

- * The use of the proper synchronization mechanism (semaphores, mutexes, events,

- * messages and so on) also helps to improve the overall system performance.

- * The use of the Priority Inheritance algorithm implemented in the mutexes

- * subsystem can improve the overall response time and reduce jitter but it is

- * not a magic wand, a proper system design comes first.

- */

diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox
deleted file mode 100644
index f2563134c..000000000
--- a/docs/src/licfaq.dox
+++ /dev/null
@@ -1,119 +0,0 @@
-/*

-    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 lic_faq License and F.A.Q.

- * ChibiOS/RT is a <a href="http://www.gnu.org/licenses" target="_top">

- * GPL3</a>-licensed product but it offers a linking exception in its stable

- * releases.<br>

- * This article contains some answers about the exception.

- *

- * @section faq Frequently Asked Questions

- * - <b>Is ChibiOS/RT free ?</b><br>

- *   Yes, free as both in free beer and freedom.

- * - <b>Can I use it in my commercial embedded product?</b><br>

- *   Yes, you just have to advertise that you are using ChibiOS/RT by putting

- *   a link to the project somewhere on your web site or documentation.

- * - <b>Am I forced to release the source code of my product?</b><br>

- *   The exception to the GPL allows you to use ChibiOS/RT in your commercial

- *   application without have to release your source code under certains

- *   conditions. See the @ref exception_text under "Approved Interfaces" for

- *   details.

- * - <b>What I have to contribute back?</b><br>

- *   In general you have to offer changes done on existing files (where

- *   allowed) or new developments done using the OS template files. As example:

- *   - Ports to new architectures because a new port uses copyrighted OS

- *     template files.

- *   - New, HAL-style, device drivers because device drivers use copyrighted

- *     template files.

- *   - Improvements on modifiable OS code as described in the

- *     "approved interfaces" section of the @ref exception_text.

- *   .

- * - <b>Is the exception applicable to any ChibiOS/RT version ?</b><br>

- *   The exception is valid only for ChibiOS/RT releases marked as @e stable.

- *   Beta, unstable or development versions are covered by the GPL3 alone

- *   because are meant for testing only.

- * - <b>I don't want to be bound by any of the above restriction, is this

- *   possible?</b><br>

- *   You may contact us about a commercial license.

- * .

- * @section exception_text GPL Exception Text

-

-<center><b>GPL Exception Text for ChibiOS/RT 1.4.x</b></center>

-

-  In addition, as a special exception, the copyright holder of ChibiOS/RT,

-gives You the additional right to link the unmodified code of this Program with

-code not covered under the GNU General Public License ("Non-GPL Code") and to

-distribute linked combinations including the two, subject to the limitations

-in this paragraph.

-

-   -# Non-GPL Code permitted under this exception must only link to the

-      unmodified code of this Program through those well defined interfaces

-      identified as "Approved Interfaces".

-   -# Every copy of the combined work is accompanied by a written statement

-      that details to the recipient the version of ChibiOS/RT used and an

-      offer by yourself to provide the ChibiOS/RT source code should the

-      recipient request it.

-   -# The combined work is not itself an RTOS, scheduler, kernel or related

-      product.

-   -# The combined work is not itself a binary library intended for linking

-      into other software applications.

-   .

-

-<center><b>The Approved Interfaces</b></center>

-

-   -# The files of Non-GPL Code may include the unmodified ChibiOS/RT

-      distribution header files contained under:

-        - ./os/kernel/include

-        - ./os/hal/include

-        - ./os/hal/platforms

-        - ./os/various

-        .

-      without causing the resulting work to be covered by the GNU General

-      Public License.

-   -# The files of Non-GPL Code may link to the unmodified ChibiOS/RT

-      distribution files contained under:

-        - ./os/kernel/src

-        - ./os/hal/src

-        - ./os/hal/platforms

-        - ./os/various

-        .

-      without causing the resulting work to be covered by the GNU General

-      Public License.

-   -# The files of Non-GPL Code may link to, or include, the modified or

-      unmodified ChibiOS/RT distribution files contained under:

-        - ./os/kernel/templates

-        - ./os/hal/templates

-        - ./os/ports

-        - ./boards

-        - ./demos

-        .

-      without causing the resulting work to be covered by the GNU General

-      Public License.

-   .

-

-  Only the copyright holder of ChibiOS/RT may make changes or additions to the

-list of Approved Interfaces.

-

-  You must obey the GNU General Public License in all respects for all of the

-Program code and other code used in conjunction with the Program except the

-Non-GPL Code covered by this exception.

- *

- */

-

diff --git a/docs/src/lifecycle.dox b/docs/src/lifecycle.dox
deleted file mode 100644
index 18875e7da..000000000
--- a/docs/src/lifecycle.dox
+++ /dev/null
@@ -1,68 +0,0 @@
-/*

-    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:

- * - <b>Static threads</b>. The memory used for static threads is allocated at

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

- *   to be done.

- * - <b>Dynamic threads</b>. 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 become objects

- * with a reference counter. The memory of a thread, if dynamic, is freed

- * 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 easiest way to ensure that the memory is released is

- * to make another thread perform 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, scanning the registry

- * has the side effect to release the zombies (detached and then terminated

- * threads).

- */

diff --git a/docs/src/main.dox b/docs/src/main.dox
index e5872cdf5..76a39bff7 100644
--- a/docs/src/main.dox
+++ b/docs/src/main.dox
@@ -58,13 +58,7 @@
  *   driver models and device driver implementations.

  * .

  * <h2>Related pages</h2>

- * - @subpage credits

- * - @subpage lic_faq

- * - @subpage goals

- * - @subpage target

- * - @subpage architecture

  * - @subpage concepts

- * - @subpage articles

  * - @subpage testsuite

  * .

  */

diff --git a/docs/src/memory.dox b/docs/src/memory.dox
deleted file mode 100644
index f41dff32f..000000000
--- a/docs/src/memory.dox
+++ /dev/null
@@ -1,138 +0,0 @@
-/*

-    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_manage_memory How to manage memory

- * ChibiOS/RT is a static kernel so you don't need to manage memory at all

- * if your application doesn't really require it. This doesn't mean that

- * the OS is unable to manage memory but just that memory management is an

- * optional part of the whole.<br>

- * The OS offers three distinct ways to manage memory, each one with its

- * weaknesses and strengths:

- * - Core Memory Manager. See @ref memcore.

- * - Heap Allocator. See @ref heaps.

- * - Memory Pools. See @ref pools.

- * .

- * The three mechanisms are able to coexist and are well integrated, as example

- * the heap allocator uses the core memory manager in order to get more

- * memory blocks, memory pools can optionally do the same thing.

- * 

- * <h2>The three subsystems</h2>

- * This is a small comparison table regarding the three subsystems, C-runtime

- * and static objects are thrown in there for comparison:<br><br>

- * <table style="text-align: center; width: 95%;"

- *        align="center" border="1" cellpadding="2" cellspacing="0">

- *   <tr>

- *     <th style="width: 100px; background-color: rgb(192, 192, 192);">

- *       <small>Subsystem</small>

- *     </th>

- *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

- *       <small>Free capable</small>

- *     </th>

- *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

- *       <small>Constant time</small>

- *     </th>

- *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

- *       <small>Safe</small>

- *     </th>

- *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

- *       <small>From IRQ</small>

- *     </th>

- *     <th style="background-color: rgb(192, 192, 192);">

- *       <small>Notes</small>

- *     </th>

- *   </tr>

- *   <tr>

- *     <th style="background-color: rgb(224, 224, 224);">

- *       <small>Static Objects</small>

- *     </th>

- *     <td><small>N/A</small></td>

- *     <td><small>N/A</small></td>

- *     <td><small>YES</small></td>

- *     <td><small>YES</small></td>

- *     <td style="text-align: left;">

- *       Preferred solution for safety applications.

- *     </td>

- *   </tr>

- *   <tr>

- *     <th style="background-color: rgb(224, 224, 224);">

- *       <small>Core Memory Manager</small>

- *     </th>

- *     <td><small>NO</small></td>

- *     <td><small>YES</small></td>

- *     <td><small>YES</small></td>

- *     <td><small>YES</small></td>

- *     <td style="text-align: left;">

- *       Fast and safe but unable to free allocated memory.

- *     </td>

- *   </tr>

- *   <tr>

- *     <th style="background-color: rgb(224, 224, 224);">

- *       <small>Heap Allocator</small>

- *     </th>

- *     <td><small>YES</small></td>

- *     <td><small>NO</small></td>

- *     <td><small>NO</small></td>

- *     <td><small>NO</small></td>

- *     <td style="text-align: left;">

- *       Unsafe because fragmentation and not constant time, cannot be used

- *       from IRQ handlers.

- *     </td>

- *   </tr>

- *   <tr>

- *     <th style="background-color: rgb(224, 224, 224);">

- *       <small>Memory Pools</small>

- *     </th>

- *     <td><small>YES</small></td>

- *     <td><small>YES</small></td>

- *     <td><small>YES</small></td>

- *     <td><small>YES</small></td>

- *     <td style="text-align: left;">

- *       Fast and safe but it can handle fixed size objects only, you may have

- *       multiple memory pools however.

- *     </td>

- *   </tr>

- *   <tr>

- *     <th style="background-color: rgb(224, 224, 224);">

- *       <small>C-Runtime</small>

- *     </th>

- *     <td><small>YES</small></td>

- *     <td><small>NO</small></td>

- *     <td><small>NO</small></td>

- *     <td><small>NO</small></td>

- *     <td style="text-align: left;">

- *       Unsafe because fragmentation, not constant time, cannot be used

- *       from IRQ handlers and not thread safe. The C runtime must also be

- *       modified in order to work with the other allocators.

- *     </td>

- *   </tr>

- * </table>

- * <br>

- * When designing a system it is recommended to proceed as follow:

- * -# Use static objects and initializers whenever possible.

- * -# Where dynamic allocation is required without having to free the allocated

- *    memory then use the Core Memory Manager allocation APIs.

- * -# Where dynamic allocation is required evaluate if one or more memory

- *    pools can be used.

- * -# If all the above points do not satisfy your requirements then use the

- *    heap allocator.

- * -# Consider the C-runtime allocator only for legacy code.

- * .

- */

- 

diff --git a/docs/src/mutualexcl.dox b/docs/src/mutualexcl.dox
deleted file mode 100644
index 260732e19..000000000
--- a/docs/src/mutualexcl.dox
+++ /dev/null
@@ -1,210 +0,0 @@
-/*

-    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_mutual_exclusion Mutual Exclusion guide

- * The most common problem when writing multithreaded code is the

- * synchronization on the shared resources/services.<br>

- * ChibiOS/RT offers a rich variety of mechanisms that apparently solve the

- * same problem. I wrote apparently because each mechanism has its pro and

- * cons.

- * This article will introduce the various mechanisms and the explain the

- * right scenarios for each one.

- *

- * <h2>Basics</h2>

- * Some of the concepts mentioned in this article can be found in the

- * following Wikipedia articles:

- * - <a href="http://en.wikipedia.org/wiki/Mutual_exclusion" target="_blank">

- *   Mutual Exclusion</a>

- * - <a href="http://en.wikipedia.org/wiki/Priority_inversion" target="_blank">

- *   Priority Inversion</a>

- * - <a href="http://en.wikipedia.org/wiki/Priority_inheritance"

- *   target="_blank">Priority Inheritance</a>

- * - <a href="http://en.wikipedia.org/wiki/Priority_ceiling" target="_blank">

- *   Priority Ceiling</a>

- * .

- * <h2>Mutual exclusion by System Locks</h2>

- * This is the lowest level mechanism, the system is locked by invoking the

- * @p chSysLock() API and then unlocked by invoking @p chSysUnlock().<br>

- * The implementation is architecture dependent but it is guaranteed to, at

- * least, disable the interrupt sources with hardware priority below or equal

- * the kernel level.

- *

- * <h3>Advantages</h3>

- * - It is the lightest as execution time, often a lock or unlock becomes just a

- *   single inlined assembler instruction.

- * - It ensures mutual exclusion among threads but also interrupt handling code.

- * - The implementation would ensure mutual exclusion even on multicore

- *   architectures where multiple hardware threads are present.

- * .

- * <h3>Disadvantages</h3>

- * - Disabling interrupts for a long period of time can deteriorate the overall

- *   system response time and/or introduce jitter.

- * .

- * <h3>When use Locks</h3>

- * - When mutual exclusion with interrupt handlers is required.

- * - When the operation within the lock zone is very simple and has finite

- *   time.

- * .

- * <h3>Example</h3>

- * @code

- * ...

- * chSysLock();

- * /* Protected code */

- * chSysUnlock();

- * ...

- * @endcode

- *

- * <h2>Mutual exclusion by Semaphores</h2>

- * In ChibiOS/RT the counting semaphores are mainly meant as a

- * synchronization mechanism between interrupt handlers and high level code

- * running at thread level. Usually a thread waits on a semaphore that is

- * signaled asynchronously by an interrupt handler.<br>

- * The semaphores can, however, be used as simple mutexes by initializing

- * the semaphore counter to one.

- *

- * <h3>Advantages</h3>

- * - The semaphores code is "already there" if you use the I/O queues or

- *   mailboxes and you don't want to enable the mutexes too in order to save

- *   space.

- * - Semaphores are lighter than mutexes because their queues are FIFO

- *   ordered and do not have any overhead caused by the priority inheritance

- *   algorithm.

- * - A semaphore takes less RAM than a mutex (12 vs 16 bytes on 32 bit

- *   architectures).

- * .

- * <h3>Disadvantages</h3>

- * - Semaphore queues are FIFO ordered by default, an option exist to make

- *   them priority ordered but this can impact I/O performance because

- *   semaphores are used in I/O queues.

- * - Semaphores do not implement the Priority Inheritance algorithm.

- * .

- * <h3>When use Semaphores</h3>

- * - When you don't need queuing by priority nor the Priority Inheritance

- *   algorithm.

- * - When RAM/ROM space is scarce.

- * .

- * <h3>Example</h3>

- * @code

- * static Semaphore sem; /* Semaphore declaration */

- * ...

- * chSemInit(&sem, 1); /* Semaphore initialization before use */

- * ...

- * chSemWait(&sem);

- * /* Protected code */

- * chSemSignal(&sem);

- * ...

- * @endcode

- *

- * <h2>Mutual exclusion by Mutexes</h2>

- * The mutexes are the mechanism intended as the most general solution for

- * Mutual Exclusion.

- *

- * <h3>Advantages</h3>

- * - Mutexes implement the Priority Inheritance algorithm that is an important

- *   tool in reducing jitter and improve overall system response time (it is

- *   not a magic solution, just another tool for the system designer).

- * .

- * <h3>Disadvantages</h3>

- * - Heaviest among all the possible choices. The Priority Inheritance method

- *   is efficiently implemented but nothing is more efficient than no code at

- *   all.

- * .

- * <h3>When use Mutexes</h3>

- * - When you are designing a very complex system with hard realtime

- *   requirements.

- * .

- * <h3>Example</h3>

- * @code

- * static Mutex mtx; /* Mutex declaration */

- * ...

- * chMtxInit(&mtx); /* Mutex initialization before use */

- * ...

- * chMtxLock(&mtx);

- * /* Protected code */

- * chMtxUnlock();

- * ...

- * @endcode

- *

- * <h2>Mutual exclusion by priority boost</h2>

- * Another way to implement mutual exclusion is to boost the thread priority

- * to a level higher than all of the threads competing for a certain resource.

- * This solution effectively implements an Immediate Priority Ceiling

- * algorithm.

- *

- * <h3>Advantages</h3>

- * - Almost free as code size, you need no semaphores nor mutexes.

- * - No RAM overhead.

- * - Fast execution, priority change is a quick operation under ChibiOS/RT.

- * - The Priority Ceiling protocol can help mitigate potential Priority

- *   Inversion problems.

- * .

- * <h3>Disadvantages</h3>

- * - Makes the design more complicated because priorities must be assigned to

- *   not just threads but also assigned to the resources to be protected.

- * - Locking a resource affects all the threads with lower priority even if

- *   not interested to the resource.

- * - All the threads that can access the resource must have lower priority

- *   than the resource itself.

- * - The mechanism is not easy to understand in the code unless it is clearly

- *   documented.

- * - This method does not work in on multicore architectures where multiple

- *   hardware threads are present.

- * - Only useful in very simple applications.

- * .

- * <h3>Example</h3>

- * @code

- * /* Priority assigned to the resource, threads must have lower

- *    priority than this.*/

- * #define AAA_RESOURCE_PRIORITY NORMALPRIO+10

- * ...

- * /* Locks the resources AAA.*/

- * tprio_t aaa_old_prio = chThdSetPriority(AAA_RESOURCE_PRIORITY);

- * /* Accessing resource AAA */

- * chThdSetPriority(aaa_old_prio); /* Unlocks AAA.*/

- * ...

- * @endcode

- *

- * <h2>Mutual exclusion by message passing</h2>

- * Another method is to make a single dedicated thread execute the critical

- * code and make it work as a messages server. The other threads can request

- * the service to the server by sending a properly formatted message and

- * then wait for the answer with the result.<br>

- * This method is very useful when integrating into the system components not

- * designed to be reentrant or to be executed in a multithreaded environment,

- * as example a 3rd part file system or a networking protocol stack.

- *

- * <h3>Advantages</h3>

- * - It is possible to encapsulate very complex logic without worry about

- *   about concurrent accesses.

- * - If the encapsulate code uses a large stack area only the server thread

- *   have to allocate enough RAM, the client threads save RAM by just

- *   requesting the service to the server.

- * - Clean system architecture.

- * - This method also implements a form of Priority Ceiling. The ceiling is

- *   the priority of the server thread itself.

- * .

- * <h3>Disadvantages</h3>

- * - More complex implementation, a protocol must be created between clients

- *   and server.

- * - Two context switches are required for each request to the server (but

- *   ChibiOSRT is very efficient at that).

- * - Requires a dedicated thread as server.

- * .

- */

diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox
deleted file mode 100644
index 087724084..000000000
--- a/docs/src/portguide.dox
+++ /dev/null
@@ -1,120 +0,0 @@
-/*

-    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_portguide Porting ChibiOS/RT for Dummies

- * Porting the operating system on a new platform is one of the most common

- * tasks. The difficulty can range from easy to very difficult depending

- * on several factors.<br>

- * We can divide in problem in several classes of progressively increasing

- * difficulty:

- * - @ref port_board

- * - @ref port_family

- * - @ref port_chip

- * - @ref port_core

- * .

- * Another kind of port type is porting to another compiler and this is an

- * added complexity level on the above classes. The kernel itself is portable

- * but the port-specific code usually contains compiler specific extensions to

- * the C language and the asm files syntax is almost never compatible.

- *

- * @section port_board Porting the OS to a new board

- * This is the easiest port type, the scenario is that the specific

- * microcontroller is already supported and a demo exists. This scenario also

- * applies when porting the OS on a custom hardware using a supported

- * microcontroller. This task can be easily performed with the following

- * steps:

- * -# Create a new directory under ./boards and copy inside the board files

- *    from another board using the same microcontroller.

- * -# Customize the board files:

- *   - @p board.h This file contains the I/O pins setup for the uC, it

- *     may also contain other board-dependent settings, as example, the clock

- *     frequency. Customize this file depending on your target hardware.

- *   - @p board.c This file contains the initialization code, it is possible

- *     you just need to customize @p board.h and not this file. If you have

- *     some hardware specific initialization code then put it here.

- *   .

- * -# Create a new directory under the ChibiOS/RT installation directory:

- *    <tt>./projects/<i>@<my_app_name@></i></tt>

- * -# Copy an existing demo code under the newly created directory.

- * -# Customize the demo:

- *   - @p Makefile You may edit this file in order to remove the test related

- *     sources and/or add you application source files.

- *   - @p main.c It contains the demo simple code, clean it and write your

- *     own @p main() function here, use this file just as a template.

- * -# Compile your application and debug.

- * .

- * @section port_family Porting the OS to a closely related microcontroller

- * In this scenario all the above steps are required but an analysis must

- * be performed to evaluate the differences between from the supported micro

- * and the target micro. Often the micros just differ for the memory area

- * sizes and a change to the linker script is enough (the file is usually

- * named @p ch.ld). Chips having more or less peripherals, everything else

- * being the same or compatible are not a problem also as long the timer and

- * the serial peripherals used by the port do not change.<br>

- * If there are differences in the internal peripherals, as example non

- * compatible interrupt controllers (this happens in the LPC2000 family)

- * or differences in UARTS, timers etc then the port falls in the following

- * category.

- *

- * @section port_chip Porting the OS to another microcontroller using the same core

- * This kind of port is required when a target microcontroller has the same

- * core (a common example: ARM7) of a supported microcontroller but has

- * differences in the internal peripherals.<br>

- * If this is your case proceed as follow:

- * -# Create a new directory under @p <tt>./os/hal/platforms</tt> and

- *    name it with the microcontroller name (or family name).<br>

- *    In case of the ARM-based microcontroller you also need to create a

- *    equally named directory under

- *    @p <tt>./os/ports/<i>@<compiler@></i>/<i>@<arch@></i></tt> and

- *    put there the microcontroller related files such as the vectors table,

- *    see the existing ports as example.

- * -# Copy into the newly created directory the most closely related existing

- *    chip port or the naked template files from

- *    @p <tt>./os/hal/templates</tt>.

- * -# Work out the differences in the drivers or implement them if you started

- *    from the templates.

- * -# Edit/create the documentation file @p <tt>platform.dox</tt>, this

- *    is only required if you want to regenerate this documentation including

- *    your work.

- * .

- * Usually this kind of port just requires a serial driver (and those are very

- * similar each other) and some code for the interrupt controller (this one

- * can be part of the core port, as example the Cortex-M3 has this as standard

- * part of the core).<br>

- * When the chip port is completed created your application as seen in the

- * previous sections.

- *

- * @section port_core Porting the OS to a whole new architecture

- * This is the hardest scenario, the time required by core ports depends

- * strongly by the target architecture complexity and the level of support you

- * need for the architecture specific features.<br>

- * As a reference, the MSP430 port took me 2 hours and it worked at the first

- * run, it can be a reference for simple architectures, the ARM Cortex-M3 was

- * painful instead, the architecture enforces you to implement things in a very

- * specific way and I spent 2 week to go through all the documentation and

- * figure out the correct way to implement the port (you can see that the

- * preemption context switch is done in a very peculiar way because the

- * exceptions architecture).<br>

- * One thing is sure, port an OS to a new architecture is not an easy task and

- * if you have the required experience for such an effort then probably you

- * don't need any advice from me. Just follow the directory patterns and fill

- * the OS template files, the hardest part is decide the correct and efficient

- * way to implement the context switching.

- */

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

-    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_roundrobin Round Robin scheduling explained

- * Unlike many other RTOSes, ChibiOS/RT supports multiple threads at the

- * same priority level and schedules them using an <i>aggressive</i>

- * round-robin strategy.<br>

- * The strategy is defined as aggressive because any scheduling event

- * causes the round-robin threads to rotate.<br>

- * A round-robin rotation can happen because of the following events:

- * - The currently executed thread voluntarily invokes the @p chThdYield()

- *   API in order to allow the execution of another thread at the same

- *   priority level, if any.

- * - The currently executed thread voluntarily goes into a sleep state

- *   (see @ref thread_states), when the thread is awakened it goes behind

- *   any other thread at the same priority level.

- * - The currently executed thread is preempted by an higher priority

- *   thread, the thread is reinserted in the ready list (see @ref scheduling)

- *   behind any other thread at the same priority level.

- * - If the @p CH_TIME_QUANTUM configuration constant is set to a value

- *   greater than zero and if the specified time quantum expired and if

- *   a thread with equal priority is ready then the currently executing

- *   thread is automatically reinserted in the ready list behind any

- *   other thread at the same priority level.

- * .

- * As you can see the @p CH_TIME_QUANTUM setting is really useful only if

- * there are threads at the same priority level that can run not preempted

- * for long periods of time and that do not explicitly yield using

- * @p chThdYield(). Because of this you should consider setting

- * @p CH_TIME_QUANTUM to zero in your configuration file, this makes the

- * kernel much faster and smaller and <b>does not</b> forbid the use of

- * multiple threads at the same priority level.

- */

diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox
deleted file mode 100644
index 233c322c6..000000000
--- a/docs/src/saveram.dox
+++ /dev/null
@@ -1,81 +0,0 @@
-/*

-    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_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();

-  ...

-  chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL);

-  ...

-}

- * @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 WORKING_AREA(waMyThread, 64);

-

-__attribute__((noreturn))

-static void MyThread(void *arg) {

-  while (!chThdShoudTerminate()) {

-    /* Do thread inner work */

-  }

-  chThdExit(1);

-}

-

-main() {

-  chSysInit();

-  ...

-  chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO,

-                    (tfunc_t)MyThread, NULL);

-  ...

-}

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

- */

diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox
deleted file mode 100644
index d87d183f6..000000000
--- a/docs/src/stacks.dox
+++ /dev/null
@@ -1,107 +0,0 @@
-/*

-    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_stacks Stacks and stack sizes

- * In an RTOS like ChibiOS/RT there are several dedicated stacks, each stack

- * has a dedicated RAM space that must have a correctly sized assigned area.

- * <h2>The stacks</h2>

- * There are several stacks in the systems, some are always present, some

- * others are present only in some architectures:

- * - <b>Main stack</b>, this stack is used by the @p main() function and the

- *   thread that execute it. It is not a normal thread stack because it is

- *   initialized in the startup code and its size is defined in a port

- *   dependent way. Details are in the various ports documentation.

- * - <b>Interrupt Stack</b>, some architectures have a dedicated interrupt

- *   stack. This is an important feature in a multithreaded environment,

- *   without a dedicated interrupt stack each thread has to reserve

- *   enough space, for interrupts servicing, within its own stack. This space,

- *   multiplied by the total threads number, can amount to a significant RAM

- *   overhead.

- * - <b>Thread Stack</b>, each thread has a dedicated stack for its own

- *   execution and context switch.

- * - <b>Other Stacks</b>, some architectures (ARM) can have other stacks but

- *   the OS does not directly use any of them. 

- * .

- * <h2>Risks</h2>

- * The most critical thing when writing an embedded multithreaded application

- * is to determine the correct stack size for main, threads and, when present,

- * interrupts.<br>

- * Assigning too much space to a stack is a waste of RAM, assigning too little

- * space leads to crashes or, worst scenario, hard to track instability.

- *

- * <h2>Assigning the correct size</h2>

- * You may try to examine the asm listings in order to calculate the exact

- * stack requirements but this requires much time, experience and patience.<br>

- * An alternative way is to use an interactive method. Follow this procedure

- * for each thread in the system:

- * - Enable the following debug options in the kernel:

- *   - @p CH_DBG_ENABLE_STACK_CHECK, this enables a stack check before any

- *        context switch. This option halts the system in @p chSysHalt() just

- *        before a stack overflow happens. The halt condition is caused by

- *        a stack overflow when the global variable @p panic_msg is set to

- *        @p NULL, normally it would point to a panic message.

- *   - @p CH_DBG_FILL_THREADS, this option fills the threads working area

- *     with an easily recognizable pattern (0x55).

- * - Assign a large and safe size to the thread stack, as example 256 bytes

- *   on 32 MCUs, 128 bytes on 8/16 bit MCUs. This is almost always too much

- *   for simple threads.

- * - Run the application, if the application crashes or halts then increase

- *   the stack size and repeat (you know how to use the debugger right?).

- * - Let the application run and make sure to trigger the thread in a way to

- *   make it follow most or all its code paths. If the application crashes or

- *   halts then increase the stack size and repeat.

- * - Stop the application using the debugger and examine the thread working

- *   area (you know what a map file is, right?). You can see that the thread

- *   stack overwrote the fill pattern (0x55) from the top of the working area

- *   downward. You can estimate the excess stack by counting the untouched

- *   locations.

- * - Trim down the stack size and repeat until the application still runs

- *   correctly and you have a decent margin in the stack.

- * - Repeat for all the thread classes in the system.

- * - Turn off the debug options.

- * - Done.

- * .

- * <h2>Final Notes</h2>

- * Some useful info:

- * - Stack overflows are the most common problems source during development,

- *   when in trouble with crashes or anomalous behaviors always first verify

- *   stack sizes.

- * - The required stack size can, and very often does change when changing

- *   compiler vendor, compiler version, compiler options, code type (ARM

- *   or THUMB as example).

- * - Code compiled in THUMB mode uses more stack space compared to the

- *   same code compiled in ARM mode. In GCC this is related to lack of tail

- *   calls optimizations in THUMB mode, this is probably true also in other

- *   compilers.

- * - Speed optimized code often requires less stack space compared to space

- *   optimized code. Be careful when changing optimizations.

- * - The interrupts space overhead on the thread stacks (@p INT_REQUIRED_STACK

- *   defined in @p chcore.h) is included in the total working area size

- *   by the system macros @p THD_WA_SIZE() and @p WORKING_AREA().<br>

- *   The correct way to reserve space into the thread stacks for interrupts

- *   processing is to override the @p INT_REQUIRED_STACK default value.

- *   Architectures with a dedicated interrupt stack do not require changes

- *   to this value. Resizing of the global interrupt stack may be required

- *   instead.

- * - Often is a good idea to have some extra space in stacks unless you

- *   are really starved on RAM. Anyway, it is best to optimize stack space

- *   at the very end of your development cycle.

- * .

- */

diff --git a/docs/src/stop_os.dox b/docs/src/stop_os.dox
deleted file mode 100644
index d2434dea9..000000000
--- a/docs/src/stop_os.dox
+++ /dev/null
@@ -1,133 +0,0 @@
-/*

-    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_stop_os How to cleanly stop the OS

- * Stopping the OS should not be normally required but there are scenarios

- * where one might want the complete control over the system again.

- * As example entering into a bootload mode, or invoking some flashing

- * algorithm locked in ROM.<br>

- * ChibiOS/RT does not have a shutdown API and there is a reason for this,

- * stopping the kernel would not be enough, a well defined operations sequence

- * is required.<br>

- * The shutdown operation should always be implemented into the @p main()

- * function because in that context the stack pointer is guaranteed to be

- * in the area allocated by the startup code. Stopping from a thread would

- * leave the stack pointer "somewhere".<br>

- * The shutdown sequence should include the following steps, some steps

- * are optional and depend on the application:

- * - Safely stop critical threads. As example a thread that uses a File System

- *   should flush all the modified buffers to the persistent storage before

- *   terminating.<br>

- *   The system should be designed to request the thread termination using

- *   @p chThdTerminate() and then wait its termination using @p chThdWait().

- *   This phase can be skipped for non-critical threads.

- * - Invoke the xxxStop() method on all the active device drivers, this

- *   disables the interrupt sources used by the various peripherals. This

- *   is required in order to not have interrupts after the shutdown that

- *   may invoke OS primitives.

- * - Invoke chSysDisable().

- * - Stop the system timer whose service routine invokes

- *   @p chSysTimerHandlerI().

- * - Disable any other interrupt source that may invoke OS APIs. In general

- *   all the interrupt sources that have handlers declared by using the

- *   @p CH_IRQ_HANDLER() macro.

- * - Perform any application related de-initialization.

- * - Invoke chSysEnable().

- * .

- * Now the OS is stopped and you can safely assume there are nothing going on

- * under the hood. From here you can also restart the OS after finishing your

- * critical operations using the following sequence:

- * - Invoke chSysDisable().

- * - Restart the system timer.

- * - Reinitialize the OS by invoking @p chSysInit().

- * - Restart your device drivers using the @p xxxStart() methods.

- * - Restart all your threads.

- * .

- * <h2>Example</h2>

- * This is an example of an hypothetical application that have to shutdown

- * the OS when a certain event is generated.

- * @code

-#include "ch.h"

-#include "hal.h"

-

-/* A shutdown flag.*/

-bool_t shutdown_required;

-

-/* Critical thread.*/

-static void my_thread(void *p) {

-

-  while (!chThdShouldTerminate()) {

-    /* Normal thread activity code.*/

-  }

-  /* Thread de-initialization before terminating, here you put the critical

-     thread finalization code.*/

-  return 0;

-}

-

-/* Main program, it is entered with interrupts disabled.*/

-void main(void) {

-

-  /* HAL initialization, you need to do this just once.*/

-  halInit();

-

-  /* Main loop, the main() function never exits.*/

-  while (TRUE) {

-    Thread *tp;

-

-    shutdown_required = FALSE;

-

-    /* ChibiOS/RT initialization. This function becomes an OS thread.*/

-    chSysInit();

-

-    /* Starting a device driver, SD2 in this case.*/

-    sdStart(&SD2, NULL);

-

-    /* Starting our critical thread.*/

-    tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(256),

-                             NORMALPRIO, my_thread, &SD2);

-

-    /* Main thread activity into a loop.*/

-    while (!shutdown_required) {

-      /* Main activity, OS active until a shutdown becomes necessary.*/

-    }

-

-    /* Starting the shutdown sequence.*/

-    chThdTerminate(tp);     /* Requesting termination.                  */

-    chThdWait(tp);          /* Waiting for the actual termination.      */

-    sdStop(&SD2);           /* Stopping serial port 2.                  */

-    chSysDisable();

-    stop_system_timer();

-    stop_any_other_interrupt();

-    chSysEnable();

-

-    /* Now the main function is again a normal function, no more a

-       OS thread.*/

-    do_funny_stuff();

-

-    /* Restarting the OS but you could also stop the system or trigger a

-       reset instead.*/

-    chSysDisable();

-  }

-}

- * @endcode

- * As you can see it is possible to jump in and out of the "OS mode" quite

- * easily. Note that this is just an example, the real code could be very

- * different depending on your requirements.

- */

diff --git a/docs/src/target.dox b/docs/src/target.dox
deleted file mode 100644
index 9904f1426..000000000
--- a/docs/src/target.dox
+++ /dev/null
@@ -1,82 +0,0 @@
-/*

-    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 target Application Range

- * @brief ChibiOS/RT Application Range.

- * - @ref applications

- * - @ref min_requirements

- * - @ref desirable_features

- * - @ref upper_limit

- * .

- * @section applications Application Scenarios

- * ChibiOS/RT is usable in many applicative areas, as example and not limited

- * to:

- * - Automotive.

- * - Robotic Applications.

- * - Consumer Electronics.

- * - Energy Management.

- * - Teaching and Learning.

- * - Hobby.

- * .

- * @section min_requirements Absolute Minimum Requirements

- * A certain set of minimum system requirements must be satisfied in order to

- * use ChibiOS/RT on a new architecture:

- * - 8bits architecture minimum.

- * - A "real" stack pointer that can be positioned anywhere in the data address

- *   space. The OS could be ported to architectures with an hardware stack but

- *   I wouldn't recommend it because the context switch would become

- *   ridiculously inefficient.

- * - Support for maskable interrupt sources and at least an OS-dedicated timer.

- * - Support for standard C89 (C99 supported) language with no

- *   architecture-related non-standard restrictions. Non standard mandatory

- *   language extensions or restrictions may result in reduced functionality

- *   or impossibility of use.

- * - 256/512bytes RAM permanently allocated to the kernel and its two mandatory

- *   threads "idle" and "main", the exact amount depends on the architecture.

- *   This figure is not inclusive of the HAL and device drivers (non mandatory

- *   components).

- * - 8KiB of program space for a full featured kernel scalable down to about

- *   1.2KiB for reduced configurations. This figure is not inclusive of the

- *   HAL and device drivers (non mandatory components).

- * .

- * @section desirable_features Desirable Features

- * - Efficient instruction set for linked lists traversal. The kernel makes

- *   extensive use of simple and bidirectional linked lists so the performance

- *   is directly affected by the supported addressing modes, number of

- *   registers etc.

- * - Uniformly sized C pointers.

- * - 2KiB RAM.

- * - 16KiB ROM/Flash.

- * .

- * @section upper_limit Upper Recommended Limit

- * The application range of ChibiOS/RT ends when one or more of the following

- * features are required:

- * - Separation between user code space and kernel space, both just logical or

- *   using a Memory Management/Protection Unit. Applications in ChibiOS/RT are

- *   supposed to be monolithic and trusted. The kernel and the application

- *   share the same address space.

- * - Multiple applications. ChibiOS/RT supports the single multithreaded

- *   application model.

- * - Multicore SMP architectures. Currently ChibiOS/RT only supports a single

- *   core unless running multiple distinct and separate OS instances.

- *   A true multicore kernel is planned for when multicore MCUs will become

- *   commonly available.

- * .

- */

diff --git a/docs/src/timing.dox b/docs/src/timing.dox
deleted file mode 100644
index 14c3b14ec..000000000
--- a/docs/src/timing.dox
+++ /dev/null
@@ -1,91 +0,0 @@
-/*

-    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_timing Reliable timings using Threads

- * One common task is to have threads do something at regular, scheduled,

- * intervals.

- * An obvious solution is to write something like this:

- * @code

-msg_t my_thread(void *param) {

-

-  while (TRUE) {

-    do_something();

-    chThdSleepMilliseconds(1000);   // Fixed interval

-  }

-}

- * @endcode

- * This example works well assuming that the @p do_something() execution time

- * is well below the system tick period and that @p my_thread() is not

- * preempted by other threads that could insert long intervals.<br>

- * If the above conditions are not satisfied you may have @p do_something()

- * executed at irregular intervals, as example:<br><br>

- * T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.<br><br>

- * Also note that the error increases over time and this kind of behavior can

- * lead to anomalies really hard to debug.

- * <h2>A better solution</h2>

- * It is possible to rewrite the above code using absolute deadlines rather

- * than fixed intervals:

- * @code

-msg_t my_thread(void *param) {

-

-  systick_t time = chTimeNow();     // T0

-  while (TRUE) {

-    time += MS2ST(1000);            // Next deadline

-    do_something();

-    chThdSleepUntil(time);

-  }

-}

- * @endcode

- * Using this code @p do_something() will always be executed at an absolute

- * deadline time and the error will not accumulate over time regardless of

- * the execution time and delays inserted by other threads.<br>

- * Note that this solution requires that the @p do_something() execution

- * time must not exceed the deadline or the thread would stay sleeping into

- * @p chThdSleepUntil().

- *

- * <h2>A different way</h2>

- * Another way to perform activities at regular intervals is the use of a

- * virtual timer. Virtual timers are able to generate callbacks at scheduled

- * intervals. Virtual timers are one shot timers so you need to restart them

- * from within the callback if you need a periodic timer like in this case.

- * @code

-VirtualTimer vt;

-

-void do_something(void *p) {

-

-  chVTSetI(&vt, MS2ST(1000), do_something, p);      // Restarts the timer.

-  // Periodic code here.

-}

-

-int main(int argc, char **argv) {

-

-  chSysLock();

-  chVTSetI(&vt, MS2ST(1000), do_something, NULL);   // Starts the timer.

-  chSysUnlock();

-  ...

-}

- * @endcode

- * Note that the callback code is executed from within the I-Locked state (see

- * @ref system_states) so you can only execute I-Class APIs from there (see

- * @ref api_suffixes).<br>

- * This solution has the advantage to not require a dedicated thread and

- * thus uses much less RAM but the periodic code must have a very short

- * execution time or it would degrade the overall system response time.

- */

diff --git a/docs/src/wakeup.dox b/docs/src/wakeup.dox
deleted file mode 100644
index b53806b78..000000000
--- a/docs/src/wakeup.dox
+++ /dev/null
@@ -1,148 +0,0 @@
-/*

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

- *

- * <h2>Synchronously waking up a specific thread</h2>

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

- *

- * <h2>Synchronously waking up one of the waiting threads</h2>

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

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

- *

- * <h2>Synchronously waking up all the waiting threads</h2>

- * In this scenario you want to synchronously wake up all the waiting threads,

- * if there are no waiting threads then nothing happens.<br>

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

- *

- * <h2>Asynchronously waking up a specific thread</h2>

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

- *

- * <h2>Asynchronously waking up one or more threads</h2>

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

- */