From 621d794bf0d2a6456221f1e478de66e48c293063 Mon Sep 17 00:00:00 2001 From: barthess Date: Tue, 12 Jul 2011 18:26:39 +0000 Subject: [PATCH] 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 | 26 +++++++++++++++++---- os/hal/include/i2c.h | 19 ++++++--------- os/hal/platforms/STM32/i2c_lld.c | 2 +- os/hal/platforms/STM32/i2c_lld.h | 40 ++++++++++++++++---------------- 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,