efm32_i2c.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483
  1. /***************************************************************************//**
  2. * @file
  3. * @brief Inter-intergrated circuit (I2C) peripheral API for EFM32.
  4. * @author Energy Micro AS
  5. * @version 1.3.0
  6. *******************************************************************************
  7. * @section License
  8. * <b>(C) Copyright 2010 Energy Micro AS, http://www.energymicro.com</b>
  9. *******************************************************************************
  10. *
  11. * This source code is the property of Energy Micro AS. The source and compiled
  12. * code may only be used on Energy Micro "EFM32" microcontrollers.
  13. *
  14. * This copyright notice may not be removed from the source code nor changed.
  15. *
  16. * DISCLAIMER OF WARRANTY/LIMITATION OF REMEDIES: Energy Micro AS has no
  17. * obligation to support this Software. Energy Micro AS is providing the
  18. * Software "AS IS", with no express or implied warranties of any kind,
  19. * including, but not limited to, any implied warranties of merchantability
  20. * or fitness for any particular purpose or warranties against infringement
  21. * of any proprietary rights of a third party.
  22. *
  23. * Energy Micro AS will not be liable for any consequential, incidental, or
  24. * special damages, or any other relief, or for any claim by any third party,
  25. * arising from your use of this Software.
  26. *
  27. ******************************************************************************/
  28. #ifndef __EFM32_I2C_H
  29. #define __EFM32_I2C_H
  30. #include <stdbool.h>
  31. #include "efm32.h"
  32. #ifdef __cplusplus
  33. extern "C" {
  34. #endif
  35. /***************************************************************************//**
  36. * @addtogroup EFM32_Library
  37. * @{
  38. ******************************************************************************/
  39. /***************************************************************************//**
  40. * @addtogroup I2C
  41. * @{
  42. ******************************************************************************/
  43. /*******************************************************************************
  44. ******************************* DEFINES ***********************************
  45. ******************************************************************************/
  46. /**
  47. * @brief
  48. * Standard mode max frequency assuming using 4:4 ratio for Nlow:Nhigh.
  49. * @details
  50. * From I2C specification: Min Tlow = 4.7us, min Thigh = 4.0us,
  51. * max Trise=1.0us, max Tfall=0.3us. Since ratio is 4:4, have to use
  52. * worst case value of Tlow or Thigh as base.
  53. *
  54. * 1/(Tlow + Thigh + 1us + 0.3us) = 1/(4.7 + 4.7 + 1.3)us = 93458Hz
  55. */
  56. #define I2C_FREQ_STANDARD_MAX 93500
  57. /**
  58. * @brief
  59. * Fast mode max frequency assuming using 6:3 ratio for Nlow:Nhigh.
  60. * @details
  61. * From I2C specification: Min Tlow = 1.3us, min Thigh = 0.6us,
  62. * max Trise=0.3us, max Tfall=0.3us. Since ratio is 6:3, have to use
  63. * worst case value of Tlow or 2xThigh as base.
  64. *
  65. * 1/(Tlow + Thigh + 0.3us + 0.3us) = 1/(1.3 + 0.65 + 0.6)us = 392157Hz
  66. */
  67. #define I2C_FREQ_FAST_MAX 392500
  68. /**
  69. * @brief
  70. * Fast mode+ max frequency assuming using 11:6 ratio for Nlow:Nhigh.
  71. * @details
  72. * From I2C specification: Min Tlow = 0.5us, min Thigh = 0.26us,
  73. * max Trise=0.012us, max Tfall=0.12us. Since ratio is 11:6, have to use
  74. * worst case value of Tlow or (11/6)xThigh as base.
  75. *
  76. * 1/(Tlow + Thigh + 0.12us + 0.12us) = 1/(0.5 + 0.273 + 0.24)us = 987167Hz
  77. */
  78. #define I2C_FREQ_FASTPLUS_MAX 987500
  79. /**
  80. * @brief
  81. * Indicate plain write sequence: S+ADDR(W)+DATA0+P.
  82. * @details
  83. * @li S - Start
  84. * @li ADDR(W) - address with W/R bit cleared
  85. * @li DATA0 - Data taken from buffer with index 0
  86. * @li P - Stop
  87. */
  88. #define I2C_FLAG_WRITE 0x0001
  89. /**
  90. * @brief
  91. * Indicate plain read sequence: S+ADDR(R)+DATA0+P.
  92. * @details
  93. * @li S - Start
  94. * @li ADDR(R) - address with W/R bit set
  95. * @li DATA0 - Data read into buffer with index 0
  96. * @li P - Stop
  97. */
  98. #define I2C_FLAG_READ 0x0002
  99. /**
  100. * @brief
  101. * Indicate combined write/read sequence: S+ADDR(W)+DATA0+Sr+ADDR(R)+DATA1+P.
  102. * @details
  103. * @li S - Start
  104. * @li Sr - Repeated start
  105. * @li ADDR(W) - address with W/R bit cleared
  106. * @li ADDR(R) - address with W/R bit set
  107. * @li DATAn - Data written from/read into buffer with index n
  108. * @li P - Stop
  109. */
  110. #define I2C_FLAG_WRITE_READ 0x0004
  111. /**
  112. * @brief
  113. * Indicate write sequence using two buffers: S+ADDR(W)+DATA0+DATA1+P.
  114. * @details
  115. * @li S - Start
  116. * @li ADDR(W) - address with W/R bit cleared
  117. * @li DATAn - Data written from buffer with index n
  118. * @li P - Stop
  119. */
  120. #define I2C_FLAG_WRITE_WRITE 0x0008
  121. /** Use 10 bit address. */
  122. #define I2C_FLAG_10BIT_ADDR 0x0010
  123. /*******************************************************************************
  124. ******************************** ENUMS ************************************
  125. ******************************************************************************/
  126. /** Clock low to high ratio settings. */
  127. typedef enum
  128. {
  129. i2cClockHLRStandard = _I2C_CTRL_CLHR_STANDARD, /**< Ratio is 4:4 */
  130. i2cClockHLRAsymetric = _I2C_CTRL_CLHR_ASYMMETRIC, /**< Ratio is 6:3 */
  131. i2cClockHLRFast = _I2C_CTRL_CLHR_FAST /**< Ratio is 11:3 */
  132. } I2C_ClockHLR_TypeDef;
  133. /** Return codes for single master mode transfer function. */
  134. typedef enum
  135. {
  136. /* In progress code (>0) */
  137. i2cTransferInProgress = 1, /**< Transfer in progress. */
  138. /* Complete code (=0) */
  139. i2cTransferDone = 0, /**< Transfer completed successfully. */
  140. /* Transfer error codes (<0) */
  141. i2cTransferNack = -1, /**< NACK received during transfer. */
  142. i2cTransferBusErr = -2, /**< Bus error during transfer (misplaced START/STOP). */
  143. i2cTransferArbLost = -3, /**< Arbitration lost during transfer. */
  144. i2cTransferUsageFault = -4, /**< Usage fault. */
  145. i2cTransferSwFault = -5 /**< SW fault. */
  146. } I2C_TransferReturn_TypeDef;
  147. /*******************************************************************************
  148. ******************************* STRUCTS ***********************************
  149. ******************************************************************************/
  150. /** I2C initialization structure. */
  151. typedef struct
  152. {
  153. /** Enable I2C peripheral when init completed. */
  154. bool enable;
  155. /** Set to master (true) or slave (false) mode */
  156. bool master;
  157. /**
  158. * I2C reference clock assumed when configuring bus frequency setup.
  159. * Set it to 0 if currently configurated reference clock shall be used
  160. * This parameter is only applicable if operating in master mode.
  161. */
  162. uint32_t refFreq;
  163. /**
  164. * (Max) I2C bus frequency to use. This parameter is only applicable
  165. * if operating in master mode.
  166. */
  167. uint32_t freq;
  168. /** Clock low/high ratio control. */
  169. I2C_ClockHLR_TypeDef clhr;
  170. } I2C_Init_TypeDef;
  171. /** Suggested default config for I2C init structure. */
  172. #define I2C_INIT_DEFAULT \
  173. { true, /* Enable when init done */ \
  174. true, /* Set to master mode */ \
  175. 0, /* Use currently configured reference clock */ \
  176. I2C_FREQ_STANDARD_MAX, /* Set to standard rate assuring being */ \
  177. /* within I2C spec */ \
  178. i2cClockHLRStandard /* Set to use 4:4 low/high duty cycle */ \
  179. }
  180. /**
  181. * @brief
  182. * Master mode transfer message structure used to define a complete
  183. * I2C transfer sequence (from start to stop).
  184. * @details
  185. * The structure allows for defining the following types of sequences,
  186. * please refer to defines for sequence details.
  187. * @li #I2C_FLAG_READ - data read into buf[0].data
  188. * @li #I2C_FLAG_WRITE - data written from buf[0].data
  189. * @li #I2C_FLAG_WRITE_READ - data written from buf[0].data and read
  190. * into buf[1].data
  191. * @li #I2C_FLAG_WRITE_WRITE - data written from buf[0].data and
  192. * buf[1].data
  193. */
  194. typedef struct
  195. {
  196. /**
  197. * @brief
  198. * Address to use after (repeated) start.
  199. * @details
  200. * Layout details, A = address bit, X = don't care bit (set to 0):
  201. * @li 7 bit address - use format AAAA AAAX.
  202. * @li 10 bit address - use format XXXX XAAX AAAA AAAA
  203. */
  204. uint16_t addr;
  205. /** Flags defining sequence type and details, see I2C_FLAG_... defines. */
  206. uint16_t flags;
  207. /**
  208. * Buffers used to hold data to send from or receive into depending
  209. * on sequence type.
  210. */
  211. struct
  212. {
  213. /** Buffer used for data to transmit/receive, must be @p len long. */
  214. uint8_t *data;
  215. /**
  216. * Number of bytes in @p data to send or receive. Notice that when
  217. * receiving data to this buffer, at least 1 byte must be received.
  218. * Setting @p len to 0 in the receive case is considered a usage fault.
  219. * Transmitting 0 bytes is legal, in which case only the address
  220. * is transmitted after the start condition.
  221. */
  222. uint16_t len;
  223. } buf[2];
  224. } I2C_TransferSeq_TypeDef;
  225. /*******************************************************************************
  226. ***************************** PROTOTYPES **********************************
  227. ******************************************************************************/
  228. uint32_t I2C_BusFreqGet(I2C_TypeDef *i2c);
  229. void I2C_BusFreqSet(I2C_TypeDef *i2c,
  230. uint32_t refFreq,
  231. uint32_t freq,
  232. I2C_ClockHLR_TypeDef type);
  233. void I2C_Enable(I2C_TypeDef *i2c, bool enable);
  234. void I2C_Init(I2C_TypeDef *i2c, const I2C_Init_TypeDef *init);
  235. /***************************************************************************//**
  236. * @brief
  237. * Clear one or more pending I2C interrupts.
  238. *
  239. * @param[in] i2c
  240. * Pointer to I2C peripheral register block.
  241. *
  242. * @param[in] flags
  243. * Pending I2C interrupt source to clear. Use a logical OR combination of
  244. * valid interrupt flags for the I2C module (I2C_IF_nnn).
  245. ******************************************************************************/
  246. static __INLINE void I2C_IntClear(I2C_TypeDef *i2c, uint32_t flags)
  247. {
  248. i2c->IFC = flags;
  249. }
  250. /***************************************************************************//**
  251. * @brief
  252. * Disable one or more I2C interrupts.
  253. *
  254. * @param[in] i2c
  255. * Pointer to I2C peripheral register block.
  256. *
  257. * @param[in] flags
  258. * I2C interrupt sources to disable. Use a logical OR combination of
  259. * valid interrupt flags for the I2C module (I2C_IF_nnn).
  260. ******************************************************************************/
  261. static __INLINE void I2C_IntDisable(I2C_TypeDef *i2c, uint32_t flags)
  262. {
  263. i2c->IEN &= ~(flags);
  264. }
  265. /***************************************************************************//**
  266. * @brief
  267. * Enable one or more I2C interrupts.
  268. *
  269. * @note
  270. * Depending on the use, a pending interrupt may already be set prior to
  271. * enabling the interrupt. Consider using I2C_IntClear() prior to enabling
  272. * if such a pending interrupt should be ignored.
  273. *
  274. * @param[in] i2c
  275. * Pointer to I2C peripheral register block.
  276. *
  277. * @param[in] flags
  278. * I2C interrupt sources to enable. Use a logical OR combination of
  279. * valid interrupt flags for the I2C module (I2C_IF_nnn).
  280. ******************************************************************************/
  281. static __INLINE void I2C_IntEnable(I2C_TypeDef *i2c, uint32_t flags)
  282. {
  283. i2c->IEN |= flags;
  284. }
  285. /***************************************************************************//**
  286. * @brief
  287. * Get pending I2C interrupt flags.
  288. *
  289. * @note
  290. * The event bits are not cleared by the use of this function.
  291. *
  292. * @param[in] i2c
  293. * Pointer to I2C peripheral register block.
  294. *
  295. * @return
  296. * I2C interrupt sources pending. A logical OR combination of valid
  297. * interrupt flags for the I2C module (I2C_IF_nnn).
  298. ******************************************************************************/
  299. static __INLINE uint32_t I2C_IntGet(I2C_TypeDef *i2c)
  300. {
  301. return(i2c->IF);
  302. }
  303. /***************************************************************************//**
  304. * @brief
  305. * Set one or more pending I2C interrupts from SW.
  306. *
  307. * @param[in] i2c
  308. * Pointer to I2C peripheral register block.
  309. *
  310. * @param[in] flags
  311. * I2C interrupt sources to set to pending. Use a logical OR combination of
  312. * valid interrupt flags for the I2C module (I2C_IF_nnn).
  313. ******************************************************************************/
  314. static __INLINE void I2C_IntSet(I2C_TypeDef *i2c, uint32_t flags)
  315. {
  316. i2c->IFS = flags;
  317. }
  318. void I2C_Reset(I2C_TypeDef *i2c);
  319. /***************************************************************************//**
  320. * @brief
  321. * Get slave address used for I2C peripheral (when operating in slave mode).
  322. *
  323. * @details
  324. * For 10 bit addressing mode, the address is split in two bytes, and only
  325. * the first byte setting is fetched, effectively only controlling the 2 most
  326. * significant bits of the 10 bit address. Full handling of 10 bit addressing
  327. * in slave mode requires additional SW handling.
  328. *
  329. * @param[in] i2c
  330. * Pointer to I2C peripheral register block.
  331. *
  332. * @return
  333. * I2C slave address in use. The 7 most significant bits define the actual
  334. * address, the least significant bit is reserved and always returned as 0.
  335. ******************************************************************************/
  336. static __INLINE uint8_t I2C_SlaveAddressGet(I2C_TypeDef *i2c)
  337. {
  338. return((uint8_t)(i2c->SADDR));
  339. }
  340. /***************************************************************************//**
  341. * @brief
  342. * Set slave address to use for I2C peripheral (when operating in slave mode).
  343. *
  344. * @details
  345. * For 10 bit addressing mode, the address is split in two bytes, and only
  346. * the first byte is set, effectively only controlling the 2 most significant
  347. * bits of the 10 bit address. Full handling of 10 bit addressing in slave
  348. * mode requires additional SW handling.
  349. *
  350. * @param[in] i2c
  351. * Pointer to I2C peripheral register block.
  352. *
  353. * @param[in] addr
  354. * I2C slave address to use. The 7 most significant bits define the actual
  355. * address, the least significant bit is reserved and always set to 0.
  356. ******************************************************************************/
  357. static __INLINE void I2C_SlaveAddressSet(I2C_TypeDef *i2c, uint8_t addr)
  358. {
  359. i2c->SADDR = (uint32_t) addr & 0xfe;
  360. }
  361. /***************************************************************************//**
  362. * @brief
  363. * Get slave address mask used for I2C peripheral (when operating in slave
  364. * mode).
  365. *
  366. * @details
  367. * The address mask defines how the comparator works. A bit position with
  368. * value 0 means that the corresponding slave address bit is ignored during
  369. * comparison (don't care). A bit position with value 1 means that the
  370. * corresponding slave address bit must match.
  371. *
  372. * For 10 bit addressing mode, the address is split in two bytes, and only
  373. * the mask for the first address byte is fetched, effectively only
  374. * controlling the 2 most significant bits of the 10 bit address.
  375. *
  376. * @param[in] i2c
  377. * Pointer to I2C peripheral register block.
  378. *
  379. * @return
  380. * I2C slave address mask in use. The 7 most significant bits define the
  381. * actual address mask, the least significant bit is reserved and always
  382. * returned as 0.
  383. ******************************************************************************/
  384. static __INLINE uint8_t I2C_SlaveAddressMaskGet(I2C_TypeDef *i2c)
  385. {
  386. return((uint8_t)(i2c->SADDRMASK));
  387. }
  388. /***************************************************************************//**
  389. * @brief
  390. * Set slave address mask used for I2C peripheral (when operating in slave
  391. * mode).
  392. *
  393. * @details
  394. * The address mask defines how the comparator works. A bit position with
  395. * value 0 means that the corresponding slave address bit is ignored during
  396. * comparison (don't care). A bit position with value 1 means that the
  397. * corresponding slave address bit must match.
  398. *
  399. * For 10 bit addressing mode, the address is split in two bytes, and only
  400. * the mask for the first address byte is set, effectively only controlling
  401. * the 2 most significant bits of the 10 bit address.
  402. *
  403. * @param[in] i2c
  404. * Pointer to I2C peripheral register block.
  405. *
  406. * @param[in] mask
  407. * I2C slave address mask to use. The 7 most significant bits define the
  408. * actual address mask, the least significant bit is reserved and should
  409. * be 0.
  410. ******************************************************************************/
  411. static __INLINE void I2C_SlaveAddressMaskSet(I2C_TypeDef *i2c, uint8_t mask)
  412. {
  413. i2c->SADDRMASK = (uint32_t) mask & 0xfe;
  414. }
  415. I2C_TransferReturn_TypeDef I2C_Transfer(I2C_TypeDef *i2c);
  416. I2C_TransferReturn_TypeDef I2C_TransferInit(I2C_TypeDef *i2c,
  417. I2C_TransferSeq_TypeDef *seq);
  418. /** @} (end addtogroup I2C) */
  419. /** @} (end addtogroup EFM32_Library) */
  420. #ifdef __cplusplus
  421. }
  422. #endif
  423. #endif /* __EFM32_I2C_H */