I2C. Documentation improvements. Dead code clenups.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/branches/i2c_dev@3153 35acf78f-673a-0410-8e92-d51de3d6d3f4

5 files changed, 61 insertions, 44 deletions

diff --git a/os/hal/dox/i2c.dox b/os/hal/dox/i2c.dox
index 1ffd2da47..cd5e3f698 100644
--- a/os/hal/dox/i2c.dox
+++ b/os/hal/dox/i2c.dox
@@ -31,12 +31,28 @@
  * 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

- *

+ * @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];

+

+    uninit [label="I2C_UNINIT", style="bold"];

+    stop [label="I2C_STOP\nLow Power"];

+    ready [label="I2C_READY\nClock Enabled"];

+	active [label="I2C_ACTIVE\nBus Active"];

+

+    uninit -> stop [label="i2cInit()"];

+    stop ->	  stop [label="i2cStop()"];

+    stop ->   ready [label="i2cStart()"];

+    ready ->  active [label="i2cMasterTransmit()\ni2cMasterReceive()"];

+	active -> ready [label="_i2c_isr_code()"];

+    ready ->  stop [label="i2cStop()"];

+  }

+ * @enddot

  * 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

+ * the I2C bus from multiple threads then use the @p i2cAcquireBus() and

  * @p i2cReleaseBus() APIs in order to gain exclusive access.

  *

  * @ingroup IO

