diff options
Diffstat (limited to 'docs/src/architecture.dox')
| -rw-r--r-- | docs/src/architecture.dox | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/docs/src/architecture.dox b/docs/src/architecture.dox new file mode 100644 index 000000000..d9a512b10 --- /dev/null +++ b/docs/src/architecture.dox @@ -0,0 +1,261 @@ +/*
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+
+ This file is part of ChibiOS/RT.
+
+ ChibiOS/RT is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 3 of the License, or
+ (at your option) any later version.
+
+ ChibiOS/RT is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @page architecture Architecture
+ * @brief ChibiOS/RT General Architecture
+ * - @ref components
+ * - @ref dependencies
+ * - @ref kernel_arch
+ * - @ref hal_arch
+ * .
+ * @section components Components
+ * ChibiOS/RT is composed of several major components, each component can be
+ * composed of one of more subsystems. The main components are:
+ * - <b>Kernel</b>, this is the platform independent part of the OS kernel.
+ * - <b>HAL</b>, this component contains a set of abstract device drivers
+ * that offer a common I/O API to the application across all the support
+ * platforms. The HAL code is totally portable across platforms.
+ * - <b>Port</b>, this is the platform dependent part of the OS kernel. This
+ * component is responsible of the system startup, interrupts abstraction,
+ * lock/unlock primitives, context switch related structures and code.<br>
+ * The component usually contains very little code because the OS is very
+ * portable but the quality of the implementation of the Port component
+ * affects heavily the performance of the ported OS. It is probably the
+ * most critical part of the whole OS.
+ * - <b>Platform</b>, this component contains a set of device drivers
+ * implementations.
+ * - <b>Various</b>, a library of various extra components that do not belong
+ * to any particular component but can make life easier while developing an
+ * embedded application.
+ * .
+ * @section dependencies Dependencies
+ * The following diagram shows the relationships among the various components
+ * that compose the system:<br><br>
+ * @dot
+ digraph example {
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="1.0", height="0.25"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ Application [label="Application"];
+ HAL [label="HAL"];
+ Platform [label="Platform"];
+ Kernel [label="Kernel"];
+ Port [label="Port"];
+ HW [label="Hardware", style="filled", width="3.0", height="0.3"];
+
+ Application -> Kernel;
+ Application -> HAL;
+ Application -> HW [label=" (not recommended)"];
+ HAL -> Platform;
+ HAL -> Kernel;
+ Platform -> Kernel;
+ Platform -> HW;
+ Kernel -> Port;
+ Port -> HW;
+ }
+ * @enddot
+ *
+ * @section kernel_arch Kernel Architecture
+ * The kernel itself is very modular and is composed of several subsystems,
+ * most subsystems are optional and can be switched of in the kernel
+ * configuration file @p chconf.h.<br>
+ * The current kernel subsystems are divided in five categories:
+ * - @ref base, this category contains the mandatory kernel
+ * subsystems:
+ * - @ref system, low level locks, initialization.
+ * - @ref time, virtual timers and time APIs.
+ * - @ref scheduler, scheduler APIs, all the higher level synchronization
+ * mechanism are implemented through this subsystem, it is very flexible
+ * but not recommended for direct use in user code.
+ * - @ref threads, thread-related APIs.
+ * .
+ * Base services diagram:<br><br>
+ * @dot
+ digraph example {
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="1.0", height="0.25"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ Threads -> Scheduler;
+ Scheduler-> System;
+ Scheduler-> Timers;
+ System-> Timers;
+ }
+ * @enddot
+ * - @ref synchronization, this category contains the synchronization-related
+ * subsystems, each one of the provided mechanism can be configured out of
+ * the kernel if not needed.
+ * - @ref semaphores, counter semaphores subsystem.
+ * - @ref mutexes, mutexes subsystem with support to the priority inheritance
+ * algorithm (fully implemented, any depht).
+ * - @ref condvars, condition variables, together with mutexes the condition
+ * variables allow the implementation of monitor constructs.
+ * - @ref events, event sources and event flags with flexible support for
+ * and/or conditions and automatic dispatching to handler functions.
+ * - @ref messages, lightweight synchronous messages.
+ * - @ref mailboxes, asynchronous messages queues.
+ * .
+ * All the synchronization mechanisms are built on top of the Scheduler APIs
+ * except Mailboxes that are build on top of Semaphores and Condition
+ * Variables that implicitly refer to Mutexes:<br><br>
+ * @dot
+ digraph example {
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="1.0", height="0.25"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ Semaphores -> Scheduler;
+ Mutexes -> Scheduler;
+ Condvars -> Scheduler;
+ Condvars -> Mutexes;
+ Events -> Scheduler;
+ Messages -> Scheduler;
+ Mailboxes -> Semaphores;
+ }
+ * @enddot
+ * - @ref memory, memory management, multiple non-alternative schemes are
+ * available:
+ * - @ref memcore, centralized core memory manager, this subsystems is used
+ * by the other allocators in order to get chunks of memory in a consistent
+ * way.
+ * - @ref heaps, central heap manager using a first fit strategy, it also
+ * allow the creation of multiple heaps in order to handle non uniform
+ * memory areas.
+ * - @ref pools, very fast fixed size objects allocator.
+ * - @ref threads (dynamic), usually threads are static objects in ChibiOS/RT
+ * but there is the option for dynamic threads management, please see the
+ * article @ref article_lifecycle.
+ * .
+ * The various allocators follow a precise hierarchy:<br><br>
+ * @dot
+ digraph example {
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="1.0", height="0.25"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ Core [label="Core Allocator"];
+ Dynamic [label="Dynamic Threads"];
+ Heaps [label="Dynamic Heaps"];
+ Pools [label="Memory Pools"];
+ C [label="C-runtime"];
+
+ Dynamic -> Heaps;
+ Dynamic -> Pools;
+ Heaps -> Core;
+ Pools -> Core;
+ C -> Core;
+ }
+ * @enddot
+ * Please also see the article @ref article_manage_memory.
+ * - @ref io_support, the kernel also provides mechanisms and abstract data
+ * interfaces that can be used by non-kernel components, the HAL as example.
+ * - @ref data_streams, abstract streams interface.
+ * - @ref io_channels, abstract I/O channels that inherits from the abstract
+ * stream interface.
+ * - @ref io_queues, generic, byte wide, I/O queues APIs.
+ * .
+ * - @ref debug, debug services and APIs. The @ref registry susystem can be
+ * seen as part of the debug category even if it finds use in non-debug
+ * roles.
+ * .
+ * @section hal_arch HAL Architecture
+ * The HAL is a collection of abstract device drivers, it relies on the
+ * Platform component for the low level implementation on specific
+ * hardware.<br>
+ * The current internal HAL organization is the following:<br><br>
+ * @dot
+ digraph example {
+ rankdir="LR";
+
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="1.0", height="0.25"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ subgraph cluster_HAL {
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="0.6", height="0.25"];
+ ADC [label="ADC"];
+ CAN [label="CAN"];
+ HAL [label="HAL"];
+ MAC [label="MAC"];
+ PAL [label="PAL"];
+ PWM [label="PWM"];
+ SER [label="SER"];
+ SPI [label="SPI"];
+ MMC_SD [label="MMC/SD"];
+ color = blue;
+ label = "HAL";
+ }
+
+ subgraph cluster_Platform {
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="0.6", height="0.25"];
+ ADC_LLD [label="ADC_LLD"];
+ CAN_LLD [label="CAN_LLD"];
+ HAL_LLD [label="HAL_LLD"];
+ MAC_LLD [label="MAC_LLD"];
+ PAL_LLD [label="PAL_LLD"];
+ PWM_LLD [label="PWM_LLD"];
+ SER_LLD [label="SER_LLD"];
+ SPI_LLD [label="SPI_LLD"];
+ color = blue;
+ label = "Platform";
+ }
+
+ node [shape=rectangle, fontname=Helvetica, fontsize=8,
+ fixedsize="true", width="1", height="0.5"];
+ edge [fontname=Helvetica, fontsize=8];
+
+ Application [label="Application"];
+ HW [label="Hardware", style="filled"];
+
+ ADC -> ADC_LLD;
+ CAN -> CAN_LLD;
+ HAL -> HAL_LLD;
+ MAC -> MAC_LLD;
+ PAL -> PAL_LLD;
+ PWM -> PWM_LLD;
+ SER -> SER_LLD;
+ SPI -> SPI_LLD;
+ MMC_SD -> SPI [constraint=false];
+
+ Application -> ADC;
+ Application -> CAN;
+ Application -> HAL;
+ Application -> MAC;
+ Application -> PAL;
+ Application -> PWM;
+ Application -> SER;
+ Application -> SPI;
+ Application -> MMC_SD;
+ ADC_LLD -> HW;
+ CAN_LLD -> HW;
+ HAL_LLD -> HW;
+ MAC_LLD -> HW;
+ PAL_LLD -> HW;
+ PWM_LLD -> HW;
+ SER_LLD -> HW;
+ SPI_LLD -> HW;
+ }
+ * @enddot
+ * <br>
+ * See @ref IO for details about the various HAL subsystems.
+ */
|