zcy
/
tinySA
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
tinySA/os/io/io.dox

318 lines
12 KiB
Plaintext
Raw Blame History

/*
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 SPI.
* - @ref ADC.
* - @ref MAC.
* - @ref MII.
* - @ref MMC_SPI.
* .
*/
/**
* @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 -> 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.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
*/
/**
* @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
*/
Reference in New Issue View Git Blame Copy Permalink