drivers/net/npe/include/IxI2cDrv.h

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