ixi2cdrv.h

AMCC POWERPC 44X系列的U-BOOT文件

 *
 * Global Data	:
 *		- None.
 *                        
 * This API will insert the SlaveAddrSet into the ISAR.
 *
 * @return 
 *      - IX_I2C_SUCCESS - successfuly set the slave addr
 *		- IX_I2C_INVALID_SLAVE_ADDR - invalid slave address (zero) specified
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : yes
 * @li   ISR Callable : yes
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvSlaveAddrSet(UINT8 SlaveAddrSet);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvBusScan(
	void)
 *
 * @brief scans the I2C bus for slave devices
 *
 * @param - None
 *
 * Global Data	:
 *		- None.
 *                        
 * This API will prompt all slave addresses for a reply except its own
 *
 * @return 
 *      - IX_I2C_SUCCESS - found at least one slave device
 *		- IX_I2C_FAIL - Fail to find even one slave device
 *		- IX_I2C_BUS_BUSY - The I2C bus is busy (held by another I2C master)
 *		- IX_I2C_ARB_LOSS - The I2C bus was loss to another I2C master
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : yes
 * @li   ISR Callable : yes
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvBusScan(void);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvWriteTransfer(
	UINT8 SlaveAddr,
	char *bufP,
	UINT32 dataSize,
	IxI2cXferMode XferModeSelect)
 *
 * @param "UINT8 [in] SlaveAddr" - The slave address to request data from.
 * @param "char [in] *bufP" - The pointer to the data to be transmitted.
 * @param "UINT32 [in] dataSize" - The number of bytes requested.
 * @param "IxI2cXferMode [in] XferModeSelect" - the transfer mode selected,
 *			either repeated start (ends w/o stop) or normal (start and stop)
 *
 * Global Data	:
 *		- None.
 *                        
 * This API will try to obtain master control of the I2C bus and transmit the
 * number of bytes, specified by dataSize, to the user specified slave
 * address from the buffer pointer. It will use either interrupt or poll mode
 * depending on the method selected. 
 *
 * If in interrupt mode and IxI2cMasterWriteCallbackP is not NULL, the driver
 * will initiate the transfer and return immediately. The function pointed to
 * by IxI2cMasterWriteCallbackP will be called in the interrupt service
 * handlers when the operation is complete.
 *
 * If in interrupt mode and IxI2cMasterWriteCallbackP is NULL, then the driver
 * will wait for the operation to complete, and then return.
 *
 * And if the repeated start transfer mode is selected, then it will not send a
 * stop signal at the end of all the transfers.
 * *NOTE*: If repeated start transfer mode is selected, it has to end with a
 *			normal mode transfer mode else the bus will continue to be held
 *			by the IXP.
 *
 * @return 
 *      - IX_I2C_SUCCESS - Successfuuly wrote data to slave.
 *		- IX_I2C_MASTER_BUS_BUSY - The I2C bus is busy (held by another I2C master)
 *		- IX_I2C_MASTER_ARB_LOSS - The I2C bus was loss to another I2C master
 *		- IX_I2C_MASTER_XFER_ERROR - There was a transfer error
 *      - IX_I2C_MASTER_BUS_ERROR - There was a bus error during transfer
 *		- IX_I2C_MASTER_NO_BUFFER - buffer pointer is NULL
 *      - IX_I2C_MASTER_INVALID_XFER_MODE - Xfer mode selected is invalid
 *      - IX_I2C_DATA_SIZE_ZERO - dataSize passed in is zero, which is invalid
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : no
 * @li   ISR Callable : no
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvWriteTransfer(
	UINT8 SlaveAddr,
	char *bufP,
	UINT32 dataSize,
	IxI2cXferMode XferModeSelect);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvReadTransfer(
	UINT8 SlaveAddr,
	char *bufP,
	UINT32 dataSize,
	IxI2cXferMode XferModeSelect)
 *
 * @brief Initiates a transfer to receive bytes of data from a slave
 *			device through the I2C bus.
 *
 * @param "UINT8 [in] SlaveAddr" - The slave address to request data from.
 * @param "char [out] *bufP" - The pointer to the buffer to store the
 *			requested data.
 * @param "UINT32 [in] dataSize" - The number of bytes requested.
 * @param "IxI2cXferMode [in] XferModeSelect" - the transfer mode selected,
 *			either repeated start (ends w/o stop) or normal (start and stop)
 *
 * Global Data	:
 *		- None.
 *                        
 * This API will try to obtain master control of the I2C bus and receive the
 * number of bytes, specified by dataSize, from the user specified address
 * into the receive buffer. It will use either interrupt or poll mode depending
 * on the mode selected.
 *
 * If in interrupt mode and IxI2cMasterReadCallbackP is not NULL, the driver
 * will initiate the transfer and return immediately. The function pointed to
 * by IxI2cMasterReadCallbackP will be called in the interrupt service
 * handlers when the operation is complete.
 *
 * If in interrupt mode and IxI2cMasterReadCallbackP is NULL, then the driver will
 * wait for the operation to complete, and then return.
 *
 * And if the repeated start transfer mode is selected, then it will not send a
 * stop signal at the end of all the transfers.
 * *NOTE*: If repeated start transfer mode is selected, it has to end with a
 *			normal mode transfer mode else the bus will continue to be held
 *			by the IXP.
 *
 * @return 
 *      - IX_I2C_SUCCESS - Successfuuly read slave data
 *		- IX_I2C_MASTER_BUS_BUSY - The I2C bus is busy (held by another I2C master)
 *		- IX_I2C_MASTER_ARB_LOSS - The I2C bus was loss to another I2C master
 *		- IX_I2C_MASTER_XFER_ERROR - There was a bus error during transfer
 *      - IX_I2C_MASTER_BUS_ERROR - There was a bus error during transfer
 *		- IX_I2C_MASTER_NO_BUFFER - buffer pointer is NULL
 *      - IX_I2C_MASTER_INVALID_XFER_MODE - Xfer mode selected is invalid
 *      - IX_I2C_INVALID_SLAVE_ADDR - invalid slave address (zero) specified
 *      - IX_I2C_DATA_SIZE_ZERO - dataSize passed in is zero, which is invalid
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : no
 * @li   ISR Callable : no
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvReadTransfer(
	UINT8 SlaveAddr,
	char *bufP,
	UINT32 dataSize,
	IxI2cXferMode XferModeSelect);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvSlaveAddrAndGenCallDetectedCheck(
	void)
 *
 * @brief Checks the I2C Status Register to determine if a slave address is
 *			detected
 *
 * @param - None
 *
 * Global Data	:
 *		- None.
 *                        
 * This API is used in polled mode to determine if the I2C unit is requested
 * for a slave or general call transfer. If it is requested for a slave
 * transfer then it will determine if it is a general call (read only), read,
 * or write transfer requested.
 *
 * @return 
 *      - IX_I2C_SLAVE_ADDR_NOT_DETECTED - The I2C unit is not requested for slave
 *										transfer
 *		- IX_I2C_GEN_CALL_ADDR_DETECTED - The I2C unit is not requested for slave
 *									transfer but for general call
 *      - IX_I2C_SLAVE_READ_DETECTED - The I2C unit is requested for a read
 *      - IX_I2C_SLAVE_WRITE_DETECTED - The I2C unit is requested for a write
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : no
 * @li   ISR Callable : no
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvSlaveAddrAndGenCallDetectedCheck(void);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvSlaveOrGenDataReceive(
	char *bufP,
	UINT32 bufSize,
	UINT32 *dataSizeRcvd)
 *
 * @brief Performs the slave receive or general call receive data transfer
 *
 * @param	"char [in] *bufP" - the pointer to the buffer to store data
 *			"UINT32 [in] bufSize" - the buffer size allocated
 *			"UINT32 [in] *dataSizeRcvd" - the length of data received in bytes
 *
 * Global Data	:
 *		- None.
 *                        
 * This API is only used in polled mode to perform the slave read or general call
 * receive data. It will continuously store the data received into bufP until
 * complete or until bufP is full in which it will return
 * IX_I2C_SLAVE_OR_GEN_READ_BUFFER_FULL. If in interrupt mode, the callback will be
 * used.
 *
 * @return 
 *      - IX_I2C_SUCCESS - The I2C driver transferred the data successfully.
 *		- IX_I2C_SLAVE_OR_GEN_READ_BUFFER_FULL - The I2C driver has ran out of
 *			space to store the received data.
 *		- IX_I2C_SLAVE_OR_GEN_READ_ERROR - The I2C driver didn't manage to
 *			detect the IDBR Rx Full bit
 *      - IX_I2C_DATA_SIZE_ZERO - bufSize passed in is zero, which is invalid
 *		- IX_I2C_SLAVE_NO_BUFFER - buffer pointer is NULL
 *      - IX_I2C_NULL_POINTER - dataSizeRcvd is NULL
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : no
 * @li   ISR Callable : no
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvSlaveOrGenDataReceive(
	char *bufP,
	UINT32 bufSize,
	UINT32 *dataSizeRcvd);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvSlaveDataTransmit(
	char *bufP,
	UINT32 dataSize,
	UINT32 *dataSizeXmtd)
 *
 * @brief Performs the slave write data transfer
 *
 * @param	"char [in] *bufP" - the pointer to the buffer for data to be
 *				transmitted
 *			"UINT32 [in] bufSize" - the buffer size allocated
 *			"UINT32 [in] *dataSizeRcvd" - the length of data trasnmitted in
 *				bytes
 *
 * Global Data	:
 *		- None.
 *                        
 * This API is only used in polled mode to perform the slave transmit data. It
 * will continuously transmit the data from bufP until complete or until bufP
 * is empty in which it will return IX_I2C_SLAVE_WRITE_BUFFER_EMPTY. If in
 * interrupt mode, the callback will be used.
 *
 * @return 
 *      - IX_I2C_SUCCESS - The I2C driver transferred the data successfully.
 *      - IX_I2C_SLAVE_WRITE_BUFFER_EMPTY - The I2C driver needs more data to
 *			transmit.
 *      - IX_I2C_SLAVE_WRITE_ERROR -The I2C driver didn't manage to detect the
 *          IDBR Tx empty bit or the slave stop bit.
 *      - IX_I2C_DATA_SIZE_ZERO - dataSize passed in is zero, which is invalid
 *		- IX_I2C_SLAVE_NO_BUFFER - buffer pointer is NULL
 *      - IX_I2C_NULL_POINTER - dataSizeXmtd is NULL
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : no
 * @li   ISR Callable : no
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvSlaveDataTransmit(
	char *bufP,
	UINT32 dataSize,
	UINT32 *dataSizeXmtd);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvSlaveOrGenCallBufReplenish(
	char *bufP,
	UINT32 bufSize)
 *
 * @brief Replenishes the buffer which stores buffer info for both slave and
 *			general call
 *
 * @param	"char [in] *bufP" - pointer to the buffer allocated
 *			"UINT32 [in] bufSize" - size of the buffer
 *
 * Global Data	:
 *		- None.
 *                        
 * This API is only used in interrupt mode for replenishing the same buffer
 * that is used by both slave and generall call by updating the buffer info
 * with new info and clearing previous offsets set by previous transfers.
 *
 * @return 
 *      - None
 *              
 * @li   Reentrant    : no
 * @li   ISR Callable : no
 *
 */
