tinySA/os/io/io.dox

/*
    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 I/O
 * @brief I/O related services.
 * @details This section contains the I/O related services.
 *
 * The I/O subsystem is a collection of device driver portable interfaces and
 * platform dependent implementations.<br>
 * Under ChibiOS/RT a device driver is 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.
 *   .
 * .
 * <h2>Available Device Drivers</h2>
 * The I/O subsystem currently includes support for:
 * - @ref PAL.
 * - @ref SERIAL.
 * - @ref MAC
 * .
 */

/**
 * @defgroup PAL Ports Abstraction Layer (PAL)
 * @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 -> 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="spiExchange()\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.75", height="0.75"];
      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\nConverting"];
      uninit -> stop [label="adcObjectInit()"];
      stop -> ready [label="adcStart()"];
      ready -> ready [label="adcStart()"];
      ready -> stop [label="adcStop()"];
      stop -> stop [label="adcStop()"];
      ready -> running [label="adcStartConversion()"];
      running -> ready [label="adcStopConversion()"];
      running -> ready [label="End of Conversion"];
  }
 * @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 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
 */