From 508b7bc93297fcb74af43b11b1435aa96add3c85 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 25 Feb 2010 16:48:00 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1675 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/architecture.dox | 261 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 docs/src/architecture.dox (limited to 'docs/src/architecture.dox') 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 . +*/ + +/** + * @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: + * - Kernel, this is the platform independent part of the OS kernel. + * - HAL, 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. + * - Port, 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.
+ * 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. + * - Platform, this component contains a set of device drivers + * implementations. + * - Various, 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:

+ * @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.
+ * 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:

+ * @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:

+ * @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:

+ * @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.
+ * The current internal HAL organization is the following:

+ * @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 + *
+ * See @ref IO for details about the various HAL subsystems. + */ -- cgit v1.2.3