1 /**************************************************************************//**
2 * @file i2c.h
3 * @version V3.0
4 * $Revision: 1 $
5 * $Date: 16/07/07 7:50p $
6 * @brief I2C Serial Interface Controller(I2C) driver header file
7 *
8 * @copyright SPDX-License-Identifier: Apache-2.0
9 * @copyright Copyright (C) 2020 Nuvoton Technology Corp. All rights reserved.
10 ******************************************************************************/
11 #ifndef __I2C_H__
12 #define __I2C_H__
13
14 #ifdef __cplusplus
15 extern "C"
16 {
17 #endif
18
19
20 /** @addtogroup Standard_Driver Standard Driver
21 @{
22 */
23
24 /** @addtogroup I2C_Driver I2C Driver
25 @{
26 */
27
28 /** @addtogroup I2C_EXPORTED_CONSTANTS I2C Exported Constants
29 @{
30 */
31
32 /*---------------------------------------------------------------------------------------------------------*/
33 /* I2C_CTL constant definitions. */
34 /*---------------------------------------------------------------------------------------------------------*/
35 #define I2C_CTL_STA_SI (0x28U) /*!< I2C_CTL setting for I2C control bits. It would set STA and SI bits */
36 #define I2C_CTL_STA_SI_AA (0x2CU) /*!< I2C_CTL setting for I2C control bits. It would set STA, SI and AA bits */
37 #define I2C_CTL_STO_SI (0x18U) /*!< I2C_CTL setting for I2C control bits. It would set STO and SI bits */
38 #define I2C_CTL_STO_SI_AA (0x1CU) /*!< I2C_CTL setting for I2C control bits. It would set STO, SI and AA bits */
39 #define I2C_CTL_SI (0x08U) /*!< I2C_CTL setting for I2C control bits. It would set SI bit */
40 #define I2C_CTL_SI_AA (0x0CU) /*!< I2C_CTL setting for I2C control bits. It would set SI and AA bits */
41 #define I2C_CTL_STA (0x20U) /*!< I2C_CTL setting for I2C control bits. It would set STA bit */
42 #define I2C_CTL_STO (0x10U) /*!< I2C_CTL setting for I2C control bits. It would set STO bit */
43 #define I2C_CTL_AA (0x04U) /*!< I2C_CTL setting for I2C control bits. It would set AA bit */
44
45 /*---------------------------------------------------------------------------------------------------------*/
46 /* I2C GCMode constant definitions. */
47 /*---------------------------------------------------------------------------------------------------------*/
48 #define I2C_GCMODE_ENABLE (1U) /*!< Enable I2C GC Mode */
49 #define I2C_GCMODE_DISABLE (0U) /*!< Disable I2C GC Mode */
50
51 /*---------------------------------------------------------------------------------------------------------*/
52 /* I2C SMBUS constant definitions. */
53 /*---------------------------------------------------------------------------------------------------------*/
54 #define I2C_SMBH_ENABLE (1U) /*!< Enable SMBus Host Mode enable */
55 #define I2C_SMBD_ENABLE (0U) /*!< Enable SMBus Device Mode enable */
56 #define I2C_PECTX_ENABLE (1U) /*!< Enable SMBus Packet Error Check Transmit function */
57 #define I2C_PECTX_DISABLE (0U) /*!< Disable SMBus Packet Error Check Transmit function */
58
59 /**@}*/ /* end of group I2C_EXPORTED_CONSTANTS */
60
61 /** @addtogroup I2C_EXPORTED_FUNCTIONS I2C Exported Functions
62 @{
63 */
64 /**
65 * @brief The macro is used to set I2C bus condition at One Time
66 *
67 * @param[in] i2c Specify I2C port
68 * @param[in] u8Ctrl A byte writes to I2C control register
69 *
70 * @return None
71 *
72 * @details Set I2C_CTL register to control I2C bus conditions of START, STOP, SI, ACK.
73 */
74 #define I2C_SET_CONTROL_REG(i2c, u8Ctrl) ((i2c)->CTL0 = ((i2c)->CTL0 & ~0x3Cu) | (u8Ctrl))
75
76 /**
77 * @brief The macro is used to set START condition of I2C Bus
78 *
79 * @param[in] i2c Specify I2C port
80 *
81 * @return None
82 *
83 * @details Set the I2C bus START condition in I2C_CTL register.
84 */
85 #define I2C_START(i2c) ((i2c)->CTL0 = ((i2c)->CTL0 | I2C_CTL0_SI_Msk) | I2C_CTL0_STA_Msk)
86
87 /**
88 * @brief The macro is used to wait I2C bus status get ready
89 *
90 * @param[in] i2c Specify I2C port
91 *
92 * @return None
93 *
94 * @details When a new status is presented of I2C bus, the SI flag will be set in I2C_CTL register.
95 */
96 #define I2C_WAIT_READY(i2c) while(!((i2c)->CTL0 & I2C_CTL0_SI_Msk))
97
98 /**
99 * @brief The macro is used to Read I2C Bus Data Register
100 *
101 * @param[in] i2c Specify I2C port
102 *
103 * @return A byte of I2C data register
104 *
105 * @details I2C controller read data from bus and save it in I2CDAT register.
106 */
107 #define I2C_GET_DATA(i2c) ((i2c)->DAT)
108
109 /**
110 * @brief Write a Data to I2C Data Register
111 *
112 * @param[in] i2c Specify I2C port
113 * @param[in] u8Data A byte that writes to data register
114 *
115 * @return None
116 *
117 * @details When write a data to I2C_DAT register, the I2C controller will shift it to I2C bus.
118 */
119 #define I2C_SET_DATA(i2c, u8Data) ((i2c)->DAT = (u8Data))
120
121 /**
122 * @brief Get I2C Bus status code
123 *
124 * @param[in] i2c Specify I2C port
125 *
126 * @return I2C status code
127 *
128 * @details To get this status code to monitor I2C bus event.
129 */
130 #define I2C_GET_STATUS(i2c) ((i2c)->STATUS0)
131
132 /**
133 * @brief Get Time-out flag from I2C Bus
134 *
135 * @param[in] i2c Specify I2C port
136 *
137 * @retval 0 I2C Bus time-out is not happened
138 * @retval 1 I2C Bus time-out is happened
139 *
140 * @details When I2C bus occurs time-out event, the time-out flag will be set.
141 */
142 #define I2C_GET_TIMEOUT_FLAG(i2c) ( ((i2c)->TOCTL & I2C_TOCTL_TOIF_Msk) == I2C_TOCTL_TOIF_Msk ? 1u : 0u)
143
144 /**
145 * @brief To get wake-up flag from I2C Bus
146 *
147 * @param[in] i2c Specify I2C port
148 *
149 * @retval 0 Chip is not woken-up from power-down mode
150 * @retval 1 Chip is woken-up from power-down mode
151 *
152 * @details I2C bus occurs wake-up event, wake-up flag will be set.
153 */
154 #define I2C_GET_WAKEUP_FLAG(i2c) ( ((i2c)->WKSTS & I2C_WKSTS_WKIF_Msk) == I2C_WKSTS_WKIF_Msk ? 1u : 0u)
155
156 /**
157 * @brief To clear wake-up flag
158 *
159 * @param[in] i2c Specify I2C port
160 *
161 * @return None
162 *
163 * @details If wake-up flag is set, use this macro to clear it.
164 */
165 #define I2C_CLEAR_WAKEUP_FLAG(i2c) ((i2c)->WKSTS = I2C_WKSTS_WKIF_Msk)
166
167 /**
168 * @brief To get wake-up address frame ACK done flag from I2C Bus
169 *
170 * @param[in] i2c Specify I2C port
171 *
172 * @retval 0 The ACK bit cycle of address match frame is not done
173 * @retval 1 The ACK bit cycle of address match frame is done in power-down
174 *
175 * @details I2C bus occurs wake-up event and address frame ACK is done, this flag will be set.
176 *
177 * \hideinitializer
178 */
179 #define I2C_GET_WAKEUP_DONE(i2c) ( ((i2c)->WKSTS & I2C_WKSTS_WKAKDONE_Msk) == I2C_WKSTS_WKAKDONE_Msk ? 1u : 0u)
180
181 /**
182 * @brief To clear address frame ACK done flag
183 *
184 * @param[in] i2c Specify I2C port
185 *
186 * @return None
187 *
188 * @details If wake-up done is set, use this macro to clear it.
189 *
190 * \hideinitializer
191 */
192 #define I2C_CLEAR_WAKEUP_DONE(i2c) ((i2c)->WKSTS = I2C_WKSTS_WKAKDONE_Msk)
193
194 /**
195 * @brief To get read/write status bit in address wakeup frame
196 *
197 * @param[in] i2c Specify I2C port
198 *
199 * @retval 0 Write command be record on the address match wakeup frame
200 * @retval 1 Read command be record on the address match wakeup frame.
201 *
202 * @details I2C bus occurs wake-up event and address frame is received, this bit will record read/write status.
203 *
204 * \hideinitializer
205 */
206 #define I2C_GET_WAKEUP_WR_STATUS(i2c) ( ((i2c)->WKSTS & I2C_WKSTS_WRSTSWK_Msk) == I2C_WKSTS_WRSTSWK_Msk ? 1u : 0u)
207
208 /**
209 * @brief To get SMBus Status
210 *
211 * @param[in] i2c Specify I2C port
212 *
213 * @return SMBus status
214 *
215 * @details To get the Bus Management status of I2C_BUSSTS register
216 *
217 */
218 #define I2C_SMBUS_GET_STATUS(i2c) ((i2c)->BUSSTS)
219
220 /**
221 * @brief Get SMBus CRC value
222 *
223 * @param[in] i2c Specify I2C port
224 *
225 * @return Packet error check byte value
226 *
227 * @details The CRC check value after a transmission or a reception by count by using CRC8
228 *
229 */
230 #define I2C_SMBUS_GET_PEC_VALUE(i2c) ((i2c)->PKTCRC)
231
232 /**
233 * @brief Set SMBus Bytes number of Transmission or reception
234 *
235 * @param[in] i2c Specify I2C port
236 * @param[in] u32PktSize Transmit / Receive bytes
237 *
238 * @return None
239 *
240 * @details The transmission or receive byte number in one transaction when PECEN is set. The maximum is 255 bytes.
241 *
242 */
243 #define I2C_SMBUS_SET_PACKET_BYTE_COUNT(i2c, u32PktSize) ((i2c)->PKTSIZE = (u32PktSize))
244
245 /**
246 * @brief Enable SMBus Alert function
247 *
248 * @param[in] i2c Specify I2C port
249 *
250 * @return None
251 *
252 * @details Device Mode(BMHEN=0): If ALERTEN(I2C_BUSCTL[4]) is set, the Alert pin will pull lo, and reply ACK when get ARP from host
253 * Host Mode(BMHEN=1): If ALERTEN(I2C_BUSCTL[4]) is set, the Alert pin is supported to receive alert state(Lo trigger)
254 *
255 */
256 #define I2C_SMBUS_ENABLE_ALERT(i2c) ((i2c)->BUSCTL |= I2C_BUSCTL_ALERTEN_Msk)
257
258 /**
259 * @brief Disable SMBus Alert pin function
260 *
261 * @param[in] i2c Specify I2C port
262 *
263 * @return None
264 *
265 * @details Device Mode(BMHEN=0): If ALERTEN(I2C_BUSCTL[4]) is clear, the Alert pin will pull hi, and reply NACK when get ARP from host
266 * Host Mode(BMHEN=1): If ALERTEN(I2C_BUSCTL[4]) is clear, the Alert pin is not supported to receive alert state(Lo trigger)
267 *
268 */
269 #define I2C_SMBUS_DISABLE_ALERT(i2c) ((i2c)->BUSCTL &= ~I2C_BUSCTL_ALERTEN_Msk)
270
271 /**
272 * @brief Set SMBus SUSCON pin is output mode
273 *
274 * @param[in] i2c Specify I2C port
275 *
276 * @return None
277 *
278 * @details This function to set SUSCON(I2C_BUSCTL[6]) pin is output mode.
279 *
280 *
281 */
282 #define I2C_SMBUS_SET_SUSCON_OUT(i2c) ((i2c)->BUSCTL |= I2C_BUSCTL_SCTLOEN_Msk)
283
284 /**
285 * @brief Set SMBus SUSCON pin is input mode
286 *
287 * @param[in] i2c Specify I2C port
288 *
289 * @return None
290 *
291 * @details This function to set SUSCON(I2C_BUSCTL[6]) pin is input mode.
292 *
293 *
294 */
295 #define I2C_SMBUS_SET_SUSCON_IN(i2c) ((i2c)->BUSCTL &= ~I2C_BUSCTL_SCTLOEN_Msk)
296
297 /**
298 * @brief Set SMBus SUSCON pin output high state
299 *
300 * @param[in] i2c Specify I2C port
301 *
302 * @return None
303 *
304 * @details This function to set SUSCON(I2C_BUSCTL[6]) pin is output hi state.
305 *
306 */
307 #define I2C_SMBUS_SET_SUSCON_HIGH(i2c) ((i2c)->BUSCTL |= I2C_BUSCTL_SCTLOSTS_Msk)
308
309
310 /**
311 * @brief Set SMBus SUSCON pin output low state
312 *
313 * @param[in] i2c Specify I2C port
314 *
315 * @return None
316 *
317 * @details This function to set SUSCON(I2C_BUSCTL[6]) pin is output lo state.
318 *
319 */
320 #define I2C_SMBUS_SET_SUSCON_LOW(i2c) ((i2c)->BUSCTL &= ~I2C_BUSCTL_SCTLOSTS_Msk)
321
322 /**
323 * @brief Enable SMBus Acknowledge control by manual
324 *
325 * @param[in] i2c Specify I2C port
326 *
327 * @return None
328 *
329 * @details The 9th bit can response the ACK or NACK according the received data by user. When the byte is received, SCLK line stretching to low between the 8th and 9th SCLK pulse.
330 *
331 */
332 #define I2C_SMBUS_ACK_MANUAL(i2c) ((i2c)->BUSCTL |= I2C_BUSCTL_ACKMEN_Msk)
333
334 /**
335 * @brief Disable SMBus Acknowledge control by manual
336 *
337 * @param[in] i2c Specify I2C port
338 *
339 * @return None
340 *
341 * @details Disable acknowledge response control by user.
342 *
343 */
344 #define I2C_SMBUS_ACK_AUTO(i2c) ((i2c)->BUSCTL &= ~I2C_BUSCTL_ACKMEN_Msk)
345
346 /**
347 * @brief Enable SMBus Acknowledge manual interrupt
348 *
349 * @param[in] i2c Specify I2C port
350 *
351 * @return None
352 *
353 * @details This function is used to enable SMBUS acknowledge manual interrupt on the 9th clock cycle when SMBUS=1 and ACKMEN=1
354 *
355 */
356 #define I2C_SMBUS_9THBIT_INT_ENABLE(i2c) ((i2c)->BUSCTL |= I2C_BUSCTL_ACKM9SI_Msk)
357
358 /**
359 * @brief Disable SMBus Acknowledge manual interrupt
360 *
361 * @param[in] i2c Specify I2C port
362 *
363 * @return None
364 *
365 * @details This function is used to disable SMBUS acknowledge manual interrupt on the 9th clock cycle when SMBUS=1 and ACKMEN=1
366 *
367 */
368 #define I2C_SMBUS_9THBIT_INT_DISABLE(i2c) ((i2c)->BUSCTL &= ~I2C_BUSCTL_ACKM9SI_Msk)
369
370 /**
371 * @brief Enable SMBus PEC clear at REPEAT START
372 *
373 * @param[in] i2c Specify I2C port
374 *
375 * @return None
376 *
377 * @details This function is used to enable the condition of REAEAT START can clear the PEC calculation.
378 *
379 */
380 #define I2C_SMBUS_RST_PEC_AT_START_ENABLE(i2c) ((i2c)->BUSCTL |= I2C_BUSCTL_PECCLR_Msk)
381
382 /**
383 * @brief Disable SMBus PEC clear at Repeat START
384 *
385 * @param[in] i2c Specify I2C port
386 *
387 * @return None
388 *
389 * @details This function is used to disable the condition of Repeat START can clear the PEC calculation.
390 *
391 */
392 #define I2C_SMBUS_RST_PEC_AT_START_DISABLE(i2c) ((i2c)->BUSCTL &= ~I2C_BUSCTL_PECCLR_Msk)
393
394 /**
395 * @brief Enable RX PDMA function.
396 * @param[in] i2c The pointer of the specified I2C module.
397 * @return None.
398 * @details Set RXPDMAEN bit of I2C_CTL1 register to enable RX PDMA transfer function.
399 */
400 #define I2C_ENABLE_RX_PDMA(i2c) ((i2c)->CTL1 |= I2C_CTL1_RXPDMAEN_Msk)
401
402 /**
403 * @brief Enable TX PDMA function.
404 * @param[in] i2c The pointer of the specified I2C module.
405 * @return None.
406 * @details Set TXPDMAEN bit of I2C_CTL1 register to enable TX PDMA transfer function.
407 */
408 #define I2C_ENABLE_TX_PDMA(i2c) ((i2c)->CTL1 |= I2C_CTL1_TXPDMAEN_Msk)
409
410 /**
411 * @brief Disable RX PDMA transfer.
412 * @param[in] i2c The pointer of the specified I2C module.
413 * @return None.
414 * @details Clear RXPDMAEN bit of I2C_CTL1 register to disable RX PDMA transfer function.
415 */
416 #define I2C_DISABLE_RX_PDMA(i2c) ((i2c)->CTL1 &= ~I2C_CTL1_RXPDMAEN_Msk)
417
418 /**
419 * @brief Disable TX PDMA transfer.
420 * @param[in] i2c The pointer of the specified I2C module.
421 * @return None.
422 * @details Clear TXPDMAEN bit of I2C_CTL1 register to disable TX PDMA transfer function.
423 */
424 #define I2C_DISABLE_TX_PDMA(i2c) ((i2c)->CTL1 &= ~I2C_CTL1_TXPDMAEN_Msk)
425
426 /**
427 * @brief Enable PDMA stretch function.
428 * @param[in] i2c The pointer of the specified I2C module.
429 * @return None.
430 * @details Enable this function is to stretch bus by hardware after PDMA transfer is done if SI is not cleared.
431 */
432 #define I2C_ENABLE_PDMA_STRETCH(i2c) ((i2c)->CTL1 |= I2C_CTL1_PDMASTR_Msk)
433
434 /**
435 * @brief Disable PDMA stretch function.
436 * @param[in] i2c The pointer of the specified I2C module.
437 * @return None.
438 * @details I2C wil send STOP after PDMA transfers done automatically.
439 */
440 #define I2C_DISABLE_PDMA_STRETCH(i2c) ((i2c)->CTL1 &= ~I2C_CTL1_PDMASTR_Msk)
441
442 /**
443 * @brief Reset PDMA function.
444 * @param[in] i2c The pointer of the specified I2C module.
445 * @return None.
446 * @details I2C PDMA engine will be reset after this function is called.
447 */
448 #define I2C_DISABLE_RST_PDMA(i2c) ((i2c)->CTL1 |= I2C_CTL1_PDMARST_Msk)
449
450 /*---------------------------------------------------------------------------------------------------------*/
451 /* inline functions */
452 /*---------------------------------------------------------------------------------------------------------*/
453 static __INLINE void I2C_STOP(I2C_T *i2c);
454
455 /**
456 * @brief The macro is used to set STOP condition of I2C Bus
457 *
458 * @param[in] i2c Specify I2C port
459 *
460 * @return None
461 *
462 * @details Set the I2C bus STOP condition in I2C_CTL register.
463 */
I2C_STOP(I2C_T * i2c)464 static __INLINE void I2C_STOP(I2C_T *i2c)
465 {
466
467 (i2c)->CTL0 |= (I2C_CTL0_SI_Msk | I2C_CTL0_STO_Msk);
468 while(i2c->CTL0 & I2C_CTL0_STO_Msk) {}
469 }
470
471
472 void I2C_ClearTimeoutFlag(I2C_T *i2c);
473 void I2C_Close(I2C_T *i2c);
474 void I2C_Trigger(I2C_T *i2c, uint8_t u8Start, uint8_t u8Stop, uint8_t u8Si, uint8_t u8Ack);
475 void I2C_DisableInt(I2C_T *i2c);
476 void I2C_EnableInt(I2C_T *i2c);
477 uint32_t I2C_GetBusClockFreq(I2C_T *i2c);
478 uint32_t I2C_GetIntFlag(I2C_T *i2c);
479 uint32_t I2C_GetStatus(I2C_T *i2c);
480 uint32_t I2C_Open(I2C_T *i2c, uint32_t u32BusClock);
481 uint8_t I2C_GetData(I2C_T *i2c);
482 void I2C_SetSlaveAddr(I2C_T *i2c, uint8_t u8SlaveNo, uint8_t u8SlaveAddr, uint8_t u8GCMode);
483 void I2C_SetSlaveAddrMask(I2C_T *i2c, uint8_t u8SlaveNo, uint8_t u8SlaveAddrMask);
484 uint32_t I2C_SetBusClockFreq(I2C_T *i2c, uint32_t u32BusClock);
485 void I2C_EnableTimeout(I2C_T *i2c, uint8_t u8LongTimeout);
486 void I2C_DisableTimeout(I2C_T *i2c);
487 void I2C_EnableWakeup(I2C_T *i2c);
488 void I2C_DisableWakeup(I2C_T *i2c);
489 void I2C_SetData(I2C_T *i2c, uint8_t u8Data);
490 uint8_t I2C_WriteByte(I2C_T *i2c, uint8_t u8SlaveAddr, uint8_t u8Data);
491 uint32_t I2C_WriteMultiBytes(I2C_T *i2c, uint8_t u8SlaveAddr, uint8_t au8Data[], uint32_t u32wLen);
492 uint8_t I2C_WriteByteOneReg(I2C_T *i2c, uint8_t u8SlaveAddr, uint8_t u8DataAddr, uint8_t u8Data);
493 uint32_t I2C_WriteMultiBytesOneReg(I2C_T *i2c, uint8_t u8SlaveAddr, uint8_t u8DataAddr, uint8_t au8Data[], uint32_t u32wLen);
494 uint8_t I2C_WriteByteTwoRegs(I2C_T *i2c, uint8_t u8SlaveAddr, uint16_t u16DataAddr, uint8_t u8Data);
495 uint32_t I2C_WriteMultiBytesTwoRegs(I2C_T *i2c, uint8_t u8SlaveAddr, uint16_t u16DataAddr, uint8_t au8Data[], uint32_t u32wLen);
496 uint8_t I2C_ReadByte(I2C_T *i2c, uint8_t u8SlaveAddr);
497 uint32_t I2C_ReadMultiBytes(I2C_T *i2c, uint8_t u8SlaveAddr, uint8_t au8Rdata[], uint32_t u32rLen);
498 uint8_t I2C_ReadByteOneReg(I2C_T *i2c, uint8_t u8SlaveAddr, uint8_t u8DataAddr);
499 uint32_t I2C_ReadMultiBytesOneReg(I2C_T *i2c, uint8_t u8SlaveAddr, uint8_t u8DataAddr, uint8_t au8Rdata[], uint32_t u32rLen);
500 uint8_t I2C_ReadByteTwoRegs(I2C_T *i2c, uint8_t u8SlaveAddr, uint16_t u16DataAddr);
501 uint32_t I2C_ReadMultiBytesTwoRegs(I2C_T *i2c, uint8_t u8SlaveAddr, uint16_t u16DataAddr, uint8_t au8Rdata[], uint32_t u32rLen);
502 uint32_t I2C_SMBusGetStatus(I2C_T *i2c);
503 void I2C_SMBusClearInterruptFlag(I2C_T *i2c, uint8_t u8ClrSMBusIntFlag);
504 void I2C_SMBusSetPacketByteCount(I2C_T *i2c, uint32_t u32PktSize);
505 void I2C_SMBusOpen(I2C_T *i2c, uint8_t u8HostDevice);
506 void I2C_SMBusClose(I2C_T *i2c);
507 void I2C_SMBusPECTxEnable(I2C_T *i2c, uint8_t u8PECTxEn);
508 uint8_t I2C_SMBusGetPECValue(I2C_T *i2c);
509 void I2C_SMBusIdleTimeout(I2C_T *i2c, uint32_t u32Us, uint32_t u32Hclk);
510 void I2C_SMBusTimeout(I2C_T *i2c, uint32_t ms, uint32_t u32Pclk);
511 void I2C_SMBusClockLoTimeout(I2C_T *i2c, uint32_t ms, uint32_t u32Pclk);
512
513 /**@}*/ /* end of group I2C_EXPORTED_FUNCTIONS */
514
515 /**@}*/ /* end of group I2C_Driver */
516
517 /**@}*/ /* end of group Standard_Driver */
518
519 #ifdef __cplusplus
520 }
521 #endif
522
523 #endif
524
