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

3 files changed, 57 insertions, 28 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 {