From 54c975bed0b0fbfbf6fdd1a5024c258150c4c5dc Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 6 Jan 2012 19:05:13 +0000 Subject: I2C driver state diagram modified, documentation improvements. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@3751 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/dox/i2c.dox | 73 +++++++++++++++++++++++++++++++++++++--------------- os/hal/dox/rtc.dox | 8 ++---- os/hal/dox/spi.dox | 4 ++- os/hal/include/i2c.h | 5 ++-- os/hal/src/i2c.c | 20 +++++++++----- 5 files changed, 74 insertions(+), 36 deletions(-) diff --git a/os/hal/dox/i2c.dox b/os/hal/dox/i2c.dox index 83dcfe285..502df8721 100644 --- a/os/hal/dox/i2c.dox +++ b/os/hal/dox/i2c.dox @@ -22,16 +22,7 @@ * @defgroup I2C I2C Driver * @brief Generic I2C Driver. * @details This module implements a generic I2C (Inter-Integrated Circuit) - * driver. On STM32 platform you can choose method of waiting START - * and STOP bits: polling wait or wait using GPT. GPT method use - * one timer per I2C interface, on the other hand -- polling is - * block function that starts transfer. - * @note If you decide to use polling wait -- do NOT start transmit or - * receive from callback because it run in ISR context. - * @note You must set I2C interrupts priority to highest level in the - * system. - * @note If you use GPT than set GPT interrupts priority level over I2C - * interrupts priority level. + * driver. * @pre In order to use the I2C driver the @p HAL_USE_I2C option * must be enabled in @p halconf.h. * @@ -40,29 +31,69 @@ * 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="false", + + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; edge [fontname=Helvetica, fontsize=8]; + stop [label="I2C_STOP\nLow Power"]; uninit [label="I2C_UNINIT", style="bold"]; + ready [label="I2C_READY\nClock Enabled"]; + active_tx [label="I2C_ACTIVE_TX\nBus TX Active"]; + active_rx [label="I2C_ACTIVE_RX\nBus RX Active"]; + locked [label="I2C_LOCKED\nBus Locked"]; + + uninit -> stop [label="i2cInit()", constraint=false]; + stop -> stop [label="i2cStop()"]; + stop -> ready [label="i2cStart()"]; + ready -> ready [label="i2cStart()"]; + ready -> stop [label="i2cStop()"]; + ready -> active_tx [label="i2cMasterTransmit()"]; + ready -> active_rx [label="i2cMasterReceive()"]; + active_tx -> ready [label="completed"]; + active_rx -> ready [label="completed"]; + active_tx -> locked [label="RDY_TIMEOUT"]; + active_rx -> locked [label="RDY_TIMEOUT"]; + locked -> stop [label="i2cStop()"]; + locked -> ready [label="i2cStart()"]; + } + * @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="I2C_STOP\nLow Power"]; + uninit [label="I2C_UNINIT", style="bold"]; ready [label="I2C_READY\nClock Enabled"]; - active_tx [label="I2C_ACTIVE_TRANSMIT\nBus TX Active"]; - active_rx [label="I2C_ACTIVE_RECEIVE\nBus RX Active"]; + active_tx [label="I2C_ACTIVE_TX\nBus TX Active"]; + active_rx [label="I2C_ACTIVE_RX\nBus RX Active"]; + locked [label="I2C_LOCKED\nBus Locked"]; - uninit -> stop [label="i2cInit()"]; - stop -> stop [label="i2cStop()"]; - stop -> ready [label="i2cStart()"]; - ready -> active_tx [label="i2cMasterTransmit()"]; - ready -> active_rx [label="i2cMasterReceive()"]; - active_tx -> ready [label="_i2c_isr_code()"]; - active_rx -> ready [label="_i2c_isr_code()"]; - ready -> stop [label="i2cStop()"]; + uninit -> stop [label="i2cInit()", constraint=false]; + stop -> stop [label="i2cStop()"]; + stop -> ready [label="i2cStart()"]; + ready -> ready [label="i2cStart()"]; + ready -> stop [label="i2cStop()"]; + ready -> active_tx [label="i2cMasterTransmit()"]; + ready -> active_rx [label="i2cMasterReceive()"]; + active_tx -> ready [label="completed"]; + active_rx -> ready [label="completed"]; + active_tx -> locked [label="RDY_TIMEOUT"]; + active_rx -> locked [label="RDY_TIMEOUT"]; + locked -> stop [label="i2cStop()"]; + locked -> ready [label="i2cStart()"]; } * @enddot + * @endif * The driver is not thread safe for performance reasons, if you need to access * the I2C bus from multiple threads then use the @p i2cAcquireBus() and * @p i2cReleaseBus() APIs in order to gain exclusive access. diff --git a/os/hal/dox/rtc.dox b/os/hal/dox/rtc.dox index b538f3a4a..c2121a314 100644 --- a/os/hal/dox/rtc.dox +++ b/os/hal/dox/rtc.dox @@ -21,12 +21,8 @@ /** * @defgroup RTC RTC Driver * @brief Real Time Clock Abstraction Layer - * @details This module defines an abstract interface for Real Time Clock cell. - * If you do not need callback functionality than disable - * @p RTC_SUPPORTS_CALLBACKS option in @p halconf.h. - * In @p halconf.h you also can select clock source for RTC in - * @p RTC_CLOCK_SOURCE option. - * + * @details This module defines an abstract interface for a Real Time Clock + * Peripheral. * @pre In order to use the RTC driver the @p HAL_USE_RTC option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/spi.dox b/os/hal/dox/spi.dox index 047ff646e..30bb0244a 100644 --- a/os/hal/dox/spi.dox +++ b/os/hal/dox/spi.dox @@ -37,7 +37,8 @@ digraph example { size="5, 7"; rankdir="LR"; - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + 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"]; @@ -57,6 +58,7 @@ complete -> active [label="\nspiStartXXXI() (async)\nthen\ncallback return"]; complete -> ready [label="\ncallback return"]; } + * @enddot * @else * @dot digraph example { diff --git a/os/hal/include/i2c.h b/os/hal/include/i2c.h index ac11718bc..88b2a73c8 100644 --- a/os/hal/include/i2c.h +++ b/os/hal/include/i2c.h @@ -89,8 +89,9 @@ typedef enum { I2C_UNINIT = 0, /**< Not initialized. */ I2C_STOP = 1, /**< Stopped. */ I2C_READY = 2, /**< Ready. */ - I2C_ACTIVE_TRANSMIT = 3, /**< Transmitting. */ - I2C_ACTIVE_RECEIVE = 4, /**< Receiving. */ + I2C_ACTIVE_TX = 3, /**< Transmitting. */ + I2C_ACTIVE_RX = 4, /**< Receiving. */ + I2C_LOCKED = 5 /**> Bus or driver locked. */ } i2cstate_t; #include "i2c_lld.h" diff --git a/os/hal/src/i2c.c b/os/hal/src/i2c.c index ea0df6589..fcccd6a87 100644 --- a/os/hal/src/i2c.c +++ b/os/hal/src/i2c.c @@ -101,7 +101,8 @@ void i2cObjectInit(I2CDriver *i2cp) { void i2cStart(I2CDriver *i2cp, const I2CConfig *config) { chDbgCheck((i2cp != NULL) && (config != NULL), "i2cStart"); - chDbgAssert((i2cp->state == I2C_STOP) || (i2cp->state == I2C_READY), + chDbgAssert((i2cp->state == I2C_STOP) || (i2cp->state == I2C_READY) || + (i2cp->state == I2C_LOCKED), "i2cStart(), #1", "invalid state"); @@ -122,7 +123,8 @@ void i2cStart(I2CDriver *i2cp, const I2CConfig *config) { void i2cStop(I2CDriver *i2cp) { chDbgCheck(i2cp != NULL, "i2cStop"); - chDbgAssert((i2cp->state == I2C_STOP) || (i2cp->state == I2C_READY), + chDbgAssert((i2cp->state == I2C_STOP) || (i2cp->state == I2C_READY) || + (i2cp->state == I2C_LOCKED), "i2cStop(), #1", "invalid state"); @@ -193,10 +195,13 @@ msg_t i2cMasterTransmitTimeout(I2CDriver *i2cp, chSysLock(); i2cp->errors = I2CD_NO_ERROR; - i2cp->state = I2C_ACTIVE_TRANSMIT; + i2cp->state = I2C_ACTIVE_TX; rdymsg = i2c_lld_master_transmit_timeout(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes, timeout); - i2cp->state = I2C_READY; + if (rdymsg == RDY_TIMEOUT) + i2cp->state = I2C_LOCKED; + else + i2cp->state = I2C_READY; chSysUnlock(); return rdymsg; } @@ -239,9 +244,12 @@ msg_t i2cMasterReceiveTimeout(I2CDriver *i2cp, chSysLock(); i2cp->errors = I2CD_NO_ERROR; - i2cp->state = I2C_ACTIVE_RECEIVE; + i2cp->state = I2C_ACTIVE_RX; rdymsg = i2c_lld_master_receive_timeout(i2cp, addr, rxbuf, rxbytes, timeout); - i2cp->state = I2C_READY; + if (rdymsg == RDY_TIMEOUT) + i2cp->state = I2C_LOCKED; + else + i2cp->state = I2C_READY; chSysUnlock(); return rdymsg; } -- cgit v1.2.3