/** * @file IxI2cDrv.h * * @brief  Header file for the IXP400 I2C Driver (IxI2cDrv) * * @version $Revision: 0.1 $ *  * @par * IXP400 SW Release version 2.0 *  * -- Copyright Notice -- *  * @par * Copyright 2001-2005, Intel Corporation. * All rights reserved. *  * @par * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright *    notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright *    notice, this list of conditions and the following disclaimer in the *    documentation and/or other materials provided with the distribution. * 3. Neither the name of the Intel Corporation nor the names of its contributors *    may be used to endorse or promote products derived from this software *    without specific prior written permission. *  * @par * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. *  * @par * -- End of Copyright Notice -- *//** * @defgroup IxI2cDrv IXP400 I2C Driver(IxI2cDrv) API  * * @brief IXP400 I2C Driver Public API * * @{ */#ifndef IXI2CDRV_H#define IXI2CDRV_H#ifdef __ixp46X#include "IxOsal.h"/* * Section for #define *//** * @ingroup IxI2cDrv * @brief The interval of micro/mili seconds the IXP will wait before it polls for * 			status from the ixI2cIntrXferStatus; Every 20us is 1 byte @ * 			400Kbps and 4 bytes	@ 100Kbps. This is dependent on delay type selected *          through the API ixI2cDrvDelayTypeSelect. */#define IX_I2C_US_POLL_FOR_XFER_STATUS	20/** * @ingroup IxI2cDrv * @brief The number of tries that will be attempted to call a callback *          function if the callback does not or is unable to resolve the *          issue it is called to resolve */#define IX_I2C_NUM_OF_TRIES_TO_CALL_CALLBACK_FUNC	10/** * @ingroup IxI2cDrv * @brief Number of tries slave will poll the IDBR Rx full bit before it *			gives up */#define IX_I2C_NUM_TO_POLL_IDBR_RX_FULL 0x100/** * @ingroup IxI2cDrv * @brief Number of tries slave will poll the IDBR Tx empty bit before it *			gives up */#define IX_I2C_NUM_TO_POLL_IDBR_TX_EMPTY 0x100/* * Section for enum *//** * @ingroup IxI2cDrv *  * @enum IxI2cMasterStatus * * @brief The master status - transfer complete, bus error or arbitration loss */typedef enum{    IX_I2C_MASTER_XFER_COMPLETE = IX_SUCCESS,	IX_I2C_MASTER_XFER_BUS_ERROR,	IX_I2C_MASTER_XFER_ARB_LOSS} IxI2cMasterStatus;/** * @ingroup IxI2cDrv *  * @enum IX_I2C_STATUS * * @brief The status that can be returned in a I2C driver initialization */typedef enum{	IX_I2C_SUCCESS = IX_SUCCESS, /**< Success status */	IX_I2C_FAIL, /**< Fail status */	IX_I2C_NOT_SUPPORTED, /**< hardware does not have dedicated I2C hardware */	IX_I2C_NULL_POINTER, /**< parameter passed in is NULL */	IX_I2C_INVALID_SPEED_MODE_ENUM_VALUE, /**< speed mode selected is invalid */	IX_I2C_INVALID_FLOW_MODE_ENUM_VALUE, /**< flow mode selected is invalid */	IX_I2C_SLAVE_ADDR_CB_MISSING, /**< slave callback is NULL */	IX_I2C_GEN_CALL_CB_MISSING, /**< general callback is NULL */	IX_I2C_INVALID_SLAVE_ADDR, /**< invalid slave address specified */	IX_I2C_INT_BIND_FAIL, /**< interrupt bind fail */	IX_I2C_INT_UNBIND_FAIL, /**< interrupt unbind fail */	IX_I2C_NOT_INIT, /**< I2C is not initialized yet */	IX_I2C_MASTER_BUS_BUSY, /**< master detected a I2C bus busy */	IX_I2C_MASTER_ARB_LOSS, /**< master experienced arbitration loss */	IX_I2C_MASTER_XFER_ERROR, /**< master experienced a transfer error */	IX_I2C_MASTER_BUS_ERROR, /**< master detected a I2C bus error */	IX_I2C_MASTER_NO_BUFFER, /**< no buffer provided for master transfer */	IX_I2C_MASTER_INVALID_XFER_MODE, /**< xfer mode selected is invalid */	IX_I2C_SLAVE_ADDR_NOT_DETECTED, /**< polled slave addr not detected */	IX_I2C_GEN_CALL_ADDR_DETECTED, /**< polling detected general call */	IX_I2C_SLAVE_READ_DETECTED, /**< polling detected slave read request */	IX_I2C_SLAVE_WRITE_DETECTED, /**< polling detected slave write request */	IX_I2C_SLAVE_NO_BUFFER, /**< no buffer provided for slave transfers */	IX_I2C_DATA_SIZE_ZERO, /**< data size transfer is zero - invalid */	IX_I2C_SLAVE_WRITE_BUFFER_EMPTY, /**< slave buffer is used till empty */	IX_I2C_SLAVE_WRITE_ERROR, /**< slave write experienced an error */	IX_I2C_SLAVE_OR_GEN_READ_BUFFER_FULL, /**< slave buffer is filled up */	IX_I2C_SLAVE_OR_GEN_READ_ERROR /**< slave read experienced an error */} IX_I2C_STATUS;/** * @ingroup IxI2cDrv *  * @enum IxI2cSpeedMode * * @brief Type of speed modes supported by the I2C hardware. */typedef enum{    IX_I2C_NORMAL_MODE = 0x0,    IX_I2C_FAST_MODE} IxI2cSpeedMode;/** * @ingroup IxI2cDrv *  * @enum IxI2cXferMode * * @brief Used for indicating it is a repeated start or normal transfer */typedef enum{    IX_I2C_NORMAL = 0x0,    IX_I2C_REPEATED_START} IxI2cXferMode;/** * @ingroup IxI2cDrv *  * @enum IxI2cFlowMode * * @brief Used for indicating it is a poll or interrupt mode */typedef enum{    IX_I2C_POLL_MODE = 0x0,    IX_I2C_INTERRUPT_MODE} IxI2cFlowMode;/** * @ingroup IxI2cDrv *  * @enum IxI2cDelayMode * * @brief Used for selecting looping delay or OS scheduler delay */typedef enum{    IX_I2C_LOOP_DELAY = 1,  /**< delay in microseconds */    IX_I2C_SCHED_DELAY      /**< delay in miliseconds */} IxI2cDelayMode;/** * @ingroup IxI2cDrv *  * @brief The pointer to the function that will be called when the master *			has completed its receive. The parameter that is passed will *			provide the status of the read (success, arb loss, or bus *			error), the transfer mode (normal or repeated start, the *			buffer pointer and number of bytes transferred. */typedef void (*IxI2cMasterReadCallbackP)(IxI2cMasterStatus, IxI2cXferMode, char*, UINT32);/** * @ingroup IxI2cDrv *  * @brief The pointer to the function that will	be called when the master *			has completed its transmit. The parameter that is passed will *			provide the status of the write (success, arb loss, or buss *			error), the transfer mode (normal or repeated start), the *			buffer pointer and number of bytes transferred. */typedef void (*IxI2cMasterWriteCallbackP)(IxI2cMasterStatus, IxI2cXferMode, char*, UINT32);/** * @ingroup IxI2cDrv *  * @brief The pointer to the function that will be called when a slave *			address detected in interrupt mode for a read. The parameters *			that is passed will provide the read status, buffer pointer, *			buffer size, and the bytes received. When a start of a read *			is initiated there will be no buffer allocated and this callback *			will be called to request for a buffer. While receiving, if the *			buffer gets filled, this callback will be called to request for *			a new buffer while sending the filled buffer's pointer and size, *			and data size received. When the receive is complete, this *			callback will be called to process the data and free the memory *			by passing the buffer's pointer and size, and data size received. */typedef void (*IxI2cSlaveReadCallbackP)(IX_I2C_STATUS, char*, UINT32, UINT32);/** * @ingroup IxI2cDrv *  * @brief The pointer to the function that will be called when a slave *			address detected in interrupt mode for a write. The parameters *			that is passed will provide the write status, buffer pointer, *			buffer size, and the bytes received. When a start of a write is *			initiated there will be no buffer allocated and this callback *			will be called to request for a buffer and to fill it with data. *			While transmitting, if the data in the buffer empties, this *			callback will be called to request for more data to be filled in *			the same or new buffer. When the transmit is complete, this *			callback will be called to free the memory or other actions to *			be taken. */typedef void (*IxI2cSlaveWriteCallbackP)(IX_I2C_STATUS, char*, UINT32, UINT32);/** * @ingroup IxI2cDrv *  * @brief The pointer to the function that will be called when a general *			call detected in interrupt mode for a read. The parameters that *			is passed will provide the read status, buffer pointer, buffer *			size, and the bytes received. When a start of a read is *			initiated there will be no buffer allocated and this callback *			will be called to request for a buffer. While receiving, if the *			buffer gets filled, this callback will be called to request for *			a new buffer while sending the filled buffer's pointer and size, *			and data size received. When the receive is complete, this *			callback will be called to process the data and free the memory *			by passing the buffer's pointer and size, and data size received. */typedef void (*IxI2cGenCallCallbackP)(IX_I2C_STATUS, char*, UINT32, UINT32);/* * Section for struct *//** * @brief contains all the variables required to initialize the I2C unit *  * Structure to be filled and used for calling initialization */typedef struct{	IxI2cSpeedMode I2cSpeedSelect;	/**<Select either normal (100kbps)									or fast mode (400kbps)*/	IxI2cFlowMode I2cFlowSelect;	/**<Select interrupt or poll mode*/		IxI2cMasterReadCallbackP MasterReadCBP;									/**<The master read callback pointer */	IxI2cMasterWriteCallbackP MasterWriteCBP;									/**<The master write callback pointer */	IxI2cSlaveReadCallbackP SlaveReadCBP;									/**<The slave read callback pointer */	IxI2cSlaveWriteCallbackP SlaveWriteCBP;									/**<The slave write callback pointer */	IxI2cGenCallCallbackP GenCallCBP;									/**<The general call callback pointer */	BOOL I2cGenCallResponseEnable;	/**<Enable/disable the unit to									respond to generall calls.*/	BOOL I2cSlaveAddrResponseEnable;/**<Enable/disable the unit to									respond to the slave address set in									ISAR*/	BOOL SCLEnable;					/**<Enable/disable the unit from									driving the SCL line during master									mode operation*/	UINT8 I2cHWAddr;				/**<The address the unit will									response to as a slave device*/} IxI2cInitVars;/** * @brief contains results of counters and their overflow *  * Structure contains all values of counters and associated overflows. */typedef struct{	UINT32 ixI2cMasterXmitCounter;			/**<Total bytes transmitted as											master.*/	UINT32 ixI2cMasterFailedXmitCounter;	/**<Total bytes failed for											transmission as master.*/	UINT32 ixI2cMasterRcvCounter;			/**<Total bytes received as											master.*/	UINT32 ixI2cMasterFailedRcvCounter;		/**<Total bytes failed for											receival as master.*/	UINT32 ixI2cSlaveXmitCounter;			/**<Total bytes transmitted as											slave.*/	UINT32 ixI2cSlaveFailedXmitCounter;		/**<Total bytes failed for											transmission as slave.*/	UINT32 ixI2cSlaveRcvCounter;			/**<Total bytes received as											slave.*/	UINT32 ixI2cSlaveFailedRcvCounter;		/**<Total bytes failed for											receival as slave.*/	UINT32 ixI2cGenAddrCallSucceedCounter;	/**<Total bytes successfully											transmitted for general address.*/	UINT32 ixI2cGenAddrCallFailedCounter;	/**<Total bytes failed transmission											for general address.*/	UINT32 ixI2cArbLossCounter;				/**<Total instances of arbitration											loss has occured.*/} IxI2cStatsCounters;/* * Section for prototypes interface functions *//** * @ingroup IxI2cDrv *  * @fn ixI2cDrvInit(	IxI2cInitVars *InitVarsSelected) * * @brief Initializes the I2C Driver. * * @param "IxI2cInitVars [in] *InitVarsSelected" - struct containing required *			variables for initialization  * * Global Data	: *		- None. * * This API will check if the hardware supports this I2C driver and the validity * of the parameters passed in. It will continue to process the parameters * passed in by setting the speed of the I2C unit (100kbps or 400kbps), setting * the flow to either interrupt or poll mode, setting the address of the I2C unit, * enabling/disabling the respond to General Calls, enabling/disabling the respond * to Slave Address and SCL line driving. If it is interrupt mode, then it will * register the callback routines for master, slavetransfer and general call receive. * * @return  *      - IX_I2C_SUCCESS - Successfully initialize and enable the I2C *							hardware. *		- IX_I2C_NOT_SUPPORTED - The hardware does not support or have a *                              dedicated I2C unit to support this driver *		- IX_I2C_NULL_POINTER - The parameter passed in is a NULL pointed *		- IX_I2C_INVALID_SPEED_MODE_ENUM_VALUE - The speed mode selected in the *												InitVarsSelected is invalid *		- IX_I2C_INVALID_FLOW_MODE_ENUM_VALUE - The flow mode selected in the *												InitVarsSelected is invalid *		- IX_I2C_INVALID_SLAVE_ADDR - The address 0x0 is reserved for *										general call. *		- IX_I2C_SLAVE_ADDR_CB_MISSING - interrupt mode is selected but *										slave address callback pointer is NULL *		- IX_I2C_GEN_CALL_CB_MISSING - interrupt mode is selected but *										general call callback pointer is NULL *		- IX_I2C_INT_BIND_FAIL - The ISR for the I2C failed to bind *		- IX_I2C_INT_UNBIND_FAIL - The ISR for the I2C failed to unbind * * @li   Reentrant    : yes * @li   ISR Callable : yes * */PUBLIC IX_I2C_STATUSixI2cDrvInit(IxI2cInitVars *InitVarsSelected);/** * @ingroup IxI2cDrv *  * @fn ixI2cDrvUninit(	void) * * @brief Disables the I2C hardware * * @param - None * * Global Data	: *		- None. *                         * This API will disable the I2C hardware, unbind interrupt, and unmap memory. * * @return  *      - IX_I2C_SUCCESS - successfully un-initialized I2C *		- IX_I2C_INT_UNBIND_FAIL - failed to unbind the I2C interrupt *		- IX_I2C_NOT_INIT - I2C not init yet. *               * @li   Reentrant    : yes * @li   ISR Callable : yes * */PUBLIC IX_I2C_STATUSixI2cDrvUninit(void);/** * @ingroup IxI2cDrv *  * @fn ixI2cDrvSlaveAddrSet(	UINT8 SlaveAddrSet) * * @brief Sets the I2C Slave Address * * @param "UINT8 [in] SlaveAddrSet" - Slave Address to be inserted into ISAR