diff options
author | barthess <barthess@35acf78f-673a-0410-8e92-d51de3d6d3f4> | 2011-07-12 18:26:39 +0000 |
---|---|---|
committer | barthess <barthess@35acf78f-673a-0410-8e92-d51de3d6d3f4> | 2011-07-12 18:26:39 +0000 |
commit | 621d794bf0d2a6456221f1e478de66e48c293063 (patch) | |
tree | 5e1d92a9110b4b84218529b5a0d688ff8c468db7 | |
parent | 44960790c58f9055068dbc427384ae8d20048334 (diff) | |
download | ChibiOS-621d794bf0d2a6456221f1e478de66e48c293063.tar.gz ChibiOS-621d794bf0d2a6456221f1e478de66e48c293063.tar.bz2 ChibiOS-621d794bf0d2a6456221f1e478de66e48c293063.zip |
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
-rw-r--r-- | os/hal/dox/i2c.dox | 26 | ||||
-rw-r--r-- | os/hal/include/i2c.h | 19 | ||||
-rw-r--r-- | os/hal/platforms/STM32/i2c_lld.c | 2 | ||||
-rw-r--r-- | os/hal/platforms/STM32/i2c_lld.h | 40 | ||||
-rw-r--r-- | os/hal/src/i2c.c | 18 |
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,
|