source: SVN/cambria/redboot/packages/devs/eth/intel/npe/common/current/include/IxI2cDrv.h @ 1

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

restored latest version of files from server backup

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

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