From 1ab46c6fb9e7a6f8283886b0d9de5357a08b3740 Mon Sep 17 00:00:00 2001 From: barthess Date: Sun, 27 Mar 2011 15:58:39 +0000 Subject: [PATCH] I2C. Doxy comments improvement. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/branches/i2c_dev@2846 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/include/i2c.h | 42 +++++++++++--------- os/hal/platforms/STM32/i2c_lld.c | 67 +++++++++++++++++++++++++++----- 2 files changed, 81 insertions(+), 28 deletions(-) diff --git a/os/hal/include/i2c.h b/os/hal/include/i2c.h index 3f9186125..a01606a18 100644 --- a/os/hal/include/i2c.h +++ b/os/hal/include/i2c.h @@ -79,15 +79,12 @@ typedef enum { /** * @brief I2C notification callback type. - * @details This callback invoked when byte transfer finish event generated, + * @details This callback invoked when byte transfer finish event occurs, * No matter sending or reading. This function designed - * for sending (re)start or stop events to I2C bus. - * Use "restart" boolean flag - * in I2CSlaveConfig structure for this needs. - * Each slave can (must?) have its own callback function. + * for sending (re)start or stop events to I2C bus from user level. * - * If callback function is set to NULL - driver generate stop - * condition on the bus after the transfer finish. + * If callback function is set to NULL - driver atomaticcaly + * generate stop condition after the transfer finish. * * @param[in] i2cp pointer to the @p I2CDriver object triggering the * callback @@ -115,8 +112,9 @@ typedef uint8_t i2cblock_t; /** - * @brief Structure representing an I2C slave configuration. - * @details TODO: write about befers + * @brief Structure representing an I2C slave configuration. + * @details Each slave device has its own config structure with input and + * output buffers for temporally storing data. */ struct I2CSlaveConfig{ /** @@ -135,17 +133,17 @@ struct I2CSlaveConfig{ i2cerrorcallback_t id_err_callback; /** - * @brief Pointer to input buffer. + * @brief Receive and transmit buffers. */ - i2cblock_t *rxbuf; // pointer to buffer - size_t rxdepth; // depth of buffer - size_t rxbytes; // count of bytes to sent in one transmission - size_t rxbufhead; // head pointer to current data byte + i2cblock_t *rxbuf; /*!< Pointer to receive buffer. */ + size_t rxdepth; /*!< Depth of buffer. */ + size_t rxbytes; /*!< Number of bytes to be receive in one transmission. */ + size_t rxbufhead; /*!< Pointer to current data byte. */ - i2cblock_t *txbuf; - size_t txdepth; - size_t txbytes; - size_t txbufhead; + i2cblock_t *txbuf; /*!< Pointer to transmit buffer.*/ + size_t txdepth; /*!< Depth of buffer. */ + size_t txbytes; /*!< Number of bytes to be transmit in one transmission. */ + size_t txbufhead; /*!< Pointer to current data byte. */ /** * @brief Contain slave address and some flags. @@ -161,7 +159,13 @@ struct I2CSlaveConfig{ */ uint16_t address; - bool_t restart; // send restart if TRUE. Else sent stop event after complete data tx/rx + /** + * @brief Boolean flag for dealing with start/stop conditions. + * @note This flag destined to use in callback functions. It place here + * for convenience and flexibility reasons, but you can use your + * own variable from user level code. + */ + bool_t restart; #if I2C_USE_WAIT diff --git a/os/hal/platforms/STM32/i2c_lld.c b/os/hal/platforms/STM32/i2c_lld.c index 94c3c0da3..9dc3a66bc 100644 --- a/os/hal/platforms/STM32/i2c_lld.c +++ b/os/hal/platforms/STM32/i2c_lld.c @@ -33,6 +33,12 @@ I2CDriver I2CD2; /* Driver local functions. */ /*===========================================================================*/ +/** + * @brief Interrupt service routine. + * @details This function handle all ERROR interrupt conditions. + * + * @param[in] i2cp pointer to the @p I2CDriver object + */ static void i2c_serve_error_interrupt(I2CDriver *i2cp) { //TODO: more robust error handling chSysLockFromIsr(); @@ -101,14 +107,20 @@ inline bool_t i2c_lld_rxbyte(I2CDriver *i2cp) { } -/* - * This function handle all regular interrupt conditions +/** + * @brief Interrupt service routine. + * @details This function handle all regular interrupt conditions. + * + * @param[in] i2cp pointer to the @p I2CDriver object */ static void i2c_serve_event_interrupt(I2CDriver *i2cp) { + +#if CH_DBG_ENABLE_CHECKS // debug variables int i = 0; int n = 0; int m = 0; +#endif /* In 10-bit addressing mode, – To enter Transmitter mode, a master sends the header (11110xx0) and then the @@ -165,7 +177,7 @@ static void i2c_serve_event_interrupt(I2CDriver *i2cp) { i2c_lld_txbyte(i2cp); // send first byte return; } - else { + else {// I2C is receiving data /* In order to generate the non-acknowledge pulse after the last received * data byte, the ACK bit must be cleared just after reading the second * last data byte (after second last RxNE event). @@ -197,22 +209,25 @@ static void i2c_serve_event_interrupt(I2CDriver *i2cp) { i2cp->id_i2c->CR2 &= (~I2C_CR2_ITEVTEN); // disable BTF interrupt chSysUnlockFromIsr(); /* now driver is ready to generate (re)start/stop condition. - * Callback function is good place to do that.*/ + * Callback function is good place to do that. If not callback was + * set - driver only generate stop condition. */ i2cp->id_state = I2C_READY; if (i2cp->id_slave_config->id_callback != NULL) i2cp->id_slave_config->id_callback(i2cp, i2cp->id_slave_config); - else /* If no callback function set - generate stop */ + else /* No callback function set - generate stop */ i2c_lld_master_stop(i2cp); return; } +#if CH_DBG_ENABLE_CHECKS else{ // debugging trap i = i2cp->id_i2c->SR1; n = i2cp->id_i2c->SR2; m = i2cp->id_i2c->CR1; - return; + while(TRUE); } +#endif /* CH_DBG_ENABLE_CHECKS */ } #if STM32_I2C_USE_I2C1 || defined(__DOXYGEN__) @@ -314,7 +329,11 @@ void i2c_lld_start(I2CDriver *i2cp) { i2cp->id_i2c->CR1 |= 1; // enable interface } - +/** + * @brief Set clock speed. + * + * @param[in] i2cp pointer to the @p I2CDriver object + */ void i2c_lld_set_clock(I2CDriver *i2cp) { volatile uint16_t regCCR, regCR2, freq, clock_div; volatile uint16_t pe_bit_saved; @@ -389,6 +408,11 @@ void i2c_lld_set_clock(I2CDriver *i2cp) { i2cp->id_i2c->CR1 |= pe_bit_saved; } +/** + * @brief Set operation mode of I2C hardware. + * + * @param[in] i2cp pointer to the @p I2CDriver object + */ void i2c_lld_set_opmode(I2CDriver *i2cp) { I2C_opMode_t opmode = i2cp->id_config->opMode; uint16_t regCR1; @@ -412,6 +436,11 @@ void i2c_lld_set_opmode(I2CDriver *i2cp) { i2cp->id_i2c->CR1 = regCR1; } +/** + * @brief Set own address. + * + * @param[in] i2cp pointer to the @p I2CDriver object + */ void i2c_lld_set_own_address(I2CDriver *i2cp) { //TODO: dual address mode @@ -458,7 +487,11 @@ void i2c_lld_stop(I2CDriver *i2cp) { i2cp->id_state = I2C_STOP; } - +/** + * @brief Generate start condition. + * + * @param[in] i2cp pointer to the @p I2CDriver object + */ void i2c_lld_master_start(I2CDriver *i2cp){ i2cp->id_i2c->CR1 |= I2C_CR1_START; while (i2cp->id_i2c->CR1 & I2C_CR1_START); @@ -468,12 +501,22 @@ void i2c_lld_master_start(I2CDriver *i2cp){ i2cp->id_i2c->CR2 |= I2C_CR2_ITEVTEN | I2C_CR2_ITBUFEN; } +/** + * @brief Generate stop condition. + * + * @param[in] i2cp pointer to the @p I2CDriver object + */ void i2c_lld_master_stop(I2CDriver *i2cp){ i2cp->id_i2c->CR1 |= I2C_CR1_STOP; while (i2cp->id_i2c->CR1 & I2C_CR1_STOP); } - +/** + * @brief Begin data transmitting. + * + * @param[in] i2cp pointer to the @p I2CDriver object + * @param[in] i2cscfg pointer to the @p I2CSlaveConfig object + */ void i2c_lld_master_transmit(I2CDriver *i2cp, I2CSlaveConfig *i2cscfg){ i2cp->id_slave_config = i2cscfg; @@ -483,6 +526,12 @@ void i2c_lld_master_transmit(I2CDriver *i2cp, I2CSlaveConfig *i2cscfg){ i2c_lld_master_start(i2cp); } +/** + * @brief Begin data receiving. + * + * @param[in] i2cp pointer to the @p I2CDriver object + * @param[in] i2cscfg pointer to the @p I2CSlaveConfig object + */ void i2c_lld_master_receive(I2CDriver *i2cp, I2CSlaveConfig *i2cscfg){ i2cp->id_slave_config = i2cscfg;