/* Copyright (c) 2006 NVIDIA Corporation.  All rights reserved.
 *
 * NVIDIA Corporation and its licensors retain all intellectual property 
 * and proprietary rights in and to this software, related documentation 
 * and any modifications thereto.  Any use, reproduction, disclosure or 
 * distribution of this software and related documentation without an 
 * express license agreement from NVIDIA Corporation is strictly prohibited.
 */

/** @file GFI2C.h
    GFSDK I2C API header file.
*/

#ifndef __I2C_H__
#define __I2C_H__

#ifdef __cplusplus
extern "C"
{
#endif

/** @addtogroup groupI2C I2CAPI I2C API
*/
/*@{*/

/** GFI2C Error code: Function was passed an illegal parameter. */
#define GFI2C_ERROR_ILLEGAL_PARAMETER           (GFI2C_ERROR | 0x00000001L)
/** GFI2C Error code: I2C slave device did not respond with ack signal. */
#define GFI2C_ERROR_ACKNOWLEDGE_FAILURE         (GFI2C_ERROR | 0x00000002L)
/** GFI2C Error code: Polling routine generated a timeout error. */
#define GFI2C_ERROR_TIMEOUT_ERROR               (GFI2C_ERROR | 0x00000003L)

/** Enum specifies attribute ids for GFI2CSetAttribute()
    @see GFI2CSetAttribute()
*/
typedef enum _GFI2CATTRIBUTES
{
    GFI2C_ATTR_PULLUP,      /**< Set internal I2C pullups, see GFI2C_ATTR_PULLUP_FLAGS. */
    GFI2C_ATTR_SW,          /**< Set to use GPIO for SW I2C */
    GFI2C_ATTR_HW,          /**< Set to use HW I2C (default) */
    GFI2C_ATTR_TIMING,      /**< I2C timing mode, valid for GFI2C_ATTR_HW mode only, see GFI2C_TIMING */
    GFI2C_ATTR_RESPTIMEOUT  /**< Set I2C Ack response timeout in ms */

} GFI2CATTRIBUTES;

/** Flag bits for for GFI2C_ATTR_PULLUP attribute.

    Usage example:
    <pre>
    attr = (SP_SCL_PULLUP_DISABLE | SP_SDA_PULLUP_DISABLE)
    GFI2CSetAttribute(I2CHandle, GFI2C_ATTR_PULLUP, attr)
    </pre>

    @see GFI2CSetAttribute(), GFI2CATTRIBUTES
*/ 
typedef enum _GFI2C_ATTR_PULLUP_FLAGS
{
    SDA_PULLDOWN_DISABLE = 0, //!< Flag to disable I2C data pull down
    SDA_PULLDOWN_ENABLE  = 1, //!< Flag to enable I2C data pull down
    SDA_PULLUP_DISABLE   = 0, //!< Flag to disable I2C data pull up
    SDA_PULLUP_ENABLE    = 1, //!< Flag to enable I2C data pull up
    SCL_PULLDOWN_DISABLE = 0, //!< Flag to disable I2C clock pull down
    SCL_PULLDOWN_ENABLE  = 1, //!< Flag to enable I2C clock pull down
    SCL_PULLUP_DISABLE   = 0, //!< Flag to disable I2C data pull up
    SCL_PULLUP_ENABLE    = 0, //!< Flag to enable I2C clock pull up
    SCL_DEFAULT          = 0, //!< Flag sets I2C clock back to default
    SDA_DEFAULT          = 0  //!< Flag sets I2C data back to default

} GFI2C_ATTR_PULLUP_FLAGS;

/** Timing modes for GFI2C_ATTR_TIMING attribute.

    The timing mode has effect for I2C HW mode (GFI2C_ATTR_HW) only.

    It affects the programming of IC_IC_CONFIG_0/THDCTL and
    IC_TCOMMAND_0/SPEED_CTL registers.
*/
typedef enum _GFI2C_TIMING
{
    /** Standard timing (default).
        IC_TCOMMAND_0, SPEED_CTL is programmed to STD_MODE (standard timing).
    */
    GFI2C_TIMING_STANDARD = 0,    

    /** Fast mode with 2 clocks extended hold time.
        IC_TCOMMAND_0, SPEED_CTL is programmed to FAST_MODE.
        IC_IC_CONFIG_0, THDCTL is programmed to b'10 (add 2 clocks to hold time).
    */
    GFI2C_TIMING_FASTADD2CLK

} GFI2C_TIMING;

typedef struct _GFI2CTABLE
{
    GF_RETTYPE (* I2CWrite)( GFI2CHandle I2CHandle,
                             NvU32      slaveAddr,
                             NvU8       *pDataBytes,
                             NvU32      len,
                             NvU32      delayInMSec );

    GF_RETTYPE (* I2CRead)( GFI2CHandle I2CHandle,
                            NvU32       slaveAddr,
                            NvU8        *pDataBytes,
                            NvU32       len,
                            NvU32       delayInMSec );

    GF_RETTYPE (* I2CRestartRead)( GFI2CHandle I2CHandle,
                            NvU32       slaveAddr,
                            NvU32       index,
                            NvU8        *pDataBytes,
                            NvU32       len,
                            NvU32       delayInMSec );

    GF_RETTYPE (* I2CScan)( GFI2CHandle I2CHandle,
                            NvU16       slaveAddr );

    GF_RETTYPE (* I2CPowerSwitch)( GFI2CHandle I2CHandle, NvU8 status);

    GF_RETTYPE (* I2CGetProperty)( GFI2CHandle I2CHandle,
                                   PGFPROPERTY  pI2CProp );

    GF_RETTYPE (* I2CSetAttribute)(GFI2CHandle I2CHandle, NvU32 aid, NvU32 attr);
    GF_RETTYPE (* I2CSetClock)( GFI2CHandle I2CHandle, NvU32 selectclock);
    GF_RETTYPE (* I2CWritePrepare)( GFI2CHandle I2CHandle,
                            NvU32       slaveAddr,
                            NvU32       *pData,
                            NvU32       len,
                            NvU32       *pBuffer,
                            NvU32       *bufferSize);
    GF_RETTYPE (* I2CRestartWrite)( GFI2CHandle  I2CHandle,
                                NvU32         slaveAddr1,
                                NvU8          *pIndexBytes,
                                NvU32         lenIndex,
                                NvU32         slaveAddr2,
                                NvU8           *pDataBytes,
                                NvU32          lenData,
                                NvU32          delayInMSec );

} GFI2CTABLE, *PGFI2CTABLE;

/** Open GFI2C component.
    @param hRm   RM handle
    @param phI2C Returns I2C component handle on success
    @param state Channel allocation mode
    @param hCh   Channel to use, or NULL to allocate new
*/
GF_RETTYPE GFI2COpen(GFRmHandle hRm, GFI2CHandle *phI2C, GF_STATE_TYPE state, GFRmChHandle hCh);

/** Close GFi@c component.
    @param phI2C I2C component handle, will be reset to NULL. Can be NULL.
*/
void GFI2CClose(GFI2CHandle *phI2C);

/** This routine writes out len bytes of data during one I2C transfer.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param slaveAddr (NvU32) I2C address of slave device
    @param pDataBytes (NvU8) Pointer to data bytes to be written
    @param len (NvU32) Number of bytes of data to be written
    @param delayInMSec (NvU32) Optional delay inserted after transfer

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

*/
#define GFI2CWrite(I2CHandle, slaveAddr, pDataBytes, len, delayInMSec) \
    ((PGFI2CTABLE)I2CHandle)->I2CWrite(I2CHandle, slaveAddr, pDataBytes, len, delayInMSec)

/** This routine reads len bytes of data during one I2C transfer.  A typical I2C slave
    device requires its address already be set by a preceding GFI2CWrite() function.
    These functions should be executed together with no other activity in between.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param slaveAddr (NvU32) I2C address of slave device
    @param pDataBytes (NvU8) Pointer to data bytes read from device
    @param len (NvU32) Number of bytes of data to be read
    @param delayInMSec (NvU32) Optional delay inserted after transfer

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

*/
#define GFI2CRead(I2CHandle, slaveAddr, pDataBytes, len, delayInMSec) \
    ((PGFI2CTABLE)I2CHandle)->I2CRead(I2CHandle, slaveAddr, pDataBytes, len, delayInMSec)

/** This function reads in len or fewer bytes of data from an I2C slave device.  It differs
    from the GFI2CRead() function in that it does so with a combination of an I2C write and 
    read.  There is an I2C write of the slave address and index byte then followed by a START
    condition.  There is no STOP condition in-between the write and read transactions.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param slaveAddr (NvU32) I2C address of slave device
    @param index (NvU32) 2nd byte index of slave device register
    @param pDataBytes (NvU8) Pointer to data bytes read from device
    @param len (NvU32) Number of bytes of data to be read
    @param delayInMSec (NvU32) Optional delay inserted after transfer

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

*/
#define GFI2CRestartRead(I2CHandle, slaveAddr, index, pDataBytes, len, delayInMSec) \
    ((PGFI2CTABLE)I2CHandle)->I2CRestartRead(I2CHandle, slaveAddr, index, pDataBytes, len, delayInMSec)

/** This routine writes out a I2C slave address and checks for an ACK.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param slaveAddr (NvU32) I2C address of slave device

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

*/
#define GFI2CScan(I2CHandle, slaveAddr) \
    ((PGFI2CTABLE)I2CHandle)->I2CScan(I2CHandle, slaveAddr)

/** This function has been replaced by camera scripting.  Camera power is now
    controlled by a function in the camera scripts.
*/
#define GFI2CPowerSwitch(I2CHandle, status) \
    ((PGFI2CTABLE)I2CHandle)->I2CPowerSwitch(I2CHandle, status)

/** This routine sets various I2C attributes.  The aid parameter passes an
    enumeration GFI2CATTRIBUTES that selects the attribute operation.  Each
    attribute has a set of defined values passed in the parameter attr, that
    it will operate on.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param aid (NvU32) attribute flag
    @param attr (NvU32) attribute data value

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

    @see GFI2CATTRIBUTES

*/
#define GFI2CSetAttribute( I2CHandle, aid, attr) \
    ((PGFI2CTABLE)I2CHandle)->I2CSetAttribute(I2CHandle, aid, attr )

/** This routine sets the I2C clock output on the SCL pin.  The parameter
    selectclock specifies the new I2C clock in kilohertz.  The default
    is 100.  If selectclock = 0, then the default will be set.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param selectclock (NvU32) new clock value in kHz.

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

*/
#define GFI2CSetClock(I2CHandle, selectclock) \
    ((PGFI2CTABLE)I2CHandle)->I2CSetClock(I2CHandle, selectclock)

/** This routine Provide properties about I2C.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param pProp (GFPROPERTY) pointer to GFPROPERTY struct.

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured
*/ 
#define GFI2CGetProperty(I2CHandle, pProp) \
    ((PGFI2CTABLE)I2CHandle)->I2CGetProperty(I2CHandle, pProp)

/** This function prepares a buffer that contains the command sequence for an
    I2C write.  This may concatenated onto another command sequence and written
    to the channel as a combination of two transactions.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param slaveAddr (NvU32) I2C address of slave device
    @param pData (NvU8) Pointer to data bytes to be written
    @param len (NvU32) Number of bytes of data to be read
    @param pBuffer (NvU8) Pointer to command sequence for I2C write
    @param bufferSize (NvU32) Number of commands returned

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

*/
#define GFI2CWritePrepare(I2CHandle, slaveAddr, pData, len, pBuffer, bufferSize) \
    ((PGFI2CTABLE)I2CHandle)->I2CWritePrepare(I2CHandle, slaveAddr, pData, len, pBuffer, bufferSize)

/** This function writes lenData bytes of data to an I2C slave device.  It differs
    from the GFI2CWrite() function in that it does so with a combination of two I2C writes  
    There is an I2C write of the slave address and index bytes then followed by a START
    condition.  There is no STOP condition in-between the write and write transactions.

    @param I2CHandle (#GFI2CHandle) Handle to I2CAPI
    @param slaveAddr1 (NvU32) I2C address of 1st slave device
    @param pDataIndex (NvU8) Pointer to index data to be written to the 1st device
    @param lenIndex (NvU32) index data length
    @param slaveAddr2 (NvU32) I2C address of 2nd slave device
    @param pDataBytes (NvU8) Pointer to data bytes written to 2nd device
    @param lenData (NvU32) Number of bytes of data to be read
    @param delayInMSec (NvU32) Optional delay inserted after transfer

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Some error occured

*/
#define GFI2CRestartWrite(I2CHandle, slaveAddr1, pIndexBytes, lenIndex, \
                        slaveAddr2, pDataBytes, lenData, delayInMSec) \
    ((PGFI2CTABLE)I2CHandle)->I2CRestartWrite(I2CHandle, slaveAddr1, pIndexBytes, lenIndex, \
                        slaveAddr2, pDataBytes, lenData, delayInMSec)

/*@}*/

#ifdef __cplusplus
}
#endif

#endif  /* __I2C_H__ */