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