1 /***************COPYRIGHT(C) 2019 WCH. A11 rights reserved********************* 2 * File Name : ch32f10x_i2c.h 3 * Author : WCH 4 * Version : V1.0.0 5 * Date : 2019/10/15 6 * Description : This file contains all the functions prototypes for the 7 * I2C firmware library. 8 *******************************************************************************/ 9 #ifndef __CH32F10x_I2C_H 10 #define __CH32F10x_I2C_H 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 #include "ch32f10x.h" 17 18 /* I2C Init structure definition */ 19 typedef struct 20 { 21 uint32_t I2C_ClockSpeed; /*!< Specifies the clock frequency. 22 This parameter must be set to a value lower than 400kHz */ 23 24 uint16_t I2C_Mode; /*!< Specifies the I2C mode. 25 This parameter can be a value of @ref I2C_mode */ 26 27 uint16_t I2C_DutyCycle; /*!< Specifies the I2C fast mode duty cycle. 28 This parameter can be a value of @ref I2C_duty_cycle_in_fast_mode */ 29 30 uint16_t I2C_OwnAddress1; /*!< Specifies the first device own address. 31 This parameter can be a 7-bit or 10-bit address. */ 32 33 uint16_t I2C_Ack; /*!< Enables or disables the acknowledgement. 34 This parameter can be a value of @ref I2C_acknowledgement */ 35 36 uint16_t I2C_AcknowledgedAddress; /*!< Specifies if 7-bit or 10-bit address is acknowledged. 37 This parameter can be a value of @ref I2C_acknowledged_address */ 38 }I2C_InitTypeDef; 39 40 /* I2C_mode */ 41 #define I2C_Mode_I2C ((uint16_t)0x0000) 42 #define I2C_Mode_SMBusDevice ((uint16_t)0x0002) 43 #define I2C_Mode_SMBusHost ((uint16_t)0x000A) 44 45 /* I2C_duty_cycle_in_fast_mode */ 46 #define I2C_DutyCycle_16_9 ((uint16_t)0x4000) /*!< I2C fast mode Tlow/Thigh = 16/9 */ 47 #define I2C_DutyCycle_2 ((uint16_t)0xBFFF) /*!< I2C fast mode Tlow/Thigh = 2 */ 48 49 /* I2C_acknowledgement */ 50 #define I2C_Ack_Enable ((uint16_t)0x0400) 51 #define I2C_Ack_Disable ((uint16_t)0x0000) 52 53 /* I2C_transfer_direction */ 54 #define I2C_Direction_Transmitter ((uint8_t)0x00) 55 #define I2C_Direction_Receiver ((uint8_t)0x01) 56 57 /* I2C_acknowledged_address */ 58 #define I2C_AcknowledgedAddress_7bit ((uint16_t)0x4000) 59 #define I2C_AcknowledgedAddress_10bit ((uint16_t)0xC000) 60 61 /* I2C_registers */ 62 #define I2C_Register_CTLR1 ((uint8_t)0x00) 63 #define I2C_Register_CTLR2 ((uint8_t)0x04) 64 #define I2C_Register_OADDR1 ((uint8_t)0x08) 65 #define I2C_Register_OADDR2 ((uint8_t)0x0C) 66 #define I2C_Register_DATAR ((uint8_t)0x10) 67 #define I2C_Register_STAR1 ((uint8_t)0x14) 68 #define I2C_Register_STAR2 ((uint8_t)0x18) 69 #define I2C_Register_CKCFGR ((uint8_t)0x1C) 70 #define I2C_Register_RTR ((uint8_t)0x20) 71 72 /* I2C_SMBus_alert_pin_level */ 73 #define I2C_SMBusAlert_Low ((uint16_t)0x2000) 74 #define I2C_SMBusAlert_High ((uint16_t)0xDFFF) 75 76 /* I2C_PEC_position */ 77 #define I2C_PECPosition_Next ((uint16_t)0x0800) 78 #define I2C_PECPosition_Current ((uint16_t)0xF7FF) 79 80 /* I2C_NCAK_position */ 81 #define I2C_NACKPosition_Next ((uint16_t)0x0800) 82 #define I2C_NACKPosition_Current ((uint16_t)0xF7FF) 83 84 /* I2C_interrupts_definition */ 85 #define I2C_IT_BUF ((uint16_t)0x0400) 86 #define I2C_IT_EVT ((uint16_t)0x0200) 87 #define I2C_IT_ERR ((uint16_t)0x0100) 88 89 /* I2C_interrupts_definition */ 90 #define I2C_IT_SMBALERT ((uint32_t)0x01008000) 91 #define I2C_IT_TIMEOUT ((uint32_t)0x01004000) 92 #define I2C_IT_PECERR ((uint32_t)0x01001000) 93 #define I2C_IT_OVR ((uint32_t)0x01000800) 94 #define I2C_IT_AF ((uint32_t)0x01000400) 95 #define I2C_IT_ARLO ((uint32_t)0x01000200) 96 #define I2C_IT_BERR ((uint32_t)0x01000100) 97 #define I2C_IT_TXE ((uint32_t)0x06000080) 98 #define I2C_IT_RXNE ((uint32_t)0x06000040) 99 #define I2C_IT_STOPF ((uint32_t)0x02000010) 100 #define I2C_IT_ADD10 ((uint32_t)0x02000008) 101 #define I2C_IT_BTF ((uint32_t)0x02000004) 102 #define I2C_IT_ADDR ((uint32_t)0x02000002) 103 #define I2C_IT_SB ((uint32_t)0x02000001) 104 105 /* SR2 register flags */ 106 #define I2C_FLAG_DUALF ((uint32_t)0x00800000) 107 #define I2C_FLAG_SMBHOST ((uint32_t)0x00400000) 108 #define I2C_FLAG_SMBDEFAULT ((uint32_t)0x00200000) 109 #define I2C_FLAG_GENCALL ((uint32_t)0x00100000) 110 #define I2C_FLAG_TRA ((uint32_t)0x00040000) 111 #define I2C_FLAG_BUSY ((uint32_t)0x00020000) 112 #define I2C_FLAG_MSL ((uint32_t)0x00010000) 113 114 /* SR1 register flags */ 115 #define I2C_FLAG_SMBALERT ((uint32_t)0x10008000) 116 #define I2C_FLAG_TIMEOUT ((uint32_t)0x10004000) 117 #define I2C_FLAG_PECERR ((uint32_t)0x10001000) 118 #define I2C_FLAG_OVR ((uint32_t)0x10000800) 119 #define I2C_FLAG_AF ((uint32_t)0x10000400) 120 #define I2C_FLAG_ARLO ((uint32_t)0x10000200) 121 #define I2C_FLAG_BERR ((uint32_t)0x10000100) 122 #define I2C_FLAG_TXE ((uint32_t)0x10000080) 123 #define I2C_FLAG_RXNE ((uint32_t)0x10000040) 124 #define I2C_FLAG_STOPF ((uint32_t)0x10000010) 125 #define I2C_FLAG_ADD10 ((uint32_t)0x10000008) 126 #define I2C_FLAG_BTF ((uint32_t)0x10000004) 127 #define I2C_FLAG_ADDR ((uint32_t)0x10000002) 128 #define I2C_FLAG_SB ((uint32_t)0x10000001) 129 130 131 /*======================================== 132 133 I2C Master Events (Events grouped in order of communication) 134 ==========================================*/ 135 /** 136 * @brief Communication start 137 * 138 * After sending the START condition (I2C_GenerateSTART() function) the master 139 * has to wait for this event. It means that the Start condition has been correctly 140 * released on the I2C bus (the bus is free, no other devices is communicating). 141 * 142 */ 143 /* --EV5 */ 144 #define I2C_EVENT_MASTER_MODE_SELECT ((uint32_t)0x00030001) /* BUSY, MSL and SB flag */ 145 146 /** 147 * @brief Address Acknowledge 148 * 149 * After checking on EV5 (start condition correctly released on the bus), the 150 * master sends the address of the slave(s) with which it will communicate 151 * (I2C_Send7bitAddress() function, it also determines the direction of the communication: 152 * Master transmitter or Receiver). Then the master has to wait that a slave acknowledges 153 * his address. If an acknowledge is sent on the bus, one of the following events will 154 * be set: 155 * 156 * 1) In case of Master Receiver (7-bit addressing): the I2C_EVENT_MASTER_RECEIVER_MODE_SELECTED 157 * event is set. 158 * 159 * 2) In case of Master Transmitter (7-bit addressing): the I2C_EVENT_MASTER_TRANSMITTER_MODE_SELECTED 160 * is set 161 * 162 * 3) In case of 10-Bit addressing mode, the master (just after generating the START 163 * and checking on EV5) has to send the header of 10-bit addressing mode (I2C_SendData() 164 * function). Then master should wait on EV9. It means that the 10-bit addressing 165 * header has been correctly sent on the bus. Then master should send the second part of 166 * the 10-bit address (LSB) using the function I2C_Send7bitAddress(). Then master 167 * should wait for event EV6. 168 * 169 */ 170 171 /* --EV6 */ 172 #define I2C_EVENT_MASTER_TRANSMITTER_MODE_SELECTED ((uint32_t)0x00070082) /* BUSY, MSL, ADDR, TXE and TRA flags */ 173 #define I2C_EVENT_MASTER_RECEIVER_MODE_SELECTED ((uint32_t)0x00030002) /* BUSY, MSL and ADDR flags */ 174 /* --EV9 */ 175 #define I2C_EVENT_MASTER_MODE_ADDRESS10 ((uint32_t)0x00030008) /* BUSY, MSL and ADD10 flags */ 176 177 /** 178 * @brief Communication events 179 * 180 * If a communication is established (START condition generated and slave address 181 * acknowledged) then the master has to check on one of the following events for 182 * communication procedures: 183 * 184 * 1) Master Receiver mode: The master has to wait on the event EV7 then to read 185 * the data received from the slave (I2C_ReceiveData() function). 186 * 187 * 2) Master Transmitter mode: The master has to send data (I2C_SendData() 188 * function) then to wait on event EV8 or EV8_2. 189 * These two events are similar: 190 * - EV8 means that the data has been written in the data register and is 191 * being shifted out. 192 * - EV8_2 means that the data has been physically shifted out and output 193 * on the bus. 194 * In most cases, using EV8 is sufficient for the application. 195 * Using EV8_2 leads to a slower communication but ensure more reliable test. 196 * EV8_2 is also more suitable than EV8 for testing on the last data transmission 197 * (before Stop condition generation). 198 * 199 * @note In case the user software does not guarantee that this event EV7 is 200 * managed before the current byte end of transfer, then user may check on EV7 201 * and BTF flag at the same time (ie. (I2C_EVENT_MASTER_BYTE_RECEIVED | I2C_FLAG_BTF)). 202 * In this case the communication may be slower. 203 * 204 */ 205 206 /* Master RECEIVER mode -----------------------------*/ 207 /* --EV7 */ 208 #define I2C_EVENT_MASTER_BYTE_RECEIVED ((uint32_t)0x00030040) /* BUSY, MSL and RXNE flags */ 209 210 /* Master TRANSMITTER mode --------------------------*/ 211 /* --EV8 */ 212 #define I2C_EVENT_MASTER_BYTE_TRANSMITTING ((uint32_t)0x00070080) /* TRA, BUSY, MSL, TXE flags */ 213 /* --EV8_2 */ 214 #define I2C_EVENT_MASTER_BYTE_TRANSMITTED ((uint32_t)0x00070084) /* TRA, BUSY, MSL, TXE and BTF flags */ 215 216 217 /*======================================== 218 219 I2C Slave Events (Events grouped in order of communication) 220 ==========================================*/ 221 222 /** 223 * @brief Communication start events 224 * 225 * Wait on one of these events at the start of the communication. It means that 226 * the I2C peripheral detected a Start condition on the bus (generated by master 227 * device) followed by the peripheral address. The peripheral generates an ACK 228 * condition on the bus (if the acknowledge feature is enabled through function 229 * I2C_AcknowledgeConfig()) and the events listed above are set : 230 * 231 * 1) In normal case (only one address managed by the slave), when the address 232 * sent by the master matches the own address of the peripheral (configured by 233 * I2C_OwnAddress1 field) the I2C_EVENT_SLAVE_XXX_ADDRESS_MATCHED event is set 234 * (where XXX could be TRANSMITTER or RECEIVER). 235 * 236 * 2) In case the address sent by the master matches the second address of the 237 * peripheral (configured by the function I2C_OwnAddress2Config() and enabled 238 * by the function I2C_DualAddressCmd()) the events I2C_EVENT_SLAVE_XXX_SECONDADDRESS_MATCHED 239 * (where XXX could be TRANSMITTER or RECEIVER) are set. 240 * 241 * 3) In case the address sent by the master is General Call (address 0x00) and 242 * if the General Call is enabled for the peripheral (using function I2C_GeneralCallCmd()) 243 * the following event is set I2C_EVENT_SLAVE_GENERALCALLADDRESS_MATCHED. 244 * 245 */ 246 247 /* --EV1 (all the events below are variants of EV1) */ 248 /* 1) Case of One Single Address managed by the slave */ 249 #define I2C_EVENT_SLAVE_RECEIVER_ADDRESS_MATCHED ((uint32_t)0x00020002) /* BUSY and ADDR flags */ 250 #define I2C_EVENT_SLAVE_TRANSMITTER_ADDRESS_MATCHED ((uint32_t)0x00060082) /* TRA, BUSY, TXE and ADDR flags */ 251 252 /* 2) Case of Dual address managed by the slave */ 253 #define I2C_EVENT_SLAVE_RECEIVER_SECONDADDRESS_MATCHED ((uint32_t)0x00820000) /* DUALF and BUSY flags */ 254 #define I2C_EVENT_SLAVE_TRANSMITTER_SECONDADDRESS_MATCHED ((uint32_t)0x00860080) /* DUALF, TRA, BUSY and TXE flags */ 255 256 /* 3) Case of General Call enabled for the slave */ 257 #define I2C_EVENT_SLAVE_GENERALCALLADDRESS_MATCHED ((uint32_t)0x00120000) /* GENCALL and BUSY flags */ 258 259 /** 260 * @brief Communication events 261 * 262 * Wait on one of these events when EV1 has already been checked and: 263 * 264 * - Slave RECEIVER mode: 265 * - EV2: When the application is expecting a data byte to be received. 266 * - EV4: When the application is expecting the end of the communication: master 267 * sends a stop condition and data transmission is stopped. 268 * 269 * - Slave Transmitter mode: 270 * - EV3: When a byte has been transmitted by the slave and the application is expecting 271 * the end of the byte transmission. The two events I2C_EVENT_SLAVE_BYTE_TRANSMITTED and 272 * I2C_EVENT_SLAVE_BYTE_TRANSMITTING are similar. The second one can optionally be 273 * used when the user software doesn't guarantee the EV3 is managed before the 274 * current byte end of transfer. 275 * - EV3_2: When the master sends a NACK in order to tell slave that data transmission 276 * shall end (before sending the STOP condition). In this case slave has to stop sending 277 * data bytes and expect a Stop condition on the bus. 278 * 279 * @note In case the user software does not guarantee that the event EV2 is 280 * managed before the current byte end of transfer, then user may check on EV2 281 * and BTF flag at the same time (ie. (I2C_EVENT_SLAVE_BYTE_RECEIVED | I2C_FLAG_BTF)). 282 * In this case the communication may be slower. 283 * 284 */ 285 286 /* Slave RECEIVER mode --------------------------*/ 287 /* --EV2 */ 288 #define I2C_EVENT_SLAVE_BYTE_RECEIVED ((uint32_t)0x00020040) /* BUSY and RXNE flags */ 289 /* --EV4 */ 290 #define I2C_EVENT_SLAVE_STOP_DETECTED ((uint32_t)0x00000010) /* STOPF flag */ 291 292 /* Slave TRANSMITTER mode -----------------------*/ 293 /* --EV3 */ 294 #define I2C_EVENT_SLAVE_BYTE_TRANSMITTED ((uint32_t)0x00060084) /* TRA, BUSY, TXE and BTF flags */ 295 #define I2C_EVENT_SLAVE_BYTE_TRANSMITTING ((uint32_t)0x00060080) /* TRA, BUSY and TXE flags */ 296 /* --EV3_2 */ 297 #define I2C_EVENT_SLAVE_ACK_FAILURE ((uint32_t)0x00000400) /* AF flag */ 298 299 /*=========================== End of Events Description ==========================================*/ 300 301 302 void I2C_DeInit(I2C_TypeDef* I2Cx); 303 void I2C_Init(I2C_TypeDef* I2Cx, I2C_InitTypeDef* I2C_InitStruct); 304 void I2C_StructInit(I2C_InitTypeDef* I2C_InitStruct); 305 void I2C_Cmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 306 void I2C_DMACmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 307 void I2C_DMALastTransferCmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 308 void I2C_GenerateSTART(I2C_TypeDef* I2Cx, FunctionalState NewState); 309 void I2C_GenerateSTOP(I2C_TypeDef* I2Cx, FunctionalState NewState); 310 void I2C_AcknowledgeConfig(I2C_TypeDef* I2Cx, FunctionalState NewState); 311 void I2C_OwnAddress2Config(I2C_TypeDef* I2Cx, uint8_t Address); 312 void I2C_DualAddressCmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 313 void I2C_GeneralCallCmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 314 void I2C_ITConfig(I2C_TypeDef* I2Cx, uint16_t I2C_IT, FunctionalState NewState); 315 void I2C_SendData(I2C_TypeDef* I2Cx, uint8_t Data); 316 uint8_t I2C_ReceiveData(I2C_TypeDef* I2Cx); 317 void I2C_Send7bitAddress(I2C_TypeDef* I2Cx, uint8_t Address, uint8_t I2C_Direction); 318 uint16_t I2C_ReadRegister(I2C_TypeDef* I2Cx, uint8_t I2C_Register); 319 void I2C_SoftwareResetCmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 320 void I2C_NACKPositionConfig(I2C_TypeDef* I2Cx, uint16_t I2C_NACKPosition); 321 void I2C_SMBusAlertConfig(I2C_TypeDef* I2Cx, uint16_t I2C_SMBusAlert); 322 void I2C_TransmitPEC(I2C_TypeDef* I2Cx, FunctionalState NewState); 323 void I2C_PECPositionConfig(I2C_TypeDef* I2Cx, uint16_t I2C_PECPosition); 324 void I2C_CalculatePEC(I2C_TypeDef* I2Cx, FunctionalState NewState); 325 uint8_t I2C_GetPEC(I2C_TypeDef* I2Cx); 326 void I2C_ARPCmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 327 void I2C_StretchClockCmd(I2C_TypeDef* I2Cx, FunctionalState NewState); 328 void I2C_FastModeDutyCycleConfig(I2C_TypeDef* I2Cx, uint16_t I2C_DutyCycle); 329 330 /** 331 * @brief 332 **************************************************************************************** 333 * 334 * I2C State Monitoring Functions 335 * 336 **************************************************************************************** 337 * This I2C driver provides three different ways for I2C state monitoring 338 * depending on the application requirements and constraints: 339 * 340 * 341 * 1) Basic state monitoring: 342 * Using I2C_CheckEvent() function: 343 * It compares the status registers (SR1 and SR2) content to a given event 344 * (can be the combination of one or more flags). 345 * It returns SUCCESS if the current status includes the given flags 346 * and returns ERROR if one or more flags are missing in the current status. 347 * - When to use: 348 * - This function is suitable for most applications as well as for startup 349 * activity since the events are fully described in the product reference manual 350 * (RM0008). 351 * - It is also suitable for users who need to define their own events. 352 * - Limitations: 353 * - If an error occurs (ie. error flags are set besides to the monitored flags), 354 * the I2C_CheckEvent() function may return SUCCESS despite the communication 355 * hold or corrupted real state. 356 * In this case, it is advised to use error interrupts to monitor the error 357 * events and handle them in the interrupt IRQ handler. 358 * 359 * @note 360 * For error management, it is advised to use the following functions: 361 * - I2C_ITConfig() to configure and enable the error interrupts (I2C_IT_ERR). 362 * - I2Cx_ER_IRQHandler() which is called when the error interrupt occurs. 363 * Where x is the peripheral instance (I2C1, I2C2 ...) 364 * - I2C_GetFlagStatus() or I2C_GetITStatus() to be called into I2Cx_ER_IRQHandler() 365 * in order to determine which error occurred. 366 * - I2C_ClearFlag() or I2C_ClearITPendingBit() and/or I2C_SoftwareResetCmd() 367 * and/or I2C_GenerateStop() in order to clear the error flag and source, 368 * and return to correct communication status. 369 * 370 * 371 * 2) Advanced state monitoring: 372 * Using the function I2C_GetLastEvent() which returns the image of both status 373 * registers in a single word (uint32_t) (Status Register 2 value is shifted left 374 * by 16 bits and concatenated to Status Register 1). 375 * - When to use: 376 * - This function is suitable for the same applications above but it allows to 377 * overcome the limitations of I2C_GetFlagStatus() function (see below). 378 * The returned value could be compared to events already defined in the 379 * library (ch32f10x_i2c.h) or to custom values defined by user. 380 * - This function is suitable when multiple flags are monitored at the same time. 381 * - At the opposite of I2C_CheckEvent() function, this function allows user to 382 * choose when an event is accepted (when all events flags are set and no 383 * other flags are set or just when the needed flags are set like 384 * I2C_CheckEvent() function). 385 * - Limitations: 386 * - User may need to define his own events. 387 * - Same remark concerning the error management is applicable for this 388 * function if user decides to check only regular communication flags (and 389 * ignores error flags). 390 * 391 * 392 * 3) Flag-based state monitoring: 393 * Using the function I2C_GetFlagStatus() which simply returns the status of 394 * one single flag (ie. I2C_FLAG_RXNE ...). 395 * - When to use: 396 * - This function could be used for specific applications or in debug phase. 397 * - It is suitable when only one flag checking is needed (most I2C events 398 * are monitored through multiple flags). 399 * - Limitations: 400 * - When calling this function, the Status register is accessed. Some flags are 401 * cleared when the status register is accessed. So checking the status 402 * of one Flag, may clear other ones. 403 * - Function may need to be called twice or more in order to monitor one 404 * single event. 405 * 406 */ 407 408 /** 409 * 410 * 1) Basic state monitoring 411 ******************************************************************************* 412 */ 413 ErrorStatus I2C_CheckEvent(I2C_TypeDef* I2Cx, uint32_t I2C_EVENT); 414 /** 415 * 416 * 2) Advanced state monitoring 417 ******************************************************************************* 418 */ 419 uint32_t I2C_GetLastEvent(I2C_TypeDef* I2Cx); 420 /** 421 * 422 * 3) Flag-based state monitoring 423 ******************************************************************************* 424 */ 425 FlagStatus I2C_GetFlagStatus(I2C_TypeDef* I2Cx, uint32_t I2C_FLAG); 426 /** 427 * 428 ******************************************************************************* 429 */ 430 431 void I2C_ClearFlag(I2C_TypeDef* I2Cx, uint32_t I2C_FLAG); 432 ITStatus I2C_GetITStatus(I2C_TypeDef* I2Cx, uint32_t I2C_IT); 433 void I2C_ClearITPendingBit(I2C_TypeDef* I2Cx, uint32_t I2C_IT); 434 435 #ifdef __cplusplus 436 } 437 #endif 438 439 #endif /*__CH32F10x_I2C_H */ 440 441 442 443 444 445 446 447 448