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

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
+ * @dot
- * @else
+  digraph example {
- * @endif
+    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

os/hal/include/i2c.h

@@ -79,13 +79,12 @@
  */
 typedef enum {
   /* master part */
-  I2C_UNINIT = 0,   /**< @brief Not initialized.        */
+  I2C_UNINIT = 0,   /**< @brief Not initialized.                    */
-  I2C_STOP = 1,     /**< @brief Stopped.                */
+  I2C_STOP = 1,     /**< @brief Stopped.                            */
-  I2C_READY = 2,    /**< @brief Ready.                  */
+  I2C_READY = 2,    /**< @brief Ready.                              */
-  I2C_ACTIVE = 3,   /**< @brief In communication.          */
+  I2C_ACTIVE = 3,   /**< @brief In communication.                   */
-  I2C_COMPLETE = 4, /**< @brief Asynchronous operation complete.   */
 
-  /* 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;                                      \

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
  * @{
  */
 

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.*/
+  i2copmode_t     op_mode;       /**< @brief Specifies the I2C mode.*/
-  uint32_t        clock_speed;   /*!< Specifies the clock frequency. Must be set to a value lower than 400kHz */
+  uint32_t        clock_speed;   /**< @brief Specifies the clock frequency. Must be set to a value lower than 400kHz */
-  i2cdutycycle_t  duty_cycle;    /*!< Specifies the I2C fast mode duty cycle */
+  i2cdutycycle_t  duty_cycle;    /**< @brief Specifies the I2C fast mode duty cycle */
-  uint8_t         own_addr_7;    /*!< Specifies the first device 7-bit own address. */
+  uint8_t         own_addr_7;    /**< @brief 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        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;           /*!< Enables or disables the acknowledgement. */
+  uint16_t        ack;           /**< @brief Enables or disables the acknowledgment. */
-  uint8_t         nbit_own_addr; /*!< Specifies if 7-bit or 10-bit address is acknowledged */
+  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           txbytes;    /*!< @brief Number of bytes to be transmitted. */
-  __IO size_t           rxbytes;    /*!< Number of bytes to be received. */
+  __IO size_t           rxbytes;    /*!< @brief Number of bytes to be received. */
-  uint8_t               *rxbuf;     /*!< Pointer to receive buffer. */
+  uint8_t               *rxbuf;     /*!< @brief Pointer to receive buffer. */
-  uint8_t               *txbuf;     /*!< Pointer to transmit buffer.*/
+  uint8_t               *txbuf;     /*!< @brief Pointer to transmit buffer.*/
-  uint8_t               *rxbuff_p;  /*!< Pointer to the current byte in slave rx buffer. */
+  uint8_t               *rxbuff_p;  /*!< @brief Pointer to the current byte in slave rx buffer. */
-  uint8_t               *txbuff_p;  /*!< Pointer to the current byte in slave tx buffer. */
+  uint8_t               *txbuff_p;  /*!< @brief Pointer to the current byte in slave tx buffer. */
 
-  __IO i2cflags_t       errors;     /*!< Error flags.*/
+  __IO i2cflags_t       errors;     /*!< @brief Error flags.*/
-  __IO i2cflags_t       flags;      /*!< State flags.*/
+  __IO i2cflags_t       flags;      /*!< @brief State flags.*/
 
-  uint16_t              slave_addr; /*!< Current slave address. */
+  uint16_t              slave_addr; /*!< @brief Current slave address. */
-  uint8_t               slave_addr1;/*!< 7-bit address of the slave with r\w bit.*/
+  uint8_t               slave_addr1;/*!< @brief 7-bit address of the slave with r\w bit.*/
-  uint8_t               slave_addr2;/*!< Used in 10-bit address mode. */
+  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. **********************************/
 

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,