tinySA/os/hal/hal.dox

/*
    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/>.
*/

/**
 * @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. The HAL is the
 * abstract interface between ChibiOS/RT application and hardware.
 *
 * @section hal_device_driver_arch HAL Device Drivers Architecture
 * 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:
 *   - @p @<driver@>.c, the HLD implementation file. This file must be
 *     included in the Makefile in order to use the driver.
 *   - @p @<driver@>.h, the HLD header file. This file is implicitly
 *     included by the HAL header file @p hal.h.
 *   .
 * - 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:
 *   - @p @<driver@>_lld.c, the LLD implementation file. This file must be
 *     included in the Makefile in order to use the driver.
 *   - @p @<driver@>_lld.h, the LLD 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.
 * .
 * @subsection hal_device_driver_diagram Diagram
 * @dot
  digraph example {
    node [shape=rectangle, fontname=Helvetica, fontsize=8,
          fixedsize="true", width="2.0", height="0.4"];
    edge [fontname=Helvetica, fontsize=8];
    app [label="Application"];
    hld [label="High Level Driver"];
    lld [label="Low Level Driver"];
    hw [label="Microcontroller Hardware"];
    hal_lld [label="HAL shared low level code"];
    app->hld;
    hld->lld;
    lld-> hw;
    lld->hal_lld;
    hal_lld->hw;
  }
 * @enddot
 */

/**
 * @defgroup HAL_CONF Configuration
 * @brief @ref HAL Configuration.
 * @details The file @p halconf.h contains the high level settings for all
 * the drivers supported by the HAL. The low level, platform dependent,
 * settings are contained in the @p mcuconf.h file instead and are describe
 * in the various platforms reference manuals.
 *
 * @ingroup IO
 */

/**
 * @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. This driver does
 * contain any API function except for a general initialization function
 * @p halInit() that must be invoked before any HAL service can be used,
 * usually the HAL initialization is performed immediately before the
 * kernel initialization.
 *
 * @ingroup IO
 */

/**
 * @defgroup HAL_LLD HAL Low Level Driver
 * @brief @ref HAL low level driver template.
 *
 * @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.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_PAL option
 *          must be enabled in @p halconf.h.
 *
 * @section pal_1 Implementation Rules
 * In implementing an @ref PAL_LLD there are some rules/behaviors that
 * should be respected.
 *
 * @subsection pal_1_1 Writing on input pads
 * 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.
 * .
 * @subsection pal_1_2 Reading from output pads
 * 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.
 * .
 * @subsection pal_1_3 Writing unused or unimplemented port bits
 * The behavior is not specified.
 *
 * @subsection pal_1_4 Reading from unused or unimplemented port bits
 * The behavior is not specified.
 *
 * @subsection pal_1_5 Reading or writing on pins associated to other functionalities
 * The behavior is not specified.
 *
 * @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 not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref PAL_LLD entry points.
 *
 * @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.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_SERIAL option
 *          must be enabled in @p halconf.h.
 *
 * @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 not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref SERIAL_LLD entry points.
 *
 * @ingroup SERIAL
 */

/**
 * @defgroup I2C I2C Driver
 * @brief Generic I2C Driver.
 * @details This module implements a generic I2C driver.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_I2C option
 *          must be enabled in @p halconf.h.
 *
 * @section i2c_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @if LATEX_PDF
 * @else
 * @endif
 *
 * The driver is not thread safe for performance reasons, if you need to access
 * the I2C bus from multiple thread then use the @p i2cAcquireBus() and
 * @p i2cReleaseBus() APIs in order to gain exclusive access.
 *
 * @ingroup IO
 */

/**
 * @defgroup I2C_LLD I2C Low Level Driver
 * @brief @ref I2C low level driver template.
 * @details This file is a template for an I2C low level driver not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref I2C_LLD entry points.
 *
 * @ingroup I2C
 */

