IxI2cDrv.h 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843
  1. /**
  2. * @file IxI2cDrv.h
  3. *
  4. * @brief Header file for the IXP400 I2C Driver (IxI2cDrv)
  5. *
  6. * @version $Revision: 0.1 $
  7. *
  8. * @par
  9. * IXP400 SW Release version 2.0
  10. *
  11. * -- Copyright Notice --
  12. *
  13. * @par
  14. * Copyright 2001-2005, Intel Corporation.
  15. * All rights reserved.
  16. *
  17. * @par
  18. * SPDX-License-Identifier: BSD-3-Clause
  19. * @par
  20. * -- End of Copyright Notice --
  21. */
  22. /**
  23. * @defgroup IxI2cDrv IXP400 I2C Driver(IxI2cDrv) API
  24. *
  25. * @brief IXP400 I2C Driver Public API
  26. *
  27. * @{
  28. */
  29. #ifndef IXI2CDRV_H
  30. #define IXI2CDRV_H
  31. #ifdef __ixp46X
  32. #include "IxOsal.h"
  33. /*
  34. * Section for #define
  35. */
  36. /**
  37. * @ingroup IxI2cDrv
  38. * @brief The interval of micro/mili seconds the IXP will wait before it polls for
  39. * status from the ixI2cIntrXferStatus; Every 20us is 1 byte @
  40. * 400Kbps and 4 bytes @ 100Kbps. This is dependent on delay type selected
  41. * through the API ixI2cDrvDelayTypeSelect.
  42. */
  43. #define IX_I2C_US_POLL_FOR_XFER_STATUS 20
  44. /**
  45. * @ingroup IxI2cDrv
  46. * @brief The number of tries that will be attempted to call a callback
  47. * function if the callback does not or is unable to resolve the
  48. * issue it is called to resolve
  49. */
  50. #define IX_I2C_NUM_OF_TRIES_TO_CALL_CALLBACK_FUNC 10
  51. /**
  52. * @ingroup IxI2cDrv
  53. * @brief Number of tries slave will poll the IDBR Rx full bit before it
  54. * gives up
  55. */
  56. #define IX_I2C_NUM_TO_POLL_IDBR_RX_FULL 0x100
  57. /**
  58. * @ingroup IxI2cDrv
  59. * @brief Number of tries slave will poll the IDBR Tx empty bit before it
  60. * gives up
  61. */
  62. #define IX_I2C_NUM_TO_POLL_IDBR_TX_EMPTY 0x100
  63. /*
  64. * Section for enum
  65. */
  66. /**
  67. * @ingroup IxI2cDrv
  68. *
  69. * @enum IxI2cMasterStatus
  70. *
  71. * @brief The master status - transfer complete, bus error or arbitration loss
  72. */
  73. typedef enum
  74. {
  75. IX_I2C_MASTER_XFER_COMPLETE = IX_SUCCESS,
  76. IX_I2C_MASTER_XFER_BUS_ERROR,
  77. IX_I2C_MASTER_XFER_ARB_LOSS
  78. } IxI2cMasterStatus;
  79. /**
  80. * @ingroup IxI2cDrv
  81. *
  82. * @enum IX_I2C_STATUS
  83. *
  84. * @brief The status that can be returned in a I2C driver initialization
  85. */
  86. typedef enum
  87. {
  88. IX_I2C_SUCCESS = IX_SUCCESS, /**< Success status */
  89. IX_I2C_FAIL, /**< Fail status */
  90. IX_I2C_NOT_SUPPORTED, /**< hardware does not have dedicated I2C hardware */
  91. IX_I2C_NULL_POINTER, /**< parameter passed in is NULL */
  92. IX_I2C_INVALID_SPEED_MODE_ENUM_VALUE, /**< speed mode selected is invalid */
  93. IX_I2C_INVALID_FLOW_MODE_ENUM_VALUE, /**< flow mode selected is invalid */
  94. IX_I2C_SLAVE_ADDR_CB_MISSING, /**< slave callback is NULL */
  95. IX_I2C_GEN_CALL_CB_MISSING, /**< general callback is NULL */
  96. IX_I2C_INVALID_SLAVE_ADDR, /**< invalid slave address specified */
  97. IX_I2C_INT_BIND_FAIL, /**< interrupt bind fail */
  98. IX_I2C_INT_UNBIND_FAIL, /**< interrupt unbind fail */
  99. IX_I2C_NOT_INIT, /**< I2C is not initialized yet */
  100. IX_I2C_MASTER_BUS_BUSY, /**< master detected a I2C bus busy */
  101. IX_I2C_MASTER_ARB_LOSS, /**< master experienced arbitration loss */
  102. IX_I2C_MASTER_XFER_ERROR, /**< master experienced a transfer error */
  103. IX_I2C_MASTER_BUS_ERROR, /**< master detected a I2C bus error */
  104. IX_I2C_MASTER_NO_BUFFER, /**< no buffer provided for master transfer */
  105. IX_I2C_MASTER_INVALID_XFER_MODE, /**< xfer mode selected is invalid */
  106. IX_I2C_SLAVE_ADDR_NOT_DETECTED, /**< polled slave addr not detected */
  107. IX_I2C_GEN_CALL_ADDR_DETECTED, /**< polling detected general call */
  108. IX_I2C_SLAVE_READ_DETECTED, /**< polling detected slave read request */
  109. IX_I2C_SLAVE_WRITE_DETECTED, /**< polling detected slave write request */
  110. IX_I2C_SLAVE_NO_BUFFER, /**< no buffer provided for slave transfers */
  111. IX_I2C_DATA_SIZE_ZERO, /**< data size transfer is zero - invalid */
  112. IX_I2C_SLAVE_WRITE_BUFFER_EMPTY, /**< slave buffer is used till empty */
  113. IX_I2C_SLAVE_WRITE_ERROR, /**< slave write experienced an error */
  114. IX_I2C_SLAVE_OR_GEN_READ_BUFFER_FULL, /**< slave buffer is filled up */
  115. IX_I2C_SLAVE_OR_GEN_READ_ERROR /**< slave read experienced an error */
  116. } IX_I2C_STATUS;
  117. /**
  118. * @ingroup IxI2cDrv
  119. *
  120. * @enum IxI2cSpeedMode
  121. *
  122. * @brief Type of speed modes supported by the I2C hardware.
  123. */
  124. typedef enum
  125. {
  126. IX_I2C_NORMAL_MODE = 0x0,
  127. IX_I2C_FAST_MODE
  128. } IxI2cSpeedMode;
  129. /**
  130. * @ingroup IxI2cDrv
  131. *
  132. * @enum IxI2cXferMode
  133. *
  134. * @brief Used for indicating it is a repeated start or normal transfer
  135. */
  136. typedef enum
  137. {
  138. IX_I2C_NORMAL = 0x0,
  139. IX_I2C_REPEATED_START
  140. } IxI2cXferMode;
  141. /**
  142. * @ingroup IxI2cDrv
  143. *
  144. * @enum IxI2cFlowMode
  145. *
  146. * @brief Used for indicating it is a poll or interrupt mode
  147. */
  148. typedef enum
  149. {
  150. IX_I2C_POLL_MODE = 0x0,
  151. IX_I2C_INTERRUPT_MODE
  152. } IxI2cFlowMode;
  153. /**
  154. * @ingroup IxI2cDrv
  155. *
  156. * @enum IxI2cDelayMode
  157. *
  158. * @brief Used for selecting looping delay or OS scheduler delay
  159. */
  160. typedef enum
  161. {
  162. IX_I2C_LOOP_DELAY = 1, /**< delay in microseconds */
  163. IX_I2C_SCHED_DELAY /**< delay in miliseconds */
  164. } IxI2cDelayMode;
  165. /**
  166. * @ingroup IxI2cDrv
  167. *
  168. * @brief The pointer to the function that will be called when the master
  169. * has completed its receive. The parameter that is passed will
  170. * provide the status of the read (success, arb loss, or bus
  171. * error), the transfer mode (normal or repeated start, the
  172. * buffer pointer and number of bytes transferred.
  173. */
  174. typedef void (*IxI2cMasterReadCallbackP)(IxI2cMasterStatus, IxI2cXferMode, char*, UINT32);
  175. /**
  176. * @ingroup IxI2cDrv
  177. *
  178. * @brief The pointer to the function that will be called when the master
  179. * has completed its transmit. The parameter that is passed will
  180. * provide the status of the write (success, arb loss, or buss
  181. * error), the transfer mode (normal or repeated start), the
  182. * buffer pointer and number of bytes transferred.
  183. */
  184. typedef void (*IxI2cMasterWriteCallbackP)(IxI2cMasterStatus, IxI2cXferMode, char*, UINT32);
  185. /**
  186. * @ingroup IxI2cDrv
  187. *
  188. * @brief The pointer to the function that will be called when a slave
  189. * address detected in interrupt mode for a read. The parameters
  190. * that is passed will provide the read status, buffer pointer,
  191. * buffer size, and the bytes received. When a start of a read
  192. * is initiated there will be no buffer allocated and this callback
  193. * will be called to request for a buffer. While receiving, if the
  194. * buffer gets filled, this callback will be called to request for
  195. * a new buffer while sending the filled buffer's pointer and size,
  196. * and data size received. When the receive is complete, this
  197. * callback will be called to process the data and free the memory
  198. * by passing the buffer's pointer and size, and data size received.
  199. */
  200. typedef void (*IxI2cSlaveReadCallbackP)(IX_I2C_STATUS, char*, UINT32, UINT32);
  201. /**
  202. * @ingroup IxI2cDrv
  203. *
  204. * @brief The pointer to the function that will be called when a slave
  205. * address detected in interrupt mode for a write. The parameters
  206. * that is passed will provide the write status, buffer pointer,
  207. * buffer size, and the bytes received. When a start of a write is
  208. * initiated there will be no buffer allocated and this callback
  209. * will be called to request for a buffer and to fill it with data.
  210. * While transmitting, if the data in the buffer empties, this
  211. * callback will be called to request for more data to be filled in
  212. * the same or new buffer. When the transmit is complete, this
  213. * callback will be called to free the memory or other actions to
  214. * be taken.
  215. */
  216. typedef void (*IxI2cSlaveWriteCallbackP)(IX_I2C_STATUS, char*, UINT32, UINT32);
  217. /**
  218. * @ingroup IxI2cDrv
  219. *
  220. * @brief The pointer to the function that will be called when a general
  221. * call detected in interrupt mode for a read. The parameters that
  222. * is passed will provide the read status, buffer pointer, buffer
  223. * size, and the bytes received. When a start of a read is
  224. * initiated there will be no buffer allocated and this callback
  225. * will be called to request for a buffer. While receiving, if the
  226. * buffer gets filled, this callback will be called to request for
  227. * a new buffer while sending the filled buffer's pointer and size,
  228. * and data size received. When the receive is complete, this
  229. * callback will be called to process the data and free the memory
  230. * by passing the buffer's pointer and size, and data size received.
  231. */
  232. typedef void (*IxI2cGenCallCallbackP)(IX_I2C_STATUS, char*, UINT32, UINT32);
  233. /*
  234. * Section for struct
  235. */
  236. /**
  237. * @brief contains all the variables required to initialize the I2C unit
  238. *
  239. * Structure to be filled and used for calling initialization
  240. */
  241. typedef struct
  242. {
  243. IxI2cSpeedMode I2cSpeedSelect; /**<Select either normal (100kbps)
  244. or fast mode (400kbps)*/
  245. IxI2cFlowMode I2cFlowSelect; /**<Select interrupt or poll mode*/
  246. IxI2cMasterReadCallbackP MasterReadCBP;
  247. /**<The master read callback pointer */
  248. IxI2cMasterWriteCallbackP MasterWriteCBP;
  249. /**<The master write callback pointer */
  250. IxI2cSlaveReadCallbackP SlaveReadCBP;
  251. /**<The slave read callback pointer */
  252. IxI2cSlaveWriteCallbackP SlaveWriteCBP;
  253. /**<The slave write callback pointer */
  254. IxI2cGenCallCallbackP GenCallCBP;
  255. /**<The general call callback pointer */
  256. BOOL I2cGenCallResponseEnable; /**<Enable/disable the unit to
  257. respond to generall calls.*/
  258. BOOL I2cSlaveAddrResponseEnable;/**<Enable/disable the unit to
  259. respond to the slave address set in
  260. ISAR*/
  261. BOOL SCLEnable; /**<Enable/disable the unit from
  262. driving the SCL line during master
  263. mode operation*/
  264. UINT8 I2cHWAddr; /**<The address the unit will
  265. response to as a slave device*/
  266. } IxI2cInitVars;
  267. /**
  268. * @brief contains results of counters and their overflow
  269. *
  270. * Structure contains all values of counters and associated overflows.
  271. */
  272. typedef struct
  273. {
  274. UINT32 ixI2cMasterXmitCounter; /**<Total bytes transmitted as
  275. master.*/
  276. UINT32 ixI2cMasterFailedXmitCounter; /**<Total bytes failed for
  277. transmission as master.*/
  278. UINT32 ixI2cMasterRcvCounter; /**<Total bytes received as
  279. master.*/
  280. UINT32 ixI2cMasterFailedRcvCounter; /**<Total bytes failed for
  281. receival as master.*/
  282. UINT32 ixI2cSlaveXmitCounter; /**<Total bytes transmitted as
  283. slave.*/
  284. UINT32 ixI2cSlaveFailedXmitCounter; /**<Total bytes failed for
  285. transmission as slave.*/
  286. UINT32 ixI2cSlaveRcvCounter; /**<Total bytes received as
  287. slave.*/
  288. UINT32 ixI2cSlaveFailedRcvCounter; /**<Total bytes failed for
  289. receival as slave.*/
  290. UINT32 ixI2cGenAddrCallSucceedCounter; /**<Total bytes successfully
  291. transmitted for general address.*/
  292. UINT32 ixI2cGenAddrCallFailedCounter; /**<Total bytes failed transmission
  293. for general address.*/
  294. UINT32 ixI2cArbLossCounter; /**<Total instances of arbitration
  295. loss has occured.*/
  296. } IxI2cStatsCounters;
  297. /*
  298. * Section for prototypes interface functions
  299. */
  300. /**
  301. * @ingroup IxI2cDrv
  302. *
  303. * @fn ixI2cDrvInit(
  304. IxI2cInitVars *InitVarsSelected)
  305. *
  306. * @brief Initializes the I2C Driver.
  307. *
  308. * @param "IxI2cInitVars [in] *InitVarsSelected" - struct containing required
  309. * variables for initialization
  310. *
  311. * Global Data :
  312. * - None.
  313. *
  314. * This API will check if the hardware supports this I2C driver and the validity
  315. * of the parameters passed in. It will continue to process the parameters
  316. * passed in by setting the speed of the I2C unit (100kbps or 400kbps), setting
  317. * the flow to either interrupt or poll mode, setting the address of the I2C unit,
  318. * enabling/disabling the respond to General Calls, enabling/disabling the respond
  319. * to Slave Address and SCL line driving. If it is interrupt mode, then it will
  320. * register the callback routines for master, slavetransfer and general call receive.
  321. *
  322. * @return
  323. * - IX_I2C_SUCCESS - Successfully initialize and enable the I2C
  324. * hardware.
  325. * - IX_I2C_NOT_SUPPORTED - The hardware does not support or have a
  326. * dedicated I2C unit to support this driver
  327. * - IX_I2C_NULL_POINTER - The parameter passed in is a NULL pointed
  328. * - IX_I2C_INVALID_SPEED_MODE_ENUM_VALUE - The speed mode selected in the
  329. * InitVarsSelected is invalid
  330. * - IX_I2C_INVALID_FLOW_MODE_ENUM_VALUE - The flow mode selected in the
  331. * InitVarsSelected is invalid
  332. * - IX_I2C_INVALID_SLAVE_ADDR - The address 0x0 is reserved for
  333. * general call.
  334. * - IX_I2C_SLAVE_ADDR_CB_MISSING - interrupt mode is selected but
  335. * slave address callback pointer is NULL
  336. * - IX_I2C_GEN_CALL_CB_MISSING - interrupt mode is selected but
  337. * general call callback pointer is NULL
  338. * - IX_I2C_INT_BIND_FAIL - The ISR for the I2C failed to bind
  339. * - IX_I2C_INT_UNBIND_FAIL - The ISR for the I2C failed to unbind
  340. *
  341. * @li Reentrant : yes
  342. * @li ISR Callable : yes
  343. *
  344. */
  345. PUBLIC IX_I2C_STATUS
  346. ixI2cDrvInit(IxI2cInitVars *InitVarsSelected);
  347. /**
  348. * @ingroup IxI2cDrv
  349. *
  350. * @fn ixI2cDrvUninit(
  351. void)
  352. *
  353. * @brief Disables the I2C hardware
  354. *
  355. * @param - None
  356. *
  357. * Global Data :
  358. * - None.
  359. *
  360. * This API will disable the I2C hardware, unbind interrupt, and unmap memory.
  361. *
  362. * @return
  363. * - IX_I2C_SUCCESS - successfully un-initialized I2C
  364. * - IX_I2C_INT_UNBIND_FAIL - failed to unbind the I2C interrupt
  365. * - IX_I2C_NOT_INIT - I2C not init yet.
  366. *
  367. * @li Reentrant : yes
  368. * @li ISR Callable : yes
  369. *
  370. */
  371. PUBLIC IX_I2C_STATUS
  372. ixI2cDrvUninit(void);
  373. /**
  374. * @ingroup IxI2cDrv
  375. *
  376. * @fn ixI2cDrvSlaveAddrSet(
  377. UINT8 SlaveAddrSet)
  378. *
  379. * @brief Sets the I2C Slave Address
  380. *
  381. * @param "UINT8 [in] SlaveAddrSet" - Slave Address to be inserted into ISAR
  382. *
  383. * Global Data :
  384. * - None.
  385. *
  386. * This API will insert the SlaveAddrSet into the ISAR.
  387. *
  388. * @return
  389. * - IX_I2C_SUCCESS - successfuly set the slave addr
  390. * - IX_I2C_INVALID_SLAVE_ADDR - invalid slave address (zero) specified
  391. * - IX_I2C_NOT_INIT - I2C not init yet.
  392. *
  393. * @li Reentrant : yes
  394. * @li ISR Callable : yes
  395. *
  396. */
  397. PUBLIC IX_I2C_STATUS
  398. ixI2cDrvSlaveAddrSet(UINT8 SlaveAddrSet);
  399. /**
  400. * @ingroup IxI2cDrv
  401. *
  402. * @fn ixI2cDrvBusScan(
  403. void)
  404. *
  405. * @brief scans the I2C bus for slave devices
  406. *
  407. * @param - None
  408. *
  409. * Global Data :
  410. * - None.
  411. *
  412. * This API will prompt all slave addresses for a reply except its own
  413. *
  414. * @return
  415. * - IX_I2C_SUCCESS - found at least one slave device
  416. * - IX_I2C_FAIL - Fail to find even one slave device
  417. * - IX_I2C_BUS_BUSY - The I2C bus is busy (held by another I2C master)
  418. * - IX_I2C_ARB_LOSS - The I2C bus was loss to another I2C master
  419. * - IX_I2C_NOT_INIT - I2C not init yet.
  420. *
  421. * @li Reentrant : yes
  422. * @li ISR Callable : yes
  423. *
  424. */
  425. PUBLIC IX_I2C_STATUS
  426. ixI2cDrvBusScan(void);
  427. /**
  428. * @ingroup IxI2cDrv
  429. *
  430. * @fn ixI2cDrvWriteTransfer(
  431. UINT8 SlaveAddr,
  432. char *bufP,
  433. UINT32 dataSize,
  434. IxI2cXferMode XferModeSelect)
  435. *
  436. * @param "UINT8 [in] SlaveAddr" - The slave address to request data from.
  437. * @param "char [in] *bufP" - The pointer to the data to be transmitted.
  438. * @param "UINT32 [in] dataSize" - The number of bytes requested.
  439. * @param "IxI2cXferMode [in] XferModeSelect" - the transfer mode selected,
  440. * either repeated start (ends w/o stop) or normal (start and stop)
  441. *
  442. * Global Data :
  443. * - None.
  444. *
  445. * This API will try to obtain master control of the I2C bus and transmit the
  446. * number of bytes, specified by dataSize, to the user specified slave
  447. * address from the buffer pointer. It will use either interrupt or poll mode
  448. * depending on the method selected.
  449. *
  450. * If in interrupt mode and IxI2cMasterWriteCallbackP is not NULL, the driver
  451. * will initiate the transfer and return immediately. The function pointed to
  452. * by IxI2cMasterWriteCallbackP will be called in the interrupt service
  453. * handlers when the operation is complete.
  454. *
  455. * If in interrupt mode and IxI2cMasterWriteCallbackP is NULL, then the driver
  456. * will wait for the operation to complete, and then return.
  457. *
  458. * And if the repeated start transfer mode is selected, then it will not send a
  459. * stop signal at the end of all the transfers.
  460. * *NOTE*: If repeated start transfer mode is selected, it has to end with a
  461. * normal mode transfer mode else the bus will continue to be held
  462. * by the IXP.
  463. *
  464. * @return
  465. * - IX_I2C_SUCCESS - Successfuuly wrote data to slave.
  466. * - IX_I2C_MASTER_BUS_BUSY - The I2C bus is busy (held by another I2C master)
  467. * - IX_I2C_MASTER_ARB_LOSS - The I2C bus was loss to another I2C master
  468. * - IX_I2C_MASTER_XFER_ERROR - There was a transfer error
  469. * - IX_I2C_MASTER_BUS_ERROR - There was a bus error during transfer
  470. * - IX_I2C_MASTER_NO_BUFFER - buffer pointer is NULL
  471. * - IX_I2C_MASTER_INVALID_XFER_MODE - Xfer mode selected is invalid
  472. * - IX_I2C_DATA_SIZE_ZERO - dataSize passed in is zero, which is invalid
  473. * - IX_I2C_NOT_INIT - I2C not init yet.
  474. *
  475. * @li Reentrant : no
  476. * @li ISR Callable : no
  477. *
  478. */
  479. PUBLIC IX_I2C_STATUS
  480. ixI2cDrvWriteTransfer(
  481. UINT8 SlaveAddr,
  482. char *bufP,
  483. UINT32 dataSize,
  484. IxI2cXferMode XferModeSelect);
  485. /**
  486. * @ingroup IxI2cDrv
  487. *
  488. * @fn ixI2cDrvReadTransfer(
  489. UINT8 SlaveAddr,
  490. char *bufP,
  491. UINT32 dataSize,
  492. IxI2cXferMode XferModeSelect)
  493. *
  494. * @brief Initiates a transfer to receive bytes of data from a slave
  495. * device through the I2C bus.
  496. *
  497. * @param "UINT8 [in] SlaveAddr" - The slave address to request data from.
  498. * @param "char [out] *bufP" - The pointer to the buffer to store the
  499. * requested data.
  500. * @param "UINT32 [in] dataSize" - The number of bytes requested.
  501. * @param "IxI2cXferMode [in] XferModeSelect" - the transfer mode selected,
  502. * either repeated start (ends w/o stop) or normal (start and stop)
  503. *
  504. * Global Data :
  505. * - None.
  506. *
  507. * This API will try to obtain master control of the I2C bus and receive the
  508. * number of bytes, specified by dataSize, from the user specified address
  509. * into the receive buffer. It will use either interrupt or poll mode depending
  510. * on the mode selected.
  511. *
  512. * If in interrupt mode and IxI2cMasterReadCallbackP is not NULL, the driver
  513. * will initiate the transfer and return immediately. The function pointed to
  514. * by IxI2cMasterReadCallbackP will be called in the interrupt service
  515. * handlers when the operation is complete.
  516. *
  517. * If in interrupt mode and IxI2cMasterReadCallbackP is NULL, then the driver will
  518. * wait for the operation to complete, and then return.
  519. *
  520. * And if the repeated start transfer mode is selected, then it will not send a
  521. * stop signal at the end of all the transfers.
  522. * *NOTE*: If repeated start transfer mode is selected, it has to end with a
  523. * normal mode transfer mode else the bus will continue to be held
  524. * by the IXP.
  525. *
  526. * @return
  527. * - IX_I2C_SUCCESS - Successfuuly read slave data
  528. * - IX_I2C_MASTER_BUS_BUSY - The I2C bus is busy (held by another I2C master)
  529. * - IX_I2C_MASTER_ARB_LOSS - The I2C bus was loss to another I2C master
  530. * - IX_I2C_MASTER_XFER_ERROR - There was a bus error during transfer
  531. * - IX_I2C_MASTER_BUS_ERROR - There was a bus error during transfer
  532. * - IX_I2C_MASTER_NO_BUFFER - buffer pointer is NULL
  533. * - IX_I2C_MASTER_INVALID_XFER_MODE - Xfer mode selected is invalid
  534. * - IX_I2C_INVALID_SLAVE_ADDR - invalid slave address (zero) specified
  535. * - IX_I2C_DATA_SIZE_ZERO - dataSize passed in is zero, which is invalid
  536. * - IX_I2C_NOT_INIT - I2C not init yet.
  537. *
  538. * @li Reentrant : no
  539. * @li ISR Callable : no
  540. *
  541. */
  542. PUBLIC IX_I2C_STATUS
  543. ixI2cDrvReadTransfer(
  544. UINT8 SlaveAddr,
  545. char *bufP,
  546. UINT32 dataSize,
  547. IxI2cXferMode XferModeSelect);
  548. /**
  549. * @ingroup IxI2cDrv
  550. *
  551. * @fn ixI2cDrvSlaveAddrAndGenCallDetectedCheck(
  552. void)
  553. *
  554. * @brief Checks the I2C Status Register to determine if a slave address is
  555. * detected
  556. *
  557. * @param - None
  558. *
  559. * Global Data :
  560. * - None.
  561. *
  562. * This API is used in polled mode to determine if the I2C unit is requested
  563. * for a slave or general call transfer. If it is requested for a slave
  564. * transfer then it will determine if it is a general call (read only), read,
  565. * or write transfer requested.
  566. *
  567. * @return
  568. * - IX_I2C_SLAVE_ADDR_NOT_DETECTED - The I2C unit is not requested for slave
  569. * transfer
  570. * - IX_I2C_GEN_CALL_ADDR_DETECTED - The I2C unit is not requested for slave
  571. * transfer but for general call
  572. * - IX_I2C_SLAVE_READ_DETECTED - The I2C unit is requested for a read
  573. * - IX_I2C_SLAVE_WRITE_DETECTED - The I2C unit is requested for a write
  574. * - IX_I2C_NOT_INIT - I2C not init yet.
  575. *
  576. * @li Reentrant : no
  577. * @li ISR Callable : no
  578. *
  579. */
  580. PUBLIC IX_I2C_STATUS
  581. ixI2cDrvSlaveAddrAndGenCallDetectedCheck(void);
  582. /**
  583. * @ingroup IxI2cDrv
  584. *
  585. * @fn ixI2cDrvSlaveOrGenDataReceive(
  586. char *bufP,
  587. UINT32 bufSize,
  588. UINT32 *dataSizeRcvd)
  589. *
  590. * @brief Performs the slave receive or general call receive data transfer
  591. *
  592. * @param "char [in] *bufP" - the pointer to the buffer to store data
  593. * "UINT32 [in] bufSize" - the buffer size allocated
  594. * "UINT32 [in] *dataSizeRcvd" - the length of data received in bytes
  595. *
  596. * Global Data :
  597. * - None.
  598. *
  599. * This API is only used in polled mode to perform the slave read or general call
  600. * receive data. It will continuously store the data received into bufP until
  601. * complete or until bufP is full in which it will return
  602. * IX_I2C_SLAVE_OR_GEN_READ_BUFFER_FULL. If in interrupt mode, the callback will be
  603. * used.
  604. *
  605. * @return
  606. * - IX_I2C_SUCCESS - The I2C driver transferred the data successfully.
  607. * - IX_I2C_SLAVE_OR_GEN_READ_BUFFER_FULL - The I2C driver has ran out of
  608. * space to store the received data.
  609. * - IX_I2C_SLAVE_OR_GEN_READ_ERROR - The I2C driver didn't manage to
  610. * detect the IDBR Rx Full bit
  611. * - IX_I2C_DATA_SIZE_ZERO - bufSize passed in is zero, which is invalid
  612. * - IX_I2C_SLAVE_NO_BUFFER - buffer pointer is NULL
  613. * - IX_I2C_NULL_POINTER - dataSizeRcvd is NULL
  614. * - IX_I2C_NOT_INIT - I2C not init yet.
  615. *
  616. * @li Reentrant : no
  617. * @li ISR Callable : no
  618. *
  619. */
  620. PUBLIC IX_I2C_STATUS
  621. ixI2cDrvSlaveOrGenDataReceive(
  622. char *bufP,
  623. UINT32 bufSize,
  624. UINT32 *dataSizeRcvd);
  625. /**
  626. * @ingroup IxI2cDrv
  627. *
  628. * @fn ixI2cDrvSlaveDataTransmit(
  629. char *bufP,
  630. UINT32 dataSize,
  631. UINT32 *dataSizeXmtd)
  632. *
  633. * @brief Performs the slave write data transfer
  634. *
  635. * @param "char [in] *bufP" - the pointer to the buffer for data to be
  636. * transmitted
  637. * "UINT32 [in] bufSize" - the buffer size allocated
  638. * "UINT32 [in] *dataSizeRcvd" - the length of data trasnmitted in
  639. * bytes
  640. *
  641. * Global Data :
  642. * - None.
  643. *
  644. * This API is only used in polled mode to perform the slave transmit data. It
  645. * will continuously transmit the data from bufP until complete or until bufP
  646. * is empty in which it will return IX_I2C_SLAVE_WRITE_BUFFER_EMPTY. If in
  647. * interrupt mode, the callback will be used.
  648. *
  649. * @return
  650. * - IX_I2C_SUCCESS - The I2C driver transferred the data successfully.
  651. * - IX_I2C_SLAVE_WRITE_BUFFER_EMPTY - The I2C driver needs more data to
  652. * transmit.
  653. * - IX_I2C_SLAVE_WRITE_ERROR -The I2C driver didn't manage to detect the
  654. * IDBR Tx empty bit or the slave stop bit.
  655. * - IX_I2C_DATA_SIZE_ZERO - dataSize passed in is zero, which is invalid
  656. * - IX_I2C_SLAVE_NO_BUFFER - buffer pointer is NULL
  657. * - IX_I2C_NULL_POINTER - dataSizeXmtd is NULL
  658. * - IX_I2C_NOT_INIT - I2C not init yet.
  659. *
  660. * @li Reentrant : no
  661. * @li ISR Callable : no
  662. *
  663. */
  664. PUBLIC IX_I2C_STATUS
  665. ixI2cDrvSlaveDataTransmit(
  666. char *bufP,
  667. UINT32 dataSize,
  668. UINT32 *dataSizeXmtd);
  669. /**
  670. * @ingroup IxI2cDrv
  671. *
  672. * @fn ixI2cDrvSlaveOrGenCallBufReplenish(
  673. char *bufP,
  674. UINT32 bufSize)
  675. *
  676. * @brief Replenishes the buffer which stores buffer info for both slave and
  677. * general call
  678. *
  679. * @param "char [in] *bufP" - pointer to the buffer allocated
  680. * "UINT32 [in] bufSize" - size of the buffer
  681. *
  682. * Global Data :
  683. * - None.
  684. *
  685. * This API is only used in interrupt mode for replenishing the same buffer
  686. * that is used by both slave and generall call by updating the buffer info
  687. * with new info and clearing previous offsets set by previous transfers.
  688. *
  689. * @return
  690. * - None
  691. *
  692. * @li Reentrant : no
  693. * @li ISR Callable : no
  694. *
  695. */
  696. PUBLIC void
  697. ixI2cDrvSlaveOrGenCallBufReplenish(
  698. char *bufP,
  699. UINT32 bufSize);
  700. /**
  701. * @ingroup IxI2cDrv
  702. *
  703. * @fn ixI2cDrvStatsGet(IxI2cStatsCounters *I2cStats)
  704. *
  705. * @brief Returns the I2C Statistics through the pointer passed in
  706. *
  707. * @param - "IxI2cStatsCounters [out] *I2cStats" - I2C statistics counter will
  708. * be read and written to the location pointed by this pointer.
  709. *
  710. * Global Data :
  711. * - None.
  712. *
  713. * This API will return the statistics counters of the I2C driver.
  714. *
  715. * @return
  716. * - IX_I2C_NULL_POINTER - pointer passed in is NULL
  717. * - IX_I2C_SUCCESS - successfully obtained I2C statistics
  718. *
  719. * @li Reentrant : yes
  720. * @li ISR Callable : no
  721. *
  722. */
  723. PUBLIC IX_I2C_STATUS
  724. ixI2cDrvStatsGet(IxI2cStatsCounters *I2cStats);
  725. /**
  726. * @ingroup IxI2cDrv
  727. *
  728. * @fn ixI2cDrvStatsReset(void)
  729. *
  730. * @brief Reset I2C statistics counters.
  731. *
  732. * @param - None
  733. *
  734. * Global Data :
  735. * - None.
  736. *
  737. * This API will reset the statistics counters of the I2C driver.
  738. *
  739. * @return
  740. * - None
  741. *
  742. * @li Reentrant : yes
  743. * @li ISR Callable : no
  744. *
  745. */
  746. PUBLIC void
  747. ixI2cDrvStatsReset(void);
  748. /**
  749. * @ingroup IxI2cDrv
  750. *
  751. * @fn ixI2cDrvShow(void)
  752. *
  753. * @brief Displays the I2C status register and the statistics counter.
  754. *
  755. * @param - None
  756. *
  757. * Global Data :
  758. * - None.
  759. *
  760. * This API will display the I2C Status register and is useful if any error
  761. * occurs. It displays the detection of bus error, slave address, general call,
  762. * address, IDBR receive full, IDBR transmit empty, arbitration loss, slave
  763. * STOP signal, I2C bus busy, unit busy, ack/nack, and read/write mode. It will
  764. * also call the ixI2cDrvGetStats and then display the statistics counter.
  765. *
  766. * @return
  767. * - IX_I2C_SUCCESS - successfully displayed statistics and status register
  768. * - IX_I2C_NOT_INIT - I2C not init yet.
  769. *
  770. * @li Reentrant : yes
  771. * @li ISR Callable : no
  772. *
  773. */
  774. PUBLIC IX_I2C_STATUS
  775. ixI2cDrvShow(void);
  776. /**
  777. * @ingroup IxI2cDrv
  778. *
  779. * @fn ixI2cDrvDelayTypeSelect (IxI2cDelayMode delayMechanismSelect)
  780. *
  781. * @brief Sets the delay type of either looping delay or OS scheduler delay
  782. * according to the argument provided.
  783. *
  784. * @param - "IxI2cDelayMode [in] delayTypeSelect" - the I2C delay type selected
  785. *
  786. * Global Data :
  787. * - None.
  788. *
  789. * This API will set the delay type used by the I2C Driver to either looping
  790. * delay or OS scheduler delay.
  791. *
  792. * @return
  793. * - None
  794. *
  795. * @li Reentrant : yes
  796. * @li ISR Callable : no
  797. *
  798. */
  799. PUBLIC void
  800. ixI2cDrvDelayTypeSelect (IxI2cDelayMode delayTypeSelect);
  801. #endif /* __ixp46X */
  802. #endif /* IXI2CDRV_H */