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

1 files changed, 388 insertions, 0 deletions

diff --git a/os/hal/hal.dox b/os/hal/hal.dox
new file mode 100644
index 000000000..77dc49a46
--- /dev/null
+++ b/os/hal/hal.dox
@@ -0,0 +1,388 @@
+/*

+    ChibiOS/RT - Copyright (C) 2006-2007 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/>.

+*/

+

+/**

+ * @defgroup IO HAL

+ * @brief Hardware Abstraction Layer.

+ * @details Under ChibiOS/RT the set of the various device driver interfaces

+ * is called the HAL subsystem: Hardware Abstraction Layer.<br>

+ * A device driver is usually split in two layers:

+ * - High Level Device Driver (<b>HLD</b>). This layer contains the definitions

+ *   of the driver's APIs and the platform independent part of the driver.<br>

+ *   An HLD is composed by two files:

+ *   - @<driver@>.c, the high level implementation file. This file must be

+ *     included in the Makefile in order to use the driver.

+ *   - @<driver@>.h, the high level header file. This file must be included

+ *     by the application code in order to access the driver's APIs.

+ *   .

+ * - Low Level Device Driver (<b>LLD</b>). This layer contains the platform

+ *   dependent part of the driver.<br>

+ *   A LLD is composed by two files:

+ *   - @<driver@>_lld.c, the low level implementation file. This file must be

+ *     included in the Makefile in order to use the driver.

+ *   - @<driver@>_lld.h, the high level header file. This file is implicitly

+ *     included by the HLD header file.

+ *   .

+ *   The LLD may be not present in those drivers that do not access the

+ *   hardware directly but through other device drivers, as example the

+ *   @ref MMC_SPI driver uses the @ref SPI and @ref PAL drivers in order

+ *   to implement its functionalities.

+ * .

+ * <h2>Available Device Drivers</h2>

+ * The I/O subsystem currently includes support for:

+ * - @ref HAL.

+ * - @ref PAL.

+ * - @ref SERIAL.

+ * - @ref ADC.

+ * - @ref CAN.

+ * - @ref MAC.

+ * - @ref MII.

+ * - @ref MMC_SPI.

+ * - @ref SPI.

+ * .

+ */

+

+/**

+ * @defgroup HAL HAL Driver

+ * @brief Hardware Abstraction Layer.

+ * @details The HAL driver performs the system initialization and includes

+ * the platform support code shared by the other drivers.

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup HAL_LLD HAL Low Level Driver

+ * @brief @ref HAL low level driver template.

+ *

+ * @ingroup HAL

+ */

+

+/**

+ * @defgroup HAL_CONF Configuration

+ * @brief @ref HAL Configuration.

+ *

+ * @ingroup HAL

+ */

+

+/**

+ * @defgroup PAL PAL Driver

+ * @brief I/O Ports Abstraction Layer

+ * @details This module defines an abstract interface for digital I/O ports.

+ * Note that most I/O ports functions are just macros. The macros

+ * have default software implementations that can be redefined in a

+ * @ref PAL_LLD if the target hardware supports special features like, as

+ * example, atomic bit set/reset/masking. Please refer to the ports specific

+ * documentation for details.<br>

+ * The @ref PAL has the advantage to make the access to the I/O ports platform

+ * independent and still be optimized for the specific architectures.<br>

+ * Note that the @ref PAL_LLD may also offer non standard macro and functions

+ * in order to support specific features but, of course, the use of such

+ * interfaces would not be portable. Such interfaces shall be marked with

+ * the architecture name inside the function names.

+ *

+ * <h2>Implementation Rules</h2>

+ * In implementing an @ref PAL_LLD there are some rules/behaviors that

+ * should be respected.

+ *

+ * <h3>Writing on input pads</h3>

+ * The behavior is not specified but there are implementations better than

+ * others, this is the list of possible implementations, preferred options

+ * are on top:

+ * -# The written value is not actually output but latched, should the pads

+ *    be reprogrammed as outputs the value would be in effect.

+ * -# The write operation is ignored.

+ * -# The write operation has side effects, as example disabling/enabling

+ *    pull up/down resistors or changing the pad direction. This scenario is

+ *    discouraged, please try to avoid this scenario.

+ * .

+ * <h3>Reading from output pads</h3>

+ * The behavior is not specified but there are implementations better than

+ * others, this is the list of possible implementations, preferred options

+ * are on top:

+ * -# The actual pads states are read (not the output latch).

+ * -# The output latch value is read (regardless of the actual pads states).

+ * -# Unspecified, please try to avoid this scenario.

+ * .

+ * <h3>Writing unused or unimplemented port bits</h3>

+ * The behavior is not specified.

+ *

+ * <h3>Reading from unused or unimplemented port bits</h3>

+ * The behavior is not specified.

+ *

+ * <h3>Reading or writing on pins associated to other functionalities</h3>

+ * The behavior is not specified.

+ *

+ * <h2>Usage</h2>

+ * The use of I/O ports requires the inclusion of the header file @p pal.h,

+ * this file is not automatically included @p ch.h like the other header

+ * files.

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup PAL_LLD PAL Low Level Driver

+ * @brief @ref PAL low level driver template.

+ * @details This file is a template for an I/O port low level driver.

+ *

+ * @ingroup PAL

+ */