/**
 * @defgroup SPI SPI Driver
 * @brief Generic SPI Driver.
 * @details This module implements a generic SPI driver.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_SPI option
 *          must be enabled in @p halconf.h.
 *
 * @section spi_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @if LATEX_PDF
 * @dot
  digraph example {
    size="5, 7";
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"];
    edge [fontname=Helvetica, fontsize=8];
    stop  [label="SPI_STOP\nLow Power"];
    uninit [label="SPI_UNINIT", style="bold"];
    ready [label="SPI_READY\nClock Enabled"];
    selected [label="SPI_SELECTED\nSlave Selected"];
    active [label="SPI_ACTIVE\nBus Active"];
    sync [label="SPI_SYNC\nSynchronization"];
    uninit -> stop [label="spiInit()", constraint=false];
    stop -> ready [label="spiStart()"];
    ready -> ready [label="spiUnselect()\nspiStart()\nspiWait()"];
    ready -> stop [label="spiStop()"];
    stop -> stop [label="spiStop()"];
    ready -> selected [label="spiSelect()"];
    selected -> selected [label="spiSelect()\nspiWait()"];
    selected -> ready [label="spiUnselect()"];
    selected -> active [label="spiIgnore()\nspiExchange()\nspiSend()\nspiReceive()"];
    active -> selected [label="spiWait()\n>spc_endcb<"];
    ready -> sync [label="spiSynchronize()"];
    sync -> ready [label="spiWait()\n>spc_endcb<"];
  }
 * @else
 * @dot
  digraph example {
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"];
    edge [fontname=Helvetica, fontsize=8];
    stop  [label="SPI_STOP\nLow Power"];
    uninit [label="SPI_UNINIT", style="bold"];
    ready [label="SPI_READY\nClock Enabled"];
    selected [label="SPI_SELECTED\nSlave Selected"];
    active [label="SPI_ACTIVE\nBus Active"];
    sync [label="SPI_SYNC\nSynchronization"];
    uninit -> stop [label="spiInit()", constraint=false];
    stop -> ready [label="spiStart()"];
    ready -> ready [label="spiUnselect()\nspiStart()\nspiWait()"];
    ready -> stop [label="spiStop()"];
    stop -> stop [label="spiStop()"];
    ready -> selected [label="spiSelect()"];
    selected -> selected [label="spiSelect()\nspiWait()"];
    selected -> ready [label="spiUnselect()"];
    selected -> active [label="spiIgnore()\nspiExchange()\nspiSend()\nspiReceive()"];
    active -> selected [label="spiWait()\n>spc_endcb<"];
    ready -> sync [label="spiSynchronize()"];
    sync -> ready [label="spiWait()\n>spc_endcb<"];
  }
 * @enddot
 * @endif
 *
 * 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 an SPI low level driver not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref SPI_LLD entry points.
 *
 * @ingroup SPI
 */

/**
 * @defgroup ADC ADC Driver
 * @brief Generic ADC Driver.
 * @details This module implements a generic ADC driver.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_ADC option
 *          must be enabled in @p halconf.h.
 *
 * @section adc_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @if LATEX_PDF
 * @dot
  digraph example {
    size="5, 7";
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.8", height="0.8"];
    edge [fontname=Helvetica, fontsize=8];
    stop  [label="ADC_STOP\nLow Power"];
    uninit [label="ADC_UNINIT", style="bold"];
    ready [label="ADC_READY\nClock Enabled"];
    running [label="ADC_RUNNING"];
    complete [label="ADC_COMPLETE"];
    uninit -> stop [label="adcInit()", constraint=false];
    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
 * @else
 * @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];
    stop  [label="ADC_STOP\nLow Power"];
    uninit [label="ADC_UNINIT", style="bold"];
    ready [label="ADC_READY\nClock Enabled"];
    running [label="ADC_RUNNING"];
    complete [label="ADC_COMPLETE"];
    uninit -> stop [label="adcInit()", constraint=false];
    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
 * @endif
 *
 * 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 an ADC low level driver not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref ADC_LLD entry points.
 *
 * @ingroup ADC
 */

/**
 * @defgroup CAN CAN Driver
 * @brief Generic CAN Driver.
 * @details This module implements a generic ADC driver.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_CAN option
 *          must be enabled in @p halconf.h.
 *
 * @section can_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @if LATEX_PDF
 * @dot
  digraph example {
    size="5, 7";
    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="canInit()"];
    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
 * @else
 * @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="canInit()"];
    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
 * @endif
 *
 * @ingroup IO
 */

/**
 * @defgroup CAN_LLD CAN Low Level Driver
 * @brief @ref CAN low level driver template.
 * @details This file is a template for a CAN low level driver not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref CAN_LLD entry points.
 *
 * @ingroup CAN
 */

/**
 * @defgroup PWM PWM Driver
 * @brief Generic PWM Driver.
 * @details This module implements a generic PWM driver.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_PWM option
 *          must be enabled in @p halconf.h.
 *
 * @section pwm_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @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="PWM_UNINIT", style="bold"];
    stop  [label="PWM_STOP\nLow Power"];
    ready [label="PWM_READY\nClock Enabled"];
    uninit -> stop [label="pwmInit()"];
    stop -> stop [label="pwmStop()"];
    stop -> ready [label="pwmStart()"];
    ready -> stop [label="pwmStop()"];
    ready -> ready [label="pwmEnableChannel()\npwmDisableChannel()"];
  }
 * @enddot
 *
 * @ingroup IO
 */

/**
 * @defgroup PWM_LLD PWM Low Level Driver
 * @brief @ref PWM low level driver template.
 * @details This file is a template for a PWM low level driver not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref PWM_LLD entry points.
 *
 * @ingroup PWM
 */

/**
 * @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.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_MAC option
 *          must be enabled in @p halconf.h.
 *
 * @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 not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref MAC_LLD entry points.
 *
 * @ingroup MAC
 */

/**
 * @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.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_MMC_SPI option
 *          must be enabled in @p halconf.h.
 *
 * @section mmc_spi_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @if LATEX_PDF
 * @dot
  digraph example {
    size="5, 7";
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.8", 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="mmcInit()"];
    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
 * @else
 * @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];

    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="mmcInit()"];
    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
 * @endif
 *
 * 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
 */

 
/**
 * @defgroup UART UART Driver
 * @brief Generic UART Driver.
 * @details This driver abstracts a generic UART peripheral, the API is
 * designed to be:
 * - Unbuffered and copy-less, transfers are always directly performed
 *   from/to the application-level buffers without extra copy operations.
 * - Asynchronous, the API is always non blocking.
 * - Callbacks capable, operations completion and other events are notified
 *   via callbacks.
 * .
 * Special hardware features like deep hardware buffers, DMA transfers
 * are hidden to the user but fully supportable by the low level
 * implementations.<br>
 * This driver model is best used where communication events are meant to
 * drive an higher level state machine, as example:
 * - RS485 drivers.
 * - Multipoint network drivers.
 * - Serial protocol decoders.
 * .
 * If your application requires a synchronoyus buffered driver then the
 * @ref SERIAL should be used instead.
 * @pre     In order to use the ADC driver the @p CH_HAL_USE_UART option
 *          must be enabled in @p halconf.h.
 *
 * @section uart_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @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="UART_UNINIT", style="bold"];
    stop  [label="UART_STOP\nLow Power"];
    ready [label="UART_READY\nClock Enabled"];

    uninit -> stop [label="\nuartInit()"];
    stop -> ready [label="\nuartStart()"];
    ready -> ready [label="\nuartStart()"];
    ready -> stop [label="\nuartStop()"];
    stop -> stop [label="\nuartStop()"];
  }
 * @enddot
 *
 * @subsection uart_1_1 Transmitter sub State Machine
 * The follow diagram describes the transmitter state machine, this diagram
 * is valid while the driver is in the @p UART_READY state. This state
 * machine is automatically reset to the @p TX_IDLE state each time the
 * driver enters the @p UART_READY state.
 * @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];

    tx_idle [label="TX_IDLE", style="bold"];
    tx_active [label="TX_ACTIVE"];
    tx_complete [label="TX_COMPLETE"];
    tx_fatal [label="Fatal Error", style="bold"];

    tx_idle -> tx_active [label="\nuartStartSend()"];
    tx_idle -> tx_idle [label="\nuartStopSend()\n>uc_txend2<"];
    tx_active -> tx_complete [label="\nbuffer transmitted\n>uc_txend1<"];
    tx_active -> tx_idle [label="\nuartStopSend()"];
    tx_active -> tx_fatal [label="\nuartStartSend()"];
    tx_complete -> tx_active [label="\nuartStartSendI()\nthen\ncallback return"];
    tx_complete -> tx_idle [label="\ncallback return"];
  }
 * @enddot
 *
 * @subsection uart_1_2 Receiver sub State Machine
 * The follow diagram describes the receiver state machine, this diagram
 * is valid while the driver is in the @p UART_READY state. This state
 * machine is automatically reset to the @p RX_IDLE state each time the
 * driver enters the @p UART_READY state.
 * @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];

    rx_idle [label="RX_IDLE", style="bold"];
    rx_active [label="RX_ACTIVE"];
    rx_complete [label="RX_COMPLETE"];
    rx_fatal [label="Fatal Error", style="bold"];

    rx_idle -> rx_idle [label="\nuartStopReceive()\n>uc_rxchar<\n>uc_rxerr<"];
    rx_idle -> rx_active [label="\nuartStartReceive()"];

    rx_active -> rx_complete [label="\nbuffer filled\n>uc_rxend<"];
    rx_active -> rx_idle [label="\nuartStopReceive()"];
    rx_active -> rx_active [label="\nreceive error\n>uc_rxerr<"];
    rx_active -> rx_fatal [label="\nuartStartReceive()"];
    rx_complete -> rx_active [label="\nuartStartReceiveI()\nthen\ncallback return"];
    rx_complete -> rx_idle [label="\ncallback return"];
  }
 * @enddot
 *
 * @ingroup IO
 */

/**
 * @defgroup UART_LLD UART Low Level Driver
 * @brief @ref UART low level driver template.
 * @details This file is a template for a UART low level driver not an
 * actual implementation. This template is only meant as documentation of
 * a generic @ref UART_LLD entry points.
 *
 * @ingroup UART
 */