STM8S/A Standard Peripherals Drivers: stm8s_i2c.h Source File

STM8S/A

stm8s_i2c.h
Go to the documentation of this file.
00001 /**
00002   ******************************************************************************
00003   * @file    stm8s_i2c.h
00004   * @author  MCD Application Team
00005   * @version V2.3.0
00006   * @date    16-June-2017
00007   * @brief  This file contains all functions prototype and macros for the I2C peripheral.
00008    ******************************************************************************
00009   * @attention
00010   *
00011   * <h2><center>&copy; COPYRIGHT 2014 STMicroelectronics</center></h2>
00012   *
00013   * Licensed under MCD-ST Liberty SW License Agreement V2, (the "License");
00014   * You may not use this file except in compliance with the License.
00015   * You may obtain a copy of the License at:
00016   *
00017   *        http://www.st.com/software_license_agreement_liberty_v2
00018   *
00019   * Unless required by applicable law or agreed to in writing, software 
00020   * distributed under the License is distributed on an "AS IS" BASIS, 
00021   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00022   * See the License for the specific language governing permissions and
00023   * limitations under the License.
00024   *
00025   ******************************************************************************
00026   */
00027 
00028 /* Define to prevent recursive inclusion -------------------------------------*/
00029 #ifndef __STM8S_I2C_H
00030 #define __STM8S_I2C_H
00031 
00032 /* Includes ------------------------------------------------------------------*/
00033 #include "stm8s.h"
00034 
00035 /* Exported types ------------------------------------------------------------*/
00036 
00037 /** @addtogroup I2C_Exported_Types
00038   * @{
00039   */
00040 
00041 /**
00042   * @brief  I2C duty cycle (fast mode only)
00043   */
00044 typedef enum
00045 {
00046   I2C_DUTYCYCLE_2    = (uint8_t)0x00,  /*!< Fast mode Tlow/THigh = 2 */
00047   I2C_DUTYCYCLE_16_9 = (uint8_t)0x40   /*!< Fast mode Tlow/Thigh = 16/9 */
00048 } I2C_DutyCycle_TypeDef;
00049 
00050 /**
00051   * @brief  I2C Acknowledgement configuration
00052   */
00053 typedef enum
00054 {
00055   I2C_ACK_NONE = (uint8_t)0x00,  /*!< No acknowledge */
00056   I2C_ACK_CURR = (uint8_t)0x01,  /*!< Acknowledge on the current byte */
00057   I2C_ACK_NEXT = (uint8_t)0x02   /*!< Acknowledge on the next byte */
00058 } I2C_Ack_TypeDef;
00059 
00060 /**
00061   * @brief  I2C Addressing Mode (slave mode only)
00062   */
00063 typedef enum
00064 {
00065   I2C_ADDMODE_7BIT  = (uint8_t)0x00,  /*!< 7-bit slave address (10-bit address not acknowledged) */
00066   I2C_ADDMODE_10BIT = (uint8_t)0x80   /*!< 10-bit slave address (7-bit address not acknowledged) */
00067 } I2C_AddMode_TypeDef;
00068 
00069 /**
00070   * @brief  I2C Interrupt sources
00071   * Warning: the values correspond to the bit position in the ITR register
00072   */
00073 typedef enum
00074 {
00075     I2C_IT_ERR     = (uint8_t)0x01,     /*!< Error Interruption */
00076     I2C_IT_EVT     = (uint8_t)0x02,     /*!< Event Interruption */
00077     I2C_IT_BUF     = (uint8_t)0x04      /*!< Buffer Interruption */
00078 } I2C_IT_TypeDef;
00079 
00080 /**
00081   * @brief  I2C transfer direction
00082   * Warning: the values correspond to the ADD0 bit position in the OARL register
00083   */
00084 typedef enum
00085 {
00086   I2C_DIRECTION_TX = (uint8_t)0x00,  /*!< Transmission direction */
00087   I2C_DIRECTION_RX = (uint8_t)0x01   /*!< Reception direction */
00088 } I2C_Direction_TypeDef;
00089 
00090 /**
00091   * @brief  I2C Flags
00092   * @brief Elements values convention: 0xXXYY
00093   *  X = SRx registers index
00094   *      X = 1 : SR1
00095   *      X = 2 : SR2
00096   *      X = 3 : SR3
00097   *  Y = Flag mask in the register
00098   */
00099 
00100 typedef enum
00101 {
00102   /* SR1 register flags */
00103   I2C_FLAG_TXEMPTY             = (uint16_t)0x0180,  /*!< Transmit Data Register Empty flag */
00104   I2C_FLAG_RXNOTEMPTY          = (uint16_t)0x0140,  /*!< Read Data Register Not Empty flag */
00105   I2C_FLAG_STOPDETECTION       = (uint16_t)0x0110,  /*!< Stop detected flag */
00106   I2C_FLAG_HEADERSENT          = (uint16_t)0x0108,  /*!< 10-bit Header sent flag */
00107   I2C_FLAG_TRANSFERFINISHED    = (uint16_t)0x0104,  /*!< Data Byte Transfer Finished flag */
00108   I2C_FLAG_ADDRESSSENTMATCHED  = (uint16_t)0x0102,  /*!< Address Sent/Matched (master/slave) flag */
00109   I2C_FLAG_STARTDETECTION      = (uint16_t)0x0101,  /*!< Start bit sent flag */
00110 
00111   /* SR2 register flags */
00112   I2C_FLAG_WAKEUPFROMHALT      = (uint16_t)0x0220,  /*!< Wake Up From Halt Flag */
00113   I2C_FLAG_OVERRUNUNDERRUN     = (uint16_t)0x0208,  /*!< Overrun/Underrun flag */
00114   I2C_FLAG_ACKNOWLEDGEFAILURE  = (uint16_t)0x0204,  /*!< Acknowledge Failure Flag */
00115   I2C_FLAG_ARBITRATIONLOSS     = (uint16_t)0x0202,  /*!< Arbitration Loss Flag */
00116   I2C_FLAG_BUSERROR            = (uint16_t)0x0201,  /*!< Misplaced Start or Stop condition */
00117 
00118   /* SR3 register flags */
00119   I2C_FLAG_GENERALCALL         = (uint16_t)0x0310,  /*!< General Call header received Flag */
00120   I2C_FLAG_TRANSMITTERRECEIVER = (uint16_t)0x0304,  /*!< Transmitter Receiver Flag */
00121   I2C_FLAG_BUSBUSY             = (uint16_t)0x0302,  /*!< Bus Busy Flag */
00122   I2C_FLAG_MASTERSLAVE         = (uint16_t)0x0301   /*!< Master Slave Flag */
00123 } I2C_Flag_TypeDef;
00124 
00125 /**
00126   * @brief I2C Pending bits
00127   * Elements values convention: 0xXYZZ
00128   *  X = SRx registers index
00129   *      X = 1 : SR1
00130   *      X = 2 : SR2
00131   *  Y = Position of the corresponding Interrupt
00132   *  ZZ = flag mask in the dedicated register(X register)
00133   */
00134 
00135 typedef enum
00136 {
00137     /* SR1 register flags */
00138     I2C_ITPENDINGBIT_TXEMPTY             = (uint16_t)0x1680,    /*!< Transmit Data Register Empty  */
00139     I2C_ITPENDINGBIT_RXNOTEMPTY          = (uint16_t)0x1640,    /*!< Read Data Register Not Empty  */
00140     I2C_ITPENDINGBIT_STOPDETECTION       = (uint16_t)0x1210,    /*!< Stop detected  */
00141     I2C_ITPENDINGBIT_HEADERSENT          = (uint16_t)0x1208,    /*!< 10-bit Header sent */
00142     I2C_ITPENDINGBIT_TRANSFERFINISHED    = (uint16_t)0x1204,    /*!< Data Byte Transfer Finished  */
00143     I2C_ITPENDINGBIT_ADDRESSSENTMATCHED  = (uint16_t)0x1202,    /*!< Address Sent/Matched (master/slave)  */
00144     I2C_ITPENDINGBIT_STARTDETECTION      = (uint16_t)0x1201,    /*!< Start bit sent  */
00145 
00146     /* SR2 register flags */
00147     I2C_ITPENDINGBIT_WAKEUPFROMHALT      = (uint16_t)0x2220,    /*!< Wake Up From Halt  */
00148     I2C_ITPENDINGBIT_OVERRUNUNDERRUN     = (uint16_t)0x2108,    /*!< Overrun/Underrun  */
00149     I2C_ITPENDINGBIT_ACKNOWLEDGEFAILURE  = (uint16_t)0x2104,    /*!< Acknowledge Failure  */
00150     I2C_ITPENDINGBIT_ARBITRATIONLOSS     = (uint16_t)0x2102,    /*!< Arbitration Loss  */
00151     I2C_ITPENDINGBIT_BUSERROR            = (uint16_t)0x2101     /*!< Misplaced Start or Stop condition */
00152 } I2C_ITPendingBit_TypeDef;
00153 
00154 /**
00155   * @brief I2C possible events
00156   * Values convention: 0xXXYY
00157   * XX = Event SR3 corresponding value
00158   * YY = Event SR1 corresponding value
00159   * @note if Event = EV3_2 the rule above does not apply
00160   * YY = Event SR2 corresponding value
00161   */
00162 
00163 typedef enum
00164 {
00165   /*========================================
00166 
00167                        I2C Master Events (Events grouped in order of communication)
00168                                                           ==========================================*/
00169   /**
00170     * @brief  Communication start
00171     *
00172     * After sending the START condition (I2C_GenerateSTART() function) the master
00173     * has to wait for this event. It means that the Start condition has been correctly
00174     * released on the I2C bus (the bus is free, no other devices is communicating).
00175     *
00176     */
00177   /* --EV5 */
00178   I2C_EVENT_MASTER_MODE_SELECT               = (uint16_t)0x0301,  /*!< BUSY, MSL and SB flag */
00179 
00180   /**
00181     * @brief  Address Acknowledge
00182     *
00183     * After checking on EV5 (start condition correctly released on the bus), the
00184     * master sends the address of the slave(s) with which it will communicate
00185     * (I2C_Send7bitAddress() function, it also determines the direction of the communication:
00186     * Master transmitter or Receiver).
00187     * Then the master has to wait that a slave acknowledges his address.
00188     * If an acknowledge is sent on the bus, one of the following events will
00189     * be set:
00190     *
00191     *  1) In case of Master Receiver (7-bit addressing):
00192     *  the I2C_EVENT_MASTER_RECEIVER_MODE_SELECTED event is set.
00193     *
00194     *  2) In case of Master Transmitter (7-bit addressing):
00195     *  the I2C_EVENT_MASTER_TRANSMITTER_MODE_SELECTED is set
00196     *
00197     *  3) In case of 10-Bit addressing mode, the master (just after generating the START
00198     *  and checking on EV5) has to send the header of 10-bit addressing mode (I2C_SendData()
00199     *  function).
00200     *  Then master should wait on EV9. It means that the 10-bit addressing
00201     *  header has been correctly sent on the bus.
00202     *  Then master should send the second part of the 10-bit address (LSB) using
00203     *  the function I2C_Send7bitAddress(). Then master should wait for event EV6.
00204     *
00205     */
00206   /* --EV6 */
00207   I2C_EVENT_MASTER_TRANSMITTER_MODE_SELECTED = (uint16_t)0x0782,  /*!< BUSY, MSL, ADDR, TXE and TRA flags */
00208   I2C_EVENT_MASTER_RECEIVER_MODE_SELECTED    = (uint16_t)0x0302,  /*!< BUSY, MSL and ADDR flags */
00209   /* --EV9 */
00210   I2C_EVENT_MASTER_MODE_ADDRESS10            = (uint16_t)0x0308,  /*!< BUSY, MSL and ADD10 flags */
00211 
00212   /**
00213     * @brief Communication events
00214     *
00215     * If a communication is established (START condition generated and slave address
00216     * acknowledged) then the master has to check on one of the following events for
00217     * communication procedures:
00218     *
00219     * 1) Master Receiver mode: The master has to wait on the event EV7 then to read
00220     *    the data received from the slave (I2C_ReceiveData() function).
00221     *
00222     * 2) Master Transmitter mode: The master has to send data (I2C_SendData()
00223     *    function) then to wait on event EV8 or EV8_2.
00224     *    These two events are similar:
00225     *     - EV8 means that the data has been written in the data register and is
00226     *       being shifted out.
00227     *     - EV8_2 means that the data has been physically shifted out and output
00228     *       on the bus.
00229     *     In most cases, using EV8 is sufficient for the application.
00230     *     Using EV8_2 leads to a slower communication but ensures more reliable test.
00231     *     EV8_2 is also more suitable than EV8 for testing on the last data transmission
00232     *     (before Stop condition generation).
00233     *
00234     *  @note In case the user software does not guarantee that this event EV7 is
00235     *  managed before the current byte end of transfer, then user may check on EV7
00236     *  and BTF flag at the same time (ie. (I2C_EVENT_MASTER_BYTE_RECEIVED | I2C_FLAG_BTF)).
00237     *  In this case the communication may be slower.
00238     *
00239     */
00240   /* Master RECEIVER mode -----------------------------*/
00241   /* --EV7 */
00242   I2C_EVENT_MASTER_BYTE_RECEIVED             = (uint16_t)0x0340,  /*!< BUSY, MSL and RXNE flags */
00243 
00244   /* Master TRANSMITTER mode --------------------------*/
00245   /* --EV8 */
00246   I2C_EVENT_MASTER_BYTE_TRANSMITTING         = (uint16_t)0x0780,  /*!< TRA, BUSY, MSL, TXE flags */
00247   /* --EV8_2 */
00248 
00249   I2C_EVENT_MASTER_BYTE_TRANSMITTED          = (uint16_t)0x0784,  /*!< EV8_2: TRA, BUSY, MSL, TXE and BTF flags */
00250 
00251 
00252   /*========================================
00253 
00254                        I2C Slave Events (Events grouped in order of communication)
00255                                                           ==========================================*/
00256 
00257   /**
00258     * @brief  Communication start events
00259     *
00260     * Wait on one of these events at the start of the communication. It means that
00261     * the I2C peripheral detected a Start condition on the bus (generated by master
00262     * device) followed by the peripheral address.
00263     * The peripheral generates an ACK condition on the bus (if the acknowledge
00264     * feature is enabled through function I2C_AcknowledgeConfig()) and the events
00265     * listed above are set :
00266     *
00267     * 1) In normal case (only one address managed by the slave), when the address
00268     *   sent by the master matches the own address of the peripheral (configured by
00269     *   I2C_OwnAddress1 field) the I2C_EVENT_SLAVE_XXX_ADDRESS_MATCHED event is set
00270     *   (where XXX could be TRANSMITTER or RECEIVER).
00271     *
00272     * 2) In case the address sent by the master is General Call (address 0x00) and 
00273     *   if the General Call is enabled for the peripheral (using function I2C_GeneralCallCmd()) 
00274     *   the following event is set I2C_EVENT_SLAVE_GENERALCALLADDRESS_MATCHED.  
00275     * 
00276     */
00277 
00278   /* --EV1  (all the events below are variants of EV1) */
00279   /* 1) Case of One Single Address managed by the slave */
00280   I2C_EVENT_SLAVE_RECEIVER_ADDRESS_MATCHED    = (uint16_t)0x0202,  /*!< BUSY and ADDR flags */
00281   I2C_EVENT_SLAVE_TRANSMITTER_ADDRESS_MATCHED = (uint16_t)0x0682,  /*!< TRA, BUSY, TXE and ADDR flags */
00282 
00283   /* 2) Case of General Call enabled for the slave */
00284   I2C_EVENT_SLAVE_GENERALCALLADDRESS_MATCHED  = (uint16_t)0x1200,  /*!< EV2: GENCALL and BUSY flags */
00285 
00286   /**
00287     * @brief  Communication events
00288     *
00289     * Wait on one of these events when EV1 has already been checked :
00290     *
00291     * - Slave RECEIVER mode:
00292     *     - EV2: When the application is expecting a data byte to be received.
00293     *     - EV4: When the application is expecting the end of the communication:
00294     *       master sends a stop condition and data transmission is stopped.
00295     *
00296     * - Slave Transmitter mode:
00297     *    - EV3: When a byte has been transmitted by the slave and the application
00298     *      is expecting the end of the byte transmission.
00299     *      The two events I2C_EVENT_SLAVE_BYTE_TRANSMITTED and I2C_EVENT_SLAVE_BYTE_TRANSMITTING
00300     *      are similar. The second one can optionally be used when the user software
00301     *      doesn't guarantee the EV3 is managed before the current byte end of transfer.
00302     *    - EV3_2: When the master sends a NACK in order to tell slave that data transmission
00303     *      shall end (before sending the STOP condition).
00304     *      In this case slave has to stop sending data bytes and expect a Stop
00305     *      condition on the bus.
00306     *
00307     *  @note In case the  user software does not guarantee that the event EV2 is
00308     *  managed before the current byte end of transfer, then user may check on EV2
00309     *  and BTF flag at the same time (ie. (I2C_EVENT_SLAVE_BYTE_RECEIVED | I2C_FLAG_BTF)).
00310     *  In this case the communication may be slower.
00311     *
00312     */
00313   /* Slave RECEIVER mode --------------------------*/
00314   /* --EV2 */
00315   I2C_EVENT_SLAVE_BYTE_RECEIVED              = (uint16_t)0x0240,  /*!< BUSY and RXNE flags */
00316   /* --EV4  */
00317   I2C_EVENT_SLAVE_STOP_DETECTED              = (uint16_t)0x0010,  /*!< STOPF flag */
00318 
00319   /* Slave TRANSMITTER mode -----------------------*/
00320   /* --EV3 */
00321   I2C_EVENT_SLAVE_BYTE_TRANSMITTED           = (uint16_t)0x0684,  /*!< TRA, BUSY, TXE and BTF flags */
00322   I2C_EVENT_SLAVE_BYTE_TRANSMITTING          = (uint16_t)0x0680,  /*!< TRA, BUSY and TXE flags */
00323   /* --EV3_2 */
00324   I2C_EVENT_SLAVE_ACK_FAILURE                = (uint16_t)0x0004  /*!< AF flag */
00325 } I2C_Event_TypeDef;
00326 
00327 /**
00328   * @}
00329   */
00330 
00331 /* Exported constants --------------------------------------------------------*/
00332 /** @addtogroup I2C_Exported_Constants
00333   * @{
00334   */
00335 #define I2C_MAX_STANDARD_FREQ ((uint32_t)100000)
00336 #define I2C_MAX_FAST_FREQ     ((uint32_t)400000)
00337 #if defined(STM8S208) || defined(STM8S207) || defined(STM8S007) 
00338  #define I2C_MAX_INPUT_FREQ     ((uint8_t)24)
00339 #else
00340  #define I2C_MAX_INPUT_FREQ     ((uint8_t)16)
00341 #endif
00342 
00343 /**
00344   * @}
00345   */
00346 
00347 /* Exported macros -----------------------------------------------------------*/
00348 /* Private macros ------------------------------------------------------------*/
00349 
00350 /** @addtogroup I2C_Private_Macros
00351   * @{
00352   */
00353 
00354 /**
00355   * @brief  Macro used by the assert function to check the different functions parameters.
00356   */
00357 
00358 /**
00359   * @brief   Macro used by the assert function to check the different I2C duty cycles.
00360   */
00361 #define IS_I2C_DUTYCYCLE_OK(DUTY) \
00362   (((DUTY) == I2C_DUTYCYCLE_2) || \
00363    ((DUTY) == I2C_DUTYCYCLE_16_9))
00364 
00365 /**
00366   * @brief   Macro used by the assert function to check the different acknowledgement configuration
00367   */
00368 #define IS_I2C_ACK_OK(ACK) \
00369   (((ACK) == I2C_ACK_NONE) || \
00370    ((ACK) == I2C_ACK_CURR) || \
00371    ((ACK) == I2C_ACK_NEXT))
00372 
00373 /**
00374   * @brief   Macro used by the assert function to check the different I2C addressing modes.
00375   */
00376 #define IS_I2C_ADDMODE_OK(ADDMODE) \
00377   (((ADDMODE) == I2C_ADDMODE_7BIT) || \
00378    ((ADDMODE) == I2C_ADDMODE_10BIT))
00379 
00380 /**
00381   * @brief   Macro used by the assert function to check the different I2C interrupt types.
00382   */
00383 #define IS_I2C_INTERRUPT_OK(IT) \
00384   (((IT) == I2C_IT_ERR)     || \
00385    ((IT) == I2C_IT_EVT)     || \
00386    ((IT) == I2C_IT_BUF)     || \
00387    ((IT) == (I2C_IT_ERR | I2C_IT_EVT)) || \
00388    ((IT) == (I2C_IT_ERR | I2C_IT_BUF)) || \
00389    ((IT) == (I2C_IT_EVT | I2C_IT_BUF)) || \
00390    ((IT) == (I2C_IT_EVT | I2C_IT_BUF | I2C_IT_ERR)))
00391 /**
00392   * @brief   Macro used by the assert function to check the different I2C communcation direction.
00393   */
00394 #define IS_I2C_DIRECTION_OK(DIR) \
00395   (((DIR) == I2C_DIRECTION_TX) || \
00396    ((DIR) == I2C_DIRECTION_RX))
00397 
00398 /**
00399   * @brief   Macro used by the assert function to check the different I2C flags.
00400   */
00401 #define IS_I2C_FLAG_OK(FLAG) \
00402   (((FLAG) == I2C_FLAG_TXEMPTY)         || \
00403    ((FLAG) == I2C_FLAG_RXNOTEMPTY)       || \
00404    ((FLAG) == I2C_FLAG_STOPDETECTION)      || \
00405    ((FLAG) == I2C_FLAG_HEADERSENT)       || \
00406    ((FLAG) == I2C_FLAG_TRANSFERFINISHED)   || \
00407    ((FLAG) == I2C_FLAG_ADDRESSSENTMATCHED)  || \
00408    ((FLAG) == I2C_FLAG_STARTDETECTION)    || \
00409    ((FLAG) == I2C_FLAG_WAKEUPFROMHALT)    || \
00410    ((FLAG) == I2C_FLAG_OVERRUNUNDERRUN)    || \
00411    ((FLAG) == I2C_FLAG_ACKNOWLEDGEFAILURE)  || \
00412    ((FLAG) == I2C_FLAG_ARBITRATIONLOSS)    || \
00413    ((FLAG) == I2C_FLAG_BUSERROR)       || \
00414    ((FLAG) == I2C_FLAG_GENERALCALL)      || \
00415    ((FLAG) == I2C_FLAG_TRANSMITTERRECEIVER) || \
00416    ((FLAG) == I2C_FLAG_BUSBUSY) || \
00417    ((FLAG) == I2C_FLAG_MASTERSLAVE))
00418 /**
00419   * @brief   Macro used by the assert function to check the I2C flags to clear.
00420   */
00421 
00422 #define IS_I2C_CLEAR_FLAG_OK(FLAG) ((((uint16_t)(FLAG) & (uint16_t)0xFD00) == 0x00) \
00423                                      && ((uint16_t)(FLAG) != 0x00))
00424 
00425 /**
00426   * @brief   Macro used by the assert function to check the different I2C possible pending bits.
00427   */
00428 #define IS_I2C_ITPENDINGBIT_OK(ITPENDINGBIT) \
00429    (((ITPENDINGBIT) == I2C_ITPENDINGBIT_TXEMPTY)                                        || \
00430     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_RXNOTEMPTY)                             || \
00431     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_STOPDETECTION)                  || \
00432     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_HEADERSENT)                             || \
00433     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_TRANSFERFINISHED)       || \
00434     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_ADDRESSSENTMATCHED) || \
00435     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_STARTDETECTION)                 || \
00436     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_WAKEUPFROMHALT)                 || \
00437     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_OVERRUNUNDERRUN)                || \
00438     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_ACKNOWLEDGEFAILURE) || \
00439     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_ARBITRATIONLOSS)                || \
00440     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_BUSERROR))
00441     
00442 /**
00443   * @brief  Macro used by the assert function to check the different I2C possible
00444   *   pending bits to clear by writing 0.
00445   */
00446 #define IS_I2C_CLEAR_ITPENDINGBIT_OK(ITPENDINGBIT) \
00447    (((ITPENDINGBIT) == I2C_ITPENDINGBIT_WAKEUPFROMHALT)     || \
00448     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_OVERRUNUNDERRUN)    || \
00449     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_ACKNOWLEDGEFAILURE) || \
00450     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_ARBITRATIONLOSS)    || \
00451     ((ITPENDINGBIT) == I2C_ITPENDINGBIT_BUSERROR))
00452    
00453 /**
00454   * @brief   Macro used by the assert function to check the different I2C possible events.
00455   */
00456 #define IS_I2C_EVENT_OK(EVENT) (((EVENT) == I2C_EVENT_SLAVE_TRANSMITTER_ADDRESS_MATCHED) || \
00457                              ((EVENT) == I2C_EVENT_SLAVE_RECEIVER_ADDRESS_MATCHED) || \
00458                              ((EVENT) == I2C_EVENT_SLAVE_GENERALCALLADDRESS_MATCHED) || \
00459                              ((EVENT) == I2C_EVENT_SLAVE_BYTE_RECEIVED) || \
00460                              ((EVENT) == (I2C_EVENT_SLAVE_BYTE_RECEIVED | (uint16_t)I2C_FLAG_GENERALCALL)) || \
00461                              ((EVENT) == I2C_EVENT_SLAVE_BYTE_TRANSMITTED) || \
00462                              ((EVENT) == (I2C_EVENT_SLAVE_BYTE_TRANSMITTED | (uint16_t)I2C_FLAG_GENERALCALL)) || \
00463                              ((EVENT) == I2C_EVENT_SLAVE_ACK_FAILURE) || \
00464                              ((EVENT) == I2C_EVENT_SLAVE_STOP_DETECTED) || \
00465                              ((EVENT) == I2C_EVENT_MASTER_MODE_SELECT) || \
00466                              ((EVENT) == I2C_EVENT_MASTER_TRANSMITTER_MODE_SELECTED) || \
00467                              ((EVENT) == I2C_EVENT_MASTER_RECEIVER_MODE_SELECTED) || \
00468                              ((EVENT) == I2C_EVENT_MASTER_BYTE_RECEIVED) || \
00469                              ((EVENT) == I2C_EVENT_MASTER_BYTE_TRANSMITTED) || \
00470                              ((EVENT) == I2C_EVENT_MASTER_BYTE_TRANSMITTING) || \
00471                              ((EVENT) == I2C_EVENT_MASTER_MODE_ADDRESS10))
00472 
00473 /**
00474   * @brief   Macro used by the assert function to check the different I2C possible own address.
00475   */
00476 #define IS_I2C_OWN_ADDRESS_OK(ADDRESS) \
00477   ((ADDRESS) <= (uint16_t)0x03FF)
00478 
00479 /* The address must be even */
00480 #define IS_I2C_ADDRESS_OK(ADD) \
00481   (((ADD) & (uint8_t)0x01) == (uint8_t)0x00)
00482 
00483 /**
00484   * @brief   Macro used by the assert function to check that I2C Input clock frequency must be between 1MHz and 50MHz.
00485   */
00486 #define IS_I2C_INPUT_CLOCK_FREQ_OK(FREQ) \
00487   (((FREQ) >= (uint8_t)1) && ((FREQ) <= I2C_MAX_INPUT_FREQ))
00488 
00489 
00490 /**
00491   * @brief   Macro used by the assert function to check that I2C Output clock frequency must be between 1Hz and 400kHz.
00492   */
00493 #define IS_I2C_OUTPUT_CLOCK_FREQ_OK(FREQ) \
00494   (((FREQ) >= (uint8_t)1) && ((FREQ) <= I2C_MAX_FAST_FREQ))
00495 
00496 /**
00497   * @}
00498   */
00499 
00500 /* Exported functions ------------------------------------------------------- */
00501 /** @addtogroup I2C_Exported_Functions
00502   * @{
00503   */
00504 
00505 void I2C_DeInit(void);
00506 void I2C_Init(uint32_t OutputClockFrequencyHz, uint16_t OwnAddress, 
00507               I2C_DutyCycle_TypeDef I2C_DutyCycle, I2C_Ack_TypeDef Ack, 
00508               I2C_AddMode_TypeDef AddMode, uint8_t InputClockFrequencyMHz );
00509 void I2C_Cmd(FunctionalState NewState);
00510 void I2C_GeneralCallCmd(FunctionalState NewState);
00511 void I2C_GenerateSTART(FunctionalState NewState);
00512 void I2C_GenerateSTOP(FunctionalState NewState);
00513 void I2C_SoftwareResetCmd(FunctionalState NewState);
00514 void I2C_StretchClockCmd(FunctionalState NewState);
00515 void I2C_AcknowledgeConfig(I2C_Ack_TypeDef Ack);
00516 void I2C_FastModeDutyCycleConfig(I2C_DutyCycle_TypeDef I2C_DutyCycle);
00517 void I2C_ITConfig(I2C_IT_TypeDef I2C_IT, FunctionalState NewState);
00518 uint8_t I2C_ReceiveData(void);
00519 void I2C_Send7bitAddress(uint8_t Address, I2C_Direction_TypeDef Direction);
00520 void I2C_SendData(uint8_t Data);
00521 /**
00522  * @brief
00523  ****************************************************************************************
00524  *
00525  *                         I2C State Monitoring Functions
00526  *
00527  ****************************************************************************************
00528  * This I2C driver provides three different ways for I2C state monitoring
00529  *  depending on the application requirements and constraints:
00530  *
00531  *
00532  * 1) Basic state monitoring:
00533  *    Using I2C_CheckEvent() function:
00534  *    It compares the status registers (SR1, SR2 and SR3) content to a given event
00535  *    (can be the combination of one or more flags).
00536  *    It returns SUCCESS if the current status includes the given flags
00537  *    and returns ERROR if one or more flags are missing in the current status.
00538  *    - When to use:
00539  *      - This function is suitable for most applications as well as for startup
00540  *      activity since the events are fully described in the product reference manual
00541  *      (RM0016).
00542  *      - It is also suitable for users who need to define their own events.
00543  *    - Limitations:
00544  *      - If an error occurs (ie. error flags are set besides to the monitored flags),
00545  *        the I2C_CheckEvent() function may return SUCCESS despite the communication
00546  *        hold or corrupted real state.
00547  *        In this case, it is advised to use error interrupts to monitor the error
00548  *        events and handle them in the interrupt IRQ handler.
00549  *
00550  *        @note
00551  *        For error management, it is advised to use the following functions:
00552  *          - I2C_ITConfig() to configure and enable the error interrupts (I2C_IT_ERR).
00553  *          - I2C_IRQHandler() which is called when the I2C interrupts occur.
00554  *          - I2C_GetFlagStatus() or I2C_GetITStatus() to be called into the
00555  *           I2Cx_IRQHandler() function in order to determine which error occurred.
00556  *          - I2C_ClearFlag() or I2C_ClearITPendingBit() and/or I2C_SoftwareResetCmd()
00557  *            and/or I2C_GenerateStop() in order to clear the error flag and
00558  *            source and return to correct communication status.
00559  *
00560  *
00561  *  2) Advanced state monitoring:
00562  *     Using the function I2C_GetLastEvent() which returns the image of both SR1
00563  *     & SR3 status registers in a single word (uint16_t) (Status Register 3 value
00564  *     is shifted left by 8 bits and concatenated to Status Register 1).
00565  *     - When to use:
00566  *       - This function is suitable for the same applications above but it allows to
00567  *         overcome the limitations of I2C_GetFlagStatus() function (see below).
00568  *         The returned value could be compared to events already defined in the
00569  *         library (stm8s_i2c.h) or to custom values defined by user.
00570  *       - This function is suitable when multiple flags are monitored at the same time.
00571  *       - At the opposite of I2C_CheckEvent() function, this function allows user to
00572  *         choose when an event is accepted (when all events flags are set and no
00573  *         other flags are set or just when the needed flags are set like
00574  *         I2C_CheckEvent() function).
00575  *     - Limitations:
00576  *       - User may need to define his own events.
00577  *       - Same remark concerning the error management is applicable for this
00578  *         function if user decides to check only regular communication flags (and
00579  *         ignores error flags).
00580  *
00581  *
00582  *  3) Flag-based state monitoring:
00583  *     Using the function I2C_GetFlagStatus() which simply returns the status of
00584  *     one single flag (ie. I2C_FLAG_RXNE ...).
00585  *     - When to use:
00586  *        - This function could be used for specific applications or in debug phase.
00587  *        - It is suitable when only one flag checking is needed (most I2C events
00588  *          are monitored through multiple flags).
00589  *     - Limitations:
00590  *        - When calling this function, the Status register is accessed. Some flags are
00591  *          cleared when the status register is accessed. So checking the status
00592  *          of one Flag, may clear other ones.
00593  *        - Function may need to be called twice or more in order to monitor one
00594  *          single event.
00595  *
00596  */
00597 
00598 /**
00599  *
00600  *  1) Basic state monitoring
00601  *******************************************************************************
00602  */
00603 ErrorStatus I2C_CheckEvent(I2C_Event_TypeDef I2C_Event);
00604 /**
00605  *
00606  *  2) Advanced state monitoring
00607  *******************************************************************************
00608  */
00609 I2C_Event_TypeDef I2C_GetLastEvent(void);
00610 /**
00611  *
00612  *  3) Flag-based state monitoring
00613  *******************************************************************************
00614  */
00615 FlagStatus I2C_GetFlagStatus(I2C_Flag_TypeDef I2C_Flag);
00616 /**
00617  *
00618  *******************************************************************************
00619  */
00620 void I2C_ClearFlag(I2C_Flag_TypeDef I2C_FLAG);
00621 ITStatus I2C_GetITStatus(I2C_ITPendingBit_TypeDef I2C_ITPendingBit);
00622 void I2C_ClearITPendingBit(I2C_ITPendingBit_TypeDef I2C_ITPendingBit);
00623 
00624 
00625 /**
00626   * @}
00627   */
00628 
00629 #endif /* __STM8S_I2C_H */
00630 
00631 
00632 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/
STM8 Standard Peripherals Library: Footer

 

 

 

      For complete documentation on STM8 8-bit Microcontrollers platform visit www.st.com