aboutsummaryrefslogtreecommitdiffstats
path: root/os/hal
diff options
context:
space:
mode:
authorbarthess <barthess@35acf78f-673a-0410-8e92-d51de3d6d3f4>2011-07-12 18:26:39 +0000
committerbarthess <barthess@35acf78f-673a-0410-8e92-d51de3d6d3f4>2011-07-12 18:26:39 +0000
commit621d794bf0d2a6456221f1e478de66e48c293063 (patch)
tree5e1d92a9110b4b84218529b5a0d688ff8c468db7 /os/hal
parent44960790c58f9055068dbc427384ae8d20048334 (diff)
downloadChibiOS-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
Diffstat (limited to 'os/hal')
-rw-r--r--os/hal/dox/i2c.dox26
-rw-r--r--os/hal/include/i2c.h19
-rw-r--r--os/hal/platforms/STM32/i2c_lld.c2
-rw-r--r--os/hal/platforms/STM32/i2c_lld.h40
-rw-r--r--os/hal/src/i2c.c18
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,