PUBLIC void
ixI2cDrvSlaveOrGenCallBufReplenish(
	char *bufP,
	UINT32 bufSize);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvStatsGet(IxI2cStatsCounters *I2cStats)
 *
 * @brief Returns the I2C Statistics through the pointer passed in
 *
 * @param - "IxI2cStatsCounters [out] *I2cStats" - I2C statistics counter will
 *			be read and written to the location pointed by this pointer.
 *
 * Global Data	:
 *		- None.
 *                        
 * This API will return the statistics counters of the I2C driver.
 *
 * @return 
 *      - IX_I2C_NULL_POINTER - pointer passed in is NULL
 *		- IX_I2C_SUCCESS - successfully obtained I2C statistics
 *              
 * @li   Reentrant    : yes
 * @li   ISR Callable : no
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvStatsGet(IxI2cStatsCounters *I2cStats);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvStatsReset(void)
 *
 * @brief Reset I2C statistics counters.
 *
 * @param - None
 *
 * Global Data	:
 *		- None.
 *                        
 * This API will reset the statistics counters of the I2C driver.
 *
 * @return 
 *      - None
 *              
 * @li   Reentrant    : yes
 * @li   ISR Callable : no
 *
 */
PUBLIC void
ixI2cDrvStatsReset(void);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvShow(void)
 *
 * @brief Displays the I2C status register and the statistics counter.
 *
 * @param - None
 *
 * Global Data	:
 *		- None.
 *                        
 * This API will display the I2C Status register and is useful if any error
 * occurs. It displays the detection of bus error, slave address, general call,
 * address, IDBR receive full, IDBR transmit empty, arbitration loss, slave
 * STOP signal, I2C bus busy, unit busy, ack/nack, and read/write mode. It will
 * also call the ixI2cDrvGetStats and then display the statistics counter.
 *
 * @return 
 *		- IX_I2C_SUCCESS - successfully displayed statistics and status register
 *		- IX_I2C_NOT_INIT - I2C not init yet.
 *              
 * @li   Reentrant    : yes
 * @li   ISR Callable : no
 *
 */
PUBLIC IX_I2C_STATUS
ixI2cDrvShow(void);

/**
 * @ingroup IxI2cDrv
 * 
 * @fn ixI2cDrvDelayTypeSelect (IxI2cDelayMode delayMechanismSelect)
 *
 * @brief Sets the delay type of either looping delay or OS scheduler delay
 *          according to the argument provided.
 *
 * @param - "IxI2cDelayMode [in] delayTypeSelect" - the I2C delay type selected
 *
 * Global Data	:
 *		- None.
 *                        
 * This API will set the delay type used by the I2C Driver to either looping
 * delay or OS scheduler delay.
 *
 * @return 
 *		- None
 *              
 * @li   Reentrant    : yes
 * @li   ISR Callable : no
 *
 */
PUBLIC void
ixI2cDrvDelayTypeSelect (IxI2cDelayMode delayTypeSelect);

#endif /* __ixp46X */
#endif /* IXI2CDRV_H */