+

+/**

+ * @defgroup SERIAL Serial Driver

+ * @brief Generic Serial Driver.

+ * @details This module implements a generic full duplex serial driver. The

+ * driver implements a @p SerialDriver interface and uses I/O Queues for

+ * communication between the upper and the lower driver. Event flags are used

+ * to notify the application about incoming data, outgoing data and other I/O

+ * events.<br>

+ * The  module also contains functions that make the implementation of the

+ * interrupt service routines much easier.

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup SERIAL_LLD Serial Low Level Driver

+ * @brief @ref SERIAL low level driver template.

+ * @details This file is a template for a serial low level driver.

+ *

+ * @ingroup SERIAL

+ */

+

+/**

+ * @defgroup SPI SPI Driver

+ * @brief Generic SPI Driver.

+ * @details This module implements a generic SPI driver. The driver implements

+ *          a state machine internally:

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

+      uninit [label="SPI_UNINIT", style="bold"];

+      stop  [label="SPI_STOP\nLow Power"];

+      ready [label="SPI_READY\nClock Enabled"];

+      active [label="SPI_ACTIVE\nBus Active"];

+      uninit -> stop [label="spiObjectInit()"];

+      stop -> ready [label="spiStart()"];

+      ready -> ready [label="spiStart()"];

+      ready -> ready [label="spiIgnore()"];

+      ready -> stop [label="spiStop()"];

+      stop -> stop [label="spiStop()"];

+      ready -> active [label="spiSelect()"];

+      active -> active [label="spiSelect()"];

+      active -> ready [label="spiUnselect()"];

+      ready -> ready [label="spiUnselect()"];

+      active -> active [label="spiIgnore()\nspiExchange()\nspiSend()\nspiReceive()"];

+  }

+ * @enddot

+ *

+ * The driver is not thread safe for performance reasons, if you need to access

+ * the SPI bus from multiple thread then use the @p spiAcquireBus() and

+ * @p spiReleaseBus() APIs in order to gain exclusive access.

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup SPI_LLD SPI Low Level Driver

+ * @brief @ref SPI low level driver template.

+ * @details This file is a template for a SPI low level driver.

+ *

+ * @ingroup SPI

+ */

+

+/**

+ * @defgroup ADC ADC Driver

+ * @brief Generic ADC Driver.

+ * @details This module implements a generic ADC driver. The driver implements

+ *          a state machine internally:

+ * @dot

+  digraph example {

+      rankdir="LR";

+      node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.8", height="0.8"];

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

+      uninit [label="ADC_UNINIT", style="bold"];

+      stop  [label="ADC_STOP\nLow Power"];

+      ready [label="ADC_READY\nClock Enabled"];

+      running [label="ADC_RUNNING"];

+      complete [label="ADC_COMPLETE"];

+      uninit -> stop [label="adcObjectInit()"];

+      stop -> ready [label="adcStart()"];

+      ready -> ready [label="adcStart()"];

+      ready -> ready [label="adcWaitConversion()"];

+      ready -> stop [label="adcStop()"];

+      stop -> stop [label="adcStop()"];

+      ready -> running [label="adcStartConversion()"];

+      running -> ready [label="adcStopConversion()"];

+      running -> complete [label="End of Conversion"];

+      complete -> running [label="adcStartConversion()"];

+      complete -> ready [label="adcStopConversion()"];

+      complete -> ready [label="adcWaitConversion()"];

+      complete -> stop [label="adcStop()"];

+  }

+ * @enddot

+ *

+ * The driver supports a continuous conversion mode with circular buffer,

+ * callback functions allow to process the converted data in real time.

+ * Please refer to the documentation of the function @p adcStartConversion().

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup ADC_LLD ADC Low Level Driver

+ * @brief @ref ADC low level driver template.

+ * @details This file is a template for a ADC low level driver.

+ *

+ * @ingroup ADC

+ */

+

+/**

+ * @defgroup CAN CAN Driver

+ * @brief Generic ADC Driver.

+ * @details This module implements a generic ADC driver. The driver implements

+ *          a state machine internally:

+ * @dot

+  digraph example {

+      rankdir="LR";

+      node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.8", height="0.8"];

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

+      uninit [label="CAN_UNINIT", style="bold"];

+      stop  [label="CAN_STOP\nLow Power"];

+      ready [label="CAN_READY\nClock Enabled"];

+      sleep [label="CAN_SLEEP\nLow Power"];

+      uninit -> stop [label="canObjectInit()"];

+      stop -> stop [label="canStop()"];

+      stop -> ready [label="canStart()"];

+      ready -> stop [label="canStop()"];

+      ready -> ready [label="canReceive()\ncanTransmit()"];

+      ready -> ready [label="canStart()"];

+      ready -> sleep [label="canSleep()"];

+      sleep -> sleep [label="canSleep()"];

+      sleep -> ready [label="canWakeup()"];

+      sleep -> ready [label="wakeup event"];

+  }

+ * @enddot

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup CAN_LLD CAN Low Level Driver

+ * @brief @ref HAL low level driver template.

+ *

+ * @ingroup CAN

+ */

+

+/**

+ * @defgroup MAC MAC Driver

+ * @brief Generic MAC driver.

+ * @details This module implements a generic interface for MAC (Media

+ *          Access Control) drivers, as example Ethernet controllers.

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup MAC_LLD MAC Low Level Driver

+ * @brief @ref MAC low level driver template.

+ * @details This file is a template for a MAC low level driver.

+ *

+ * @ingroup MAC

+ */

+

+/**

+ * @defgroup MII MII Driver

+ * @brief Generic MII driver.

+ * @details This module implements a generic interface for MII (Media

+ *          Independent Interface) drivers.

+ *          The MII/RMII/GMII/RGMII/SGMII buses are standard interfaces meant

+ *          to connect a MAC block to a PHY transceiver.<br>

+ *          A @ref MII is usually used from within a @ref MAC and is not

+ *          meant to be used directly from the application code.

+ *

+ * @ingroup IO

+ */

+

+/**

+ * @defgroup MII_LLD MII Low Level Driver

+ * @brief @ref MII low level driver template.

+ * @details This file is a template for a MII low level driver.

+ *

+ * @ingroup MII

+ */

+ 

+/**

+ * @defgroup MMC_SPI MMC over SPI Driver

+ * @brief Generic MMC driver.

+ * @details This module implements a portable MMC driver that uses a SPI

+ *          driver as physical layer.<br>

+ *          The driver implements the following state machine:

+ * @dot

+  digraph example {

+      rankdir="LR";

+      node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.8"];

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

+

+      any [label="Any State"];

+      stop2 [label="MMC_STOP\nLow Power"];

+      uninit [label="MMC_UNINIT", style="bold"];

+      stop [label="MMC_STOP\nLow Power"];

+      wait [label="MMC_WAIT\nWaiting Card"];

+      inserted [label="MMC_INSERTED\nCard Inserted"];

+      ready [label="MMC_READY\nCard Ready"];

+      reading [label="MMC_READING\nReading"];

+      writing [label="MMC_WRITING\nWriting"];

+

+      uninit -> stop [label="mmcObjectInit()"];

+      stop -> wait [label="mmcStart()", constraint=false];

+      wait -> inserted [label="insertion (inserted event)"];

+      inserted -> inserted [label="mmcDisconnect()"];

+      inserted -> ready [label="mmcConnect()"];

+      ready -> ready [label="mmcConnect()"];

+      ready -> inserted [label="mmcDisconnect()"];

+      ready -> reading [label="mmcStartSequentialRead()"];

+      reading -> reading [label="mmcSequentialRead()"];

+      reading -> ready [label="mmcStopSequentialRead()"];

+      reading -> ready [label="read error"];

+      ready -> writing [label="mmcStartSequentialWrite()"];

+      writing -> writing [label="mmcSequentialWrite()"];

+      writing -> ready [label="mmcStopSequentialWrite()"];

+      writing -> ready [label="write error"];

+

+      inserted -> wait [label="removal (removed event)"];

+      ready -> wait [label="removal (removed event)"];

+      reading -> wait [label="removal (removed event)"];

+      writing -> wait [label="removal (removed event)"];

+

+      any -> stop2 [label="mmcStop()"];

+  }

+ * @enddot

+ *

+ * The MMC drivers currently supports only cards with capacity up to 2GB

+ * and does not implement CRC checking. Hot plugging and removal are supported

+ * through kernel events.

+ *

+ * @ingroup IO

+ */

+

+ 
\ No newline at end of file