diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Doxyfile | 4 | ||||
| -rw-r--r-- | docs/src/architecture.dox | 261 | ||||
| -rw-r--r-- | docs/src/articles.dox | 1 | ||||
| -rw-r--r-- | docs/src/concepts.dox | 26 | ||||
| -rw-r--r-- | docs/src/goals.dox | 2 | ||||
| -rw-r--r-- | docs/src/lifecycle.dox | 67 | ||||
| -rw-r--r-- | docs/src/main.dox | 1 |
7 files changed, 340 insertions, 22 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile index 02ed1edb3..1ea40a3b8 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -598,7 +598,8 @@ INPUT = ../docs/src \ ../os/hal/platforms/MSP430 \ ../os/hal/platforms/STM32 \ ../os/various \ - ../test + ../test \ + ../ext/ext.dox # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is @@ -1315,6 +1316,7 @@ PREDEFINED = __DOXYGEN__ \ CH_USE_MESSAGES=1 \ CH_USE_MAILBOXES=1 \ CH_USE_DYNAMIC=1 \ + CH_USE_REGISTRY=1 \ CH_DBG_ENABLE_ASSERTS=1 \ CH_DBG_ENABLE_CHECKS=1 \ CH_DBG_ENABLE_TRACE=1 \ 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.
+ */
diff --git a/docs/src/articles.dox b/docs/src/articles.dox index bcdb62b6c..f8a40e2f7 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -25,6 +25,7 @@ * - @subpage article_wakeup
* - @subpage article_manage_memory
* - @subpage article_stacks
+ * - @subpage article_lifecycle
* - @subpage article_mutual_exclusion
* - @subpage article_atomic
* - @subpage article_saveram
diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index b6a9e8630..e1d5f6156 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -18,8 +18,8 @@ */
/**
- * @page concepts Concepts and Architecture
- * @brief ChibiOS/RT Concepts and Architecture
+ * @page concepts Kernel Concepts
+ * @brief ChibiOS/RT Kernel Concepts
* - @ref naming
* - @ref api_suffixes
* - @ref interrupt_classes
@@ -28,7 +28,6 @@ * - @ref thread_states
* - @ref priority
* - @ref warea
- * - @ref architecture
* .
* @section naming Naming Conventions
* ChibiOS/RT APIs are all named following this convention:
@@ -52,10 +51,10 @@ * @section interrupt_classes Interrupt Classes
* In ChibiOS/RT there are three logical interrupt classes:
* - <b>Regular Interrupts</b>. Maskable interrupt sources that cannot
- * preempt 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.
+ * 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.
* - <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
@@ -246,17 +245,4 @@ * .
* See the @ref core documentation for details, the area may change on
* the various ports and some structures may not be present (or be zero-sized).
- *
- * @section architecture Architectural Diagram
- * The following diagram shows the relationships among the hardware, the
- * various ChibiOS/RT subsystems and the application code.
- * <br><br>
- * @image html arch.png
- * <br>
- * In this diagram the device drivers are at the same level of the application
- * code because both have access to the system services and can directly
- * access the hardware.<br>
- * Of course it is possible to create in the application architecture several
- * extra layers, this is just not part of the kernel architecture but part of
- * the overall system design.
*/
diff --git a/docs/src/goals.dox b/docs/src/goals.dox index f41308e26..eb1b2bd81 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -69,7 +69,7 @@ * <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 is around <b>5.2KiB</b>
+ * 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.
diff --git a/docs/src/lifecycle.dox b/docs/src/lifecycle.dox new file mode 100644 index 000000000..d96795b21 --- /dev/null +++ b/docs/src/lifecycle.dox @@ -0,0 +1,67 @@ +/*
+ 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:
+ * - Static threads. The memory used for static threads is allocated at
+ * compile time so static threads are always there, there is no management
+ * to be done.
+ * - Dynamic threads. 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 becomes objects
+ * with a reference counter. The memory of a thread, if dynamic, is released
+ * 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 simplest way to ensure that the memory is released is
+ * that another threads performs 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 and frees the
+ * terminated ones.
+ */
diff --git a/docs/src/main.dox b/docs/src/main.dox index a5ae9a8ca..39601e563 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -60,6 +60,7 @@ * <h2>Related pages</h2>
* - @subpage lic_faq
* - @subpage goals
+ * - @subpage architecture
* - @subpage concepts
* - @subpage articles
* - @subpage testsuite
|