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