source: SVN/rincon/u-boot/cpu/ixp/npe/include/IxI2cDrv.h @ 55

Last change on this file since 55 was 55, checked in by Tim Harvey, 2 years ago

rincon: added latest u-boot source

restored form server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 27.9 KB
Line 
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
67 *                      status from the ixI2cIntrXferStatus; Every 20us is 1 byte @
68 *                      400Kbps and 4 bytes     @ 100Kbps. This is dependent on delay type selected
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 */
107typedef 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 */
122typedef 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 */
161typedef 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 */
174typedef 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 */
187typedef 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 */
200typedef 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 */
215typedef 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 */
226typedef 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 */
243typedef 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 */
260typedef 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 */
277typedef 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 */
288typedef 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 */
320typedef 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 */
396PUBLIC IX_I2C_STATUS
397ixI2cDrvInit(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 */
423PUBLIC IX_I2C_STATUS
424ixI2cDrvUninit(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 */
450PUBLIC IX_I2C_STATUS
451ixI2cDrvSlaveAddrSet(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 */
479PUBLIC IX_I2C_STATUS
480ixI2cDrvBusScan(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 */
534PUBLIC IX_I2C_STATUS
535ixI2cDrvWriteTransfer(
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 */
598PUBLIC IX_I2C_STATUS
599ixI2cDrvReadTransfer(
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 */
637PUBLIC IX_I2C_STATUS
638ixI2cDrvSlaveAddrAndGenCallDetectedCheck(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 */
678PUBLIC IX_I2C_STATUS
679ixI2cDrvSlaveOrGenDataReceive(
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 */
723PUBLIC IX_I2C_STATUS
724ixI2cDrvSlaveDataTransmit(
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 */
756PUBLIC void
757ixI2cDrvSlaveOrGenCallBufReplenish(
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 */
784PUBLIC IX_I2C_STATUS
785ixI2cDrvStatsGet(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 */
808PUBLIC void
809ixI2cDrvStatsReset(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 */
837PUBLIC IX_I2C_STATUS
838ixI2cDrvShow(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 */
863PUBLIC void
864ixI2cDrvDelayTypeSelect (IxI2cDelayMode delayTypeSelect);
865
866#endif /* __ixp46X */
867#endif /* IXI2CDRV_H */
Note: See TracBrowser for help on using the repository browser.