/*
    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 depht).
 *   - @ref condvars, condition variables, together with mutexes the condition
 *     variables allow the implementation of monitor constructs.
 *   - @ref events, event sources and event flags with flexible support for
 *     and/or conditions and automatic dispatching to handler functions.
 *   - @ref messages, lightweight synchronous messages.
 *   - @ref mailboxes, asynchronous messages queues.
 *   .
 *   All the synchronization mechanisms are built on top of the Scheduler APIs
 *   except Mailboxes that are build on top of Semaphores and Condition
 *   Variables that implicitly refer to Mutexes:<br><br>
 * @dot
  digraph example {
    node [shape=rectangle, fontname=Helvetica, fontsize=8,
          fixedsize="true", width="1.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
 *     allow the creation of multiple heaps in order to handle non uniform
 *     memory areas.
 *   - @ref pools, very fast fixed size objects allocator.
 *   - @ref threads (dynamic), usually threads are static objects in ChibiOS/RT
 *     but there is the option for dynamic threads management, please see the
 *     article @ref article_lifecycle.
 *   .
 *   The various allocators follow a precise hierarchy:<br><br>
 * @dot
  digraph example {
    node [shape=rectangle, fontname=Helvetica, fontsize=8,
          fixedsize="true", width="1.0", height="0.25"];
    edge [fontname=Helvetica, fontsize=8];

    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 susystem can be
 *   seen as part of the debug category even if it finds use in non-debug
 *   roles.
 * .
 * @section hal_arch HAL Architecture
 * The HAL is a collection of abstract device drivers, it relies on the
 * Platform component for the low level implementation on specific
 * hardware.<br>
 * The current internal HAL organization is the following:<br><br>
 * @dot
  digraph example {
    rankdir="LR";

    node [shape=rectangle, fontname=Helvetica, fontsize=8,
          fixedsize="true", width="1.0", height="0.25"];
    edge [fontname=Helvetica, fontsize=8];

    subgraph cluster_HAL {
      node [shape=rectangle, fontname=Helvetica, fontsize=8,
            fixedsize="true", width="0.6", height="0.25"];
      ADC [label="ADC"];
      CAN [label="CAN"];
      HAL [label="HAL"];
      MAC [label="MAC"];
      PAL [label="PAL"];
      PWM [label="PWM"];
      SER [label="SER"];
      SPI [label="SPI"];
      MMC_SD [label="MMC/SD"];
      color = blue;
      label = "HAL";
    }

    subgraph cluster_Platform {
      node [shape=rectangle, fontname=Helvetica, fontsize=8,
            fixedsize="true", width="0.6", height="0.25"];
      ADC_LLD [label="ADC_LLD"];
      CAN_LLD [label="CAN_LLD"];
      HAL_LLD [label="HAL_LLD"];
      MAC_LLD [label="MAC_LLD"];
      PAL_LLD [label="PAL_LLD"];
      PWM_LLD [label="PWM_LLD"];
      SER_LLD [label="SER_LLD"];
      SPI_LLD [label="SPI_LLD"];
      color = blue;
      label = "Platform";
    }

    node [shape=rectangle, fontname=Helvetica, fontsize=8,
          fixedsize="true", width="1", height="0.5"];
    edge [fontname=Helvetica, fontsize=8];

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

    ADC -> ADC_LLD;
    CAN -> CAN_LLD;
    HAL -> HAL_LLD;
    MAC -> MAC_LLD;
    PAL -> PAL_LLD;
    PWM -> PWM_LLD;
    SER -> SER_LLD;
    SPI -> SPI_LLD;
    MMC_SD -> SPI [constraint=false];

    Application -> ADC;
    Application -> CAN;
    Application -> HAL;
    Application -> MAC;
    Application -> PAL;
    Application -> PWM;
    Application -> SER;
    Application -> SPI;
    Application -> MMC_SD;
    ADC_LLD -> HW;
    CAN_LLD -> HW;
    HAL_LLD -> HW;
    MAC_LLD -> HW;
    PAL_LLD -> HW;
    PWM_LLD -> HW;
    SER_LLD -> HW;
    SPI_LLD -> HW;
  }
 * @enddot
 * <br>
 * See @ref IO for details about the various HAL subsystems.
 */