diff --git a/os/hal/include/i2c.h b/os/hal/include/i2c.h
index 1e7ce3e1e..19eab3b35 100644
--- a/os/hal/include/i2c.h
+++ b/os/hal/include/i2c.h
@@ -79,13 +79,12 @@
  */

 typedef enum {

   /* master part */

-  I2C_UNINIT = 0,   /**< @brief Not initialized.        */

-  I2C_STOP = 1,     /**< @brief Stopped.                */

-  I2C_READY = 2,    /**< @brief Ready.                  */

-  I2C_ACTIVE = 3,   /**< @brief In communication.          */

-  I2C_COMPLETE = 4, /**< @brief Asynchronous operation complete.   */

+  I2C_UNINIT = 0,   /**< @brief Not initialized.                    */

+  I2C_STOP = 1,     /**< @brief Stopped.                            */

+  I2C_READY = 2,    /**< @brief Ready.                              */

+  I2C_ACTIVE = 3,   /**< @brief In communication.                   */

 

-  /* slave part */

+  /* Slave part. Not realized. */

   I2C_SACTIVE = 10,

   I2C_STRANSMIT = 11,

   I2C_SRECEIVE = 12,

@@ -209,11 +208,9 @@ struct I2CSlaveConfig{
  * @notapi

  */

 #define _i2c_isr_code(i2cp, i2cscfg) {                                 \

-  (i2cp)->id_state = I2C_COMPLETE;                                     \

   if(((i2cp)->id_slave_config)->id_callback) {                         \

     ((i2cp)->id_slave_config)->id_callback(i2cp, i2cscfg);             \

-    if((i2cp)->id_state == I2C_COMPLETE)                               \

-      (i2cp)->id_state = I2C_READY;                                    \

+    (i2cp)->id_state = I2C_READY;                                      \

   }                                                                    \

   else                                                                 \

     (i2cp)->id_state = I2C_READY;                                      \

@@ -235,11 +232,9 @@ struct I2CSlaveConfig{
  * @notapi

  */

 #define _i2c_isr_err_code(i2cp, i2cscfg) {                             \

-  (i2cp)->id_state = I2C_COMPLETE;                                     \

   if(((i2cp)->id_slave_config)->id_err_callback) {                     \

     ((i2cp)->id_slave_config)->id_err_callback(i2cp, i2cscfg);         \

-    if((i2cp)->id_state == I2C_COMPLETE)                               \

-      (i2cp)->id_state = I2C_READY;                                    \

+    (i2cp)->id_state = I2C_READY;                                      \

   }                                                                    \

   else                                                                 \

     (i2cp)->id_state = I2C_READY;                                      \

diff --git a/os/hal/platforms/STM32/i2c_lld.c b/os/hal/platforms/STM32/i2c_lld.c
index 84959c7f0..1b36fde8f 100644
--- a/os/hal/platforms/STM32/i2c_lld.c
+++ b/os/hal/platforms/STM32/i2c_lld.c
@@ -1,7 +1,7 @@
 /**
  * @file STM32/i2c_lld.c
  * @brief STM32 I2C subsystem low level driver source. Slave mode not implemented.
- * @addtogroup STM32_I2C
+ * @addtogroup I2C
  * @{
  */
 
diff --git a/os/hal/platforms/STM32/i2c_lld.h b/os/hal/platforms/STM32/i2c_lld.h
index b41f8f6fa..c91e3103a 100644
--- a/os/hal/platforms/STM32/i2c_lld.h
+++ b/os/hal/platforms/STM32/i2c_lld.h
@@ -1,7 +1,7 @@
 /**
  * @file STM32/i2c_lld.h
  * @brief STM32 I2C subsystem low level driver header.
- * @addtogroup STM32_I2C
+ * @addtogroup I2C
  * @{
  */
 
@@ -111,13 +111,13 @@ typedef enum {
  * @brief Driver configuration structure.
  */
 typedef struct {
-  i2copmode_t     op_mode;       /*!< Specifies the I2C mode.*/
-  uint32_t        clock_speed;   /*!< Specifies the clock frequency. Must be set to a value lower than 400kHz */
-  i2cdutycycle_t  duty_cycle;    /*!< Specifies the I2C fast mode duty cycle */
-  uint8_t         own_addr_7;    /*!< Specifies the first device 7-bit own address. */
-  uint16_t        own_addr_10;   /*!< Specifies the second part of device own address in 10-bit mode. Set to NULL if not used. */
-  uint16_t        ack;           /*!< Enables or disables the acknowledgement. */
-  uint8_t         nbit_own_addr; /*!< Specifies if 7-bit or 10-bit address is acknowledged */
+  i2copmode_t     op_mode;       /**< @brief Specifies the I2C mode.*/
+  uint32_t        clock_speed;   /**< @brief Specifies the clock frequency. Must be set to a value lower than 400kHz */
+  i2cdutycycle_t  duty_cycle;    /**< @brief Specifies the I2C fast mode duty cycle */
+  uint8_t         own_addr_7;    /**< @brief Specifies the first device 7-bit own address. */
+  uint16_t        own_addr_10;   /**< @brief Specifies the second part of device own address in 10-bit mode. Set to NULL if not used. */
+  uint16_t        ack;           /**< @brief Enables or disables the acknowledgment. */
+  uint8_t         nbit_own_addr; /**< @brief Specifies if 7-bit or 10-bit address is acknowledged */
 } I2CConfig;
 
 
@@ -164,21 +164,21 @@ struct I2CDriver{
    */
   const I2CSlaveConfig  *id_slave_config;
 
-  __IO size_t           txbytes;    /*!< Number of bytes to be transmitted. */
-  __IO size_t           rxbytes;    /*!< Number of bytes to be received. */
-  uint8_t               *rxbuf;     /*!< Pointer to receive buffer. */
-  uint8_t               *txbuf;     /*!< Pointer to transmit buffer.*/
-  uint8_t               *rxbuff_p;  /*!< Pointer to the current byte in slave rx buffer. */
-  uint8_t               *txbuff_p;  /*!< Pointer to the current byte in slave tx buffer. */
+  __IO size_t           txbytes;    /*!< @brief Number of bytes to be transmitted. */
+  __IO size_t           rxbytes;    /*!< @brief Number of bytes to be received. */
+  uint8_t               *rxbuf;     /*!< @brief Pointer to receive buffer. */
+  uint8_t               *txbuf;     /*!< @brief Pointer to transmit buffer.*/
+  uint8_t               *rxbuff_p;  /*!< @brief Pointer to the current byte in slave rx buffer. */
+  uint8_t               *txbuff_p;  /*!< @brief Pointer to the current byte in slave tx buffer. */
 
-  __IO i2cflags_t       errors;     /*!< Error flags.*/
-  __IO i2cflags_t       flags;      /*!< State flags.*/
+  __IO i2cflags_t       errors;     /*!< @brief Error flags.*/
+  __IO i2cflags_t       flags;      /*!< @brief State flags.*/
 
-  uint16_t              slave_addr; /*!< Current slave address. */
-  uint8_t               slave_addr1;/*!< 7-bit address of the slave with r\w bit.*/
-  uint8_t               slave_addr2;/*!< Used in 10-bit address mode. */
+  uint16_t              slave_addr; /*!< @brief Current slave address. */
+  uint8_t               slave_addr1;/*!< @brief 7-bit address of the slave with r\w bit.*/
+  uint8_t               slave_addr2;/*!< @brief Used in 10-bit address mode. */
 
-  EventSource           sevent;     /*!< Status Change @p EventSource.*/
+  EventSource           sevent;     /*!< @brief Status Change @p EventSource.*/
 
   /*********** End of the mandatory fields. **********************************/
 
diff --git a/os/hal/src/i2c.c b/os/hal/src/i2c.c
index cd12d42eb..b169fb70d 100644
--- a/os/hal/src/i2c.c
+++ b/os/hal/src/i2c.c
@@ -135,18 +135,23 @@ void i2cStop(I2CDriver *i2cp) {
 }

 

 /**

- * @brief Sends data ever the I2C bus.

+ * @brief Sends data via the I2C bus.

+ *

+ * @details Function designed to realize "read-through-write" transfer

+ *          paradigm. If you want transmit data without any further read,

+ *          than set @b rxbuf field to 0.

  *

  * @param[in] i2cp        pointer to the @p I2CDriver object

  * @param[in] i2cscfg     pointer to the @p I2C slave config

  * @param[in] slave_addr  Slave device address. Bits 0-9 contain slave

  *                        device address. Bit 15 must be set to 1 if 10-bit

- *                        addressing modes used. Otherwise	keep it cleared.

+ *                        addressing mode used. Otherwise	keep it cleared.

  *                        Bits 10-14 unused.

- * @param[in] txbytes     number of bytes to be transmitted

  * @param[in] txbuf       pointer to transmit buffer

- * @param[in] rxbytes     number of bytes to be received

+ * @param[in] txbytes     number of bytes to be transmitted

  * @param[in] rxbuf       pointer to receive buffer

+ * @param[in] rxbytes     number of bytes to be received, set it to 0 if

+ *                        you want transmit only

  */

 void i2cMasterTransmit(I2CDriver *i2cp,

                       const I2CSlaveConfig *i2cscfg,

@@ -183,9 +188,10 @@ void i2cMasterTransmit(I2CDriver *i2cp,
  * @param[in] i2cscfg     pointer to the @p I2C slave config

  * @param[in] slave_addr  Slave device address. Bits 0-9 contain slave

  *                        device address. Bit 15 must be set to 1 if 10-bit

- *                        addressing modes used. Otherwise	keep it cleared.

+ *                        addressing mode used. Otherwise	keep it cleared.

  *                        Bits 10-14 unused.

- * @param[in] txbytes     number of bytes to be transmited

+ * @param[in] rxbytes     number of bytes to be received

+ * @param[in] rxbuf       pointer to receive buffer

  */

 void i2cMasterReceive(I2CDriver *i2cp,

                       const I2CSlaveConfig *i2cscfg,