Driver_I2C.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  1. /* -----------------------------------------------------------------------------
  2. * Copyright (c) 2013-2014 ARM Ltd.
  3. *
  4. * This software is provided 'as-is', without any express or implied warranty.
  5. * In no event will the authors be held liable for any damages arising from
  6. * the use of this software. Permission is granted to anyone to use this
  7. * software for any purpose, including commercial applications, and to alter
  8. * it and redistribute it freely, subject to the following restrictions:
  9. *
  10. * 1. The origin of this software must not be misrepresented; you must not
  11. * claim that you wrote the original software. If you use this software in
  12. * a product, an acknowledgment in the product documentation would be
  13. * appreciated but is not required.
  14. *
  15. * 2. Altered source versions must be plainly marked as such, and must not be
  16. * misrepresented as being the original software.
  17. *
  18. * 3. This notice may not be removed or altered from any source distribution.
  19. *
  20. *
  21. * $Date: 9. May 2014
  22. * $Revision: V2.02
  23. *
  24. * Project: I2C (Inter-Integrated Circuit) Driver definitions
  25. * -------------------------------------------------------------------------- */
  26. /* History:
  27. * Version 2.02
  28. * Removed function ARM_I2C_MasterTransfer in order to simplify drivers
  29. * and added back parameter "xfer_pending" to functions
  30. * ARM_I2C_MasterTransmit and ARM_I2C_MasterReceive
  31. * Version 2.01
  32. * Added function ARM_I2C_MasterTransfer and removed parameter "xfer_pending"
  33. * from functions ARM_I2C_MasterTransmit and ARM_I2C_MasterReceive
  34. * Added function ARM_I2C_GetDataCount
  35. * Removed flag "address_nack" from ARM_I2C_STATUS
  36. * Replaced events ARM_I2C_EVENT_MASTER_DONE and ARM_I2C_EVENT_SLAVE_DONE
  37. * with event ARM_I2C_EVENT_TRANSFER_DONE
  38. * Added event ARM_I2C_EVENT_TRANSFER_INCOMPLETE
  39. * Removed parameter "arg" from function ARM_I2C_SignalEvent
  40. * Version 2.00
  41. * New simplified driver:
  42. * complexity moved to upper layer (especially data handling)
  43. * more unified API for different communication interfaces
  44. * Added:
  45. * Slave Mode
  46. * Changed prefix ARM_DRV -> ARM_DRIVER
  47. * Version 1.10
  48. * Namespace prefix ARM_ added
  49. * Version 1.00
  50. * Initial release
  51. */
  52. #ifndef __DRIVER_I2C_H
  53. #define __DRIVER_I2C_H
  54. #include "Driver_Common.h"
  55. #define ARM_I2C_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,02) /* API version */
  56. /****** I2C Control Codes *****/
  57. #define ARM_I2C_OWN_ADDRESS (0x01) ///< Set Own Slave Address; arg = address
  58. #define ARM_I2C_BUS_SPEED (0x02) ///< Set Bus Speed; arg = speed
  59. #define ARM_I2C_BUS_CLEAR (0x03) ///< Execute Bus clear: send nine clock pulses
  60. #define ARM_I2C_ABORT_TRANSFER (0x04) ///< Abort Master/Slave Transmit/Receive
  61. /*----- I2C Bus Speed -----*/
  62. #define ARM_I2C_BUS_SPEED_STANDARD (0x01) ///< Standard Speed (100kHz)
  63. #define ARM_I2C_BUS_SPEED_FAST (0x02) ///< Fast Speed (400kHz)
  64. #define ARM_I2C_BUS_SPEED_FAST_PLUS (0x03) ///< Fast+ Speed ( 1MHz)
  65. #define ARM_I2C_BUS_SPEED_HIGH (0x04) ///< High Speed (3.4MHz)
  66. /****** I2C Address Flags *****/
  67. #define ARM_I2C_ADDRESS_10BIT 0x0400 ///< 10-bit address flag
  68. #define ARM_I2C_ADDRESS_GC 0x8000 ///< General Call flag
  69. /**
  70. \brief I2C Status
  71. */
  72. typedef struct _ARM_I2C_STATUS {
  73. uint32_t busy : 1; ///< Busy flag
  74. uint32_t mode : 1; ///< Mode: 0=Slave, 1=Master
  75. uint32_t direction : 1; ///< Direction: 0=Transmitter, 1=Receiver
  76. uint32_t general_call : 1; ///< General Call indication (cleared on start of next Slave operation)
  77. uint32_t arbitration_lost : 1; ///< Master lost arbitration (cleared on start of next Master operation)
  78. uint32_t bus_error : 1; ///< Bus error detected (cleared on start of next Master/Slave operation)
  79. } ARM_I2C_STATUS;
  80. /****** I2C Event *****/
  81. #define ARM_I2C_EVENT_TRANSFER_DONE (1UL << 0) ///< Master/Slave Transmit/Receive finished
  82. #define ARM_I2C_EVENT_TRANSFER_INCOMPLETE (1UL << 1) ///< Master/Slave Transmit/Receive incomplete transfer
  83. #define ARM_I2C_EVENT_SLAVE_TRANSMIT (1UL << 2) ///< Slave Transmit operation requested
  84. #define ARM_I2C_EVENT_SLAVE_RECEIVE (1UL << 3) ///< Slave Receive operation requested
  85. #define ARM_I2C_EVENT_ADDRESS_NACK (1UL << 4) ///< Address not acknowledged from Slave
  86. #define ARM_I2C_EVENT_GENERAL_CALL (1UL << 5) ///< General Call indication
  87. #define ARM_I2C_EVENT_ARBITRATION_LOST (1UL << 6) ///< Master lost arbitration
  88. #define ARM_I2C_EVENT_BUS_ERROR (1UL << 7) ///< Bus error detected (START/STOP at illegal position)
  89. #define ARM_I2C_EVENT_BUS_CLEAR (1UL << 8) ///< Bus clear finished
  90. // Function documentation
  91. /**
  92. \fn ARM_DRIVER_VERSION ARM_I2C_GetVersion (void)
  93. \brief Get driver version.
  94. \return \ref ARM_DRIVER_VERSION
  95. \fn ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities (void)
  96. \brief Get driver capabilities.
  97. \return \ref ARM_I2C_CAPABILITIES
  98. \fn int32_t ARM_I2C_Initialize (ARM_I2C_SignalEvent_t cb_event)
  99. \brief Initialize I2C Interface.
  100. \param[in] cb_event Pointer to \ref ARM_I2C_SignalEvent
  101. \return \ref execution_status
  102. \fn int32_t ARM_I2C_Uninitialize (void)
  103. \brief De-initialize I2C Interface.
  104. \return \ref execution_status
  105. \fn int32_t ARM_I2C_PowerControl (ARM_POWER_STATE state)
  106. \brief Control I2C Interface Power.
  107. \param[in] state Power state
  108. \return \ref execution_status
  109. \fn int32_t ARM_I2C_MasterTransmit (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending)
  110. \brief Start transmitting data as I2C Master.
  111. \param[in] addr Slave address (7-bit or 10-bit)
  112. \param[in] data Pointer to buffer with data to transmit to I2C Slave
  113. \param[in] num Number of data bytes to transmit
  114. \param[in] xfer_pending Transfer operation is pending - Stop condition will not be generated
  115. \return \ref execution_status
  116. \fn int32_t ARM_I2C_MasterReceive (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending)
  117. \brief Start receiving data as I2C Master.
  118. \param[in] addr Slave address (7-bit or 10-bit)
  119. \param[out] data Pointer to buffer for data to receive from I2C Slave
  120. \param[in] num Number of data bytes to receive
  121. \param[in] xfer_pending Transfer operation is pending - Stop condition will not be generated
  122. \return \ref execution_status
  123. \fn int32_t ARM_I2C_SlaveTransmit (const uint8_t *data, uint32_t num)
  124. \brief Start transmitting data as I2C Slave.
  125. \param[in] data Pointer to buffer with data to transmit to I2C Master
  126. \param[in] num Number of data bytes to transmit
  127. \return \ref execution_status
  128. \fn int32_t ARM_I2C_SlaveReceive (uint8_t *data, uint32_t num)
  129. \brief Start receiving data as I2C Slave.
  130. \param[out] data Pointer to buffer for data to receive from I2C Master
  131. \param[in] num Number of data bytes to receive
  132. \return \ref execution_status
  133. \fn int32_t ARM_I2C_GetDataCount (void)
  134. \brief Get transferred data count.
  135. \return number of data bytes transferred; -1 when Slave is not addressed by Master
  136. \fn int32_t ARM_I2C_Control (uint32_t control, uint32_t arg)
  137. \brief Control I2C Interface.
  138. \param[in] control Operation
  139. \param[in] arg Argument of operation (optional)
  140. \return \ref execution_status
  141. \fn ARM_I2C_STATUS ARM_I2C_GetStatus (void)
  142. \brief Get I2C status.
  143. \return I2C status \ref ARM_I2C_STATUS
  144. \fn void ARM_I2C_SignalEvent (uint32_t event)
  145. \brief Signal I2C Events.
  146. \param[in] event \ref I2C_events notification mask
  147. */
  148. typedef void (*ARM_I2C_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_I2C_SignalEvent : Signal I2C Event.
  149. /**
  150. \brief I2C Driver Capabilities.
  151. */
  152. typedef struct _ARM_I2C_CAPABILITIES {
  153. uint32_t address_10_bit : 1; ///< supports 10-bit addressing
  154. } ARM_I2C_CAPABILITIES;
  155. /**
  156. \brief Access structure of the I2C Driver.
  157. */
  158. typedef struct _ARM_DRIVER_I2C {
  159. ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_I2C_GetVersion : Get driver version.
  160. ARM_I2C_CAPABILITIES (*GetCapabilities)(void); ///< Pointer to \ref ARM_I2C_GetCapabilities : Get driver capabilities.
  161. int32_t (*Initialize) (ARM_I2C_SignalEvent_t cb_event); ///< Pointer to \ref ARM_I2C_Initialize : Initialize I2C Interface.
  162. int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_I2C_Uninitialize : De-initialize I2C Interface.
  163. int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_I2C_PowerControl : Control I2C Interface Power.
  164. int32_t (*MasterTransmit) (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending); ///< Pointer to \ref ARM_I2C_MasterTransmit : Start transmitting data as I2C Master.
  165. int32_t (*MasterReceive) (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending); ///< Pointer to \ref ARM_I2C_MasterReceive : Start receiving data as I2C Master.
  166. int32_t (*SlaveTransmit) ( const uint8_t *data, uint32_t num); ///< Pointer to \ref ARM_I2C_SlaveTransmit : Start transmitting data as I2C Slave.
  167. int32_t (*SlaveReceive) ( uint8_t *data, uint32_t num); ///< Pointer to \ref ARM_I2C_SlaveReceive : Start receiving data as I2C Slave.
  168. int32_t (*GetDataCount) (void); ///< Pointer to \ref ARM_I2C_GetDataCount : Get transferred data count.
  169. int32_t (*Control) (uint32_t control, uint32_t arg); ///< Pointer to \ref ARM_I2C_Control : Control I2C Interface.
  170. ARM_I2C_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_I2C_GetStatus : Get I2C status.
  171. } const ARM_DRIVER_I2C;
  172. #endif /* __DRIVER_I2C_H */