csl_i2c.h

Configuring External Interrupts on TMS320C672x Devices

 *   @verbatim  
        CSL_i2cHandle hI2c;
        CSL_i2cHwSetup hwSetup;
      
        hwSetup.mode           = CSL_I2C_MODE_MASTER;
        hwSetup.dir            = CSL_I2C_DIR_TRANSMIT;
        hwSetup.addrMode       = CSL_I2C_ADDRSZ_SEVEN;
        .
        .
        hwSetup.clksetup       = &clksetup;
    
        CSL_i2cHwSetup (hI2c, &hwSetup);
     @endverbatim
 * 
 * ============================================================================
 */ 
extern CSL_Status  CSL_i2cHwSetup(    
    CSL_I2cHandle                         hI2c,    
    CSL_I2cHwSetup                        *setup
);

/** ============================================================================
 *   @n@b CSL_i2cGetHwSetup
 *
 *   @b Description
 *   @n It retrives the hardware setup parameters of the I2C
 *      specified by the given handle.
 *
 *   @b Arguments
 *   @verbatim
 
            hI2c        Handle to the I2C  
            setup       Pointer to the harware setup structure

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Retrieving the hardware setup
 *                                                parameters is successful
 *   @li                    CSL_ESYS_BADHANDLE  - The handle is passed is
 *                                                invalid
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *
 *   <b> Pre Condition </b>
 *   @n  i2c must have opened properly
 *
 *   <b> Post Condition </b>
 *   @n  The hardware setup structure is populated with the hardware setup
 *       parameters
 *
 *   @b Modifies
 *   @n setup variable
 *
 *   @b Example
 *   @verbatim
            CSL_I2cHandle   hI2c;
            CSL_I2cHwSetup  hwSetup;

            ...

            status = CSL_i2cGetHwSetup (hI2c, &hwSetup);

            ...

     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_i2cGetHwSetup(    
    CSL_I2cHandle                         hI2c,   
    CSL_I2cHwSetup                        *setup
);


/** ============================================================================
 *   @n@b CSL_i2cHwControl
 *
 *   @b Description
 *   @n Takes a command of I2C with an optional argument & implements it.
 *
 *   @b Arguments
 *   @verbatim
 
            hI2c        Handle to the I2C instance 
            cmd         The command to this API indicates the action to be
                        taken on I2C. 
            arg         An optional argument.

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li         CSL_SOK               - Status info return successful.
 *   @li         CSL_ESYS_BADHANDLE    - Invalid handle
 *   @li         CSL_ESYS_INVCMD       - Invalid command
 *   @li         CSL_ESYS_INVPARAMS    - Invalid parameter
 *
 *   <b> Pre Condition </b>
 *   @n  i2c opened properly
 *
 *   <b> Post Condition </b>
 *   @n  device register programmed accordingly
 *
 *   @b Modifies
 *   @n The hardware registers of I2C.
 *
 *   @b Example
 *   @verbatim
        CSL_I2cHandle           hI2c;
        CSL_I2cHwControlCmd     cmd;
        void                    *arg;
        
        cmd = CSL_I2C_CMD_RESET;

        status = CSL_i2cHwControl (hI2c, cmd, &arg);

     @endverbatim
 * =============================================================================
 */ 
extern CSL_Status  CSL_i2cHwControl(    
    CSL_I2cHandle                        hI2c,    
    CSL_I2cHwControlCmd                  cmd,    
    void                                 *arg
);

/** ============================================================================
 *   @n@b CSL_i2cRead
 *
 *   @b Description
 *   @n Reads the received data from the I2C Data Receive register
 *
 *   @b Arguments
     @verbatim
            hI2c   Handle of already opened peripheral
            buf    Pointer to memory where data will be read and stored
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Data successfully extracted
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *                  
 *   <b> Pre Condition </b>
 *   @n  Both @a CSL_i2cInit() and @a CSL_i2cOpen() must be called successfully
 *
 *   <b> Post Condition </b>
 *   @n  RSFULL flag bit in ICSTR register is cleared
 *       ICRRDY flag bit in ICSTR register is cleared
 *
 *   @b Modifies
 *   @n buf variable holds the received data
 *
 *   @b Example
 *   @verbatim 
 
        Uint16        inData;
        CSL_Status    status;
        CSL_I2cHandle hI2c;
        ...
        // I2C object defined and HwSetup structure defined and initialized
        ...

        // Init, Open, HwSetup successfully done in that order
        ...

        status = CSL_i2cRead(hI2c, &inData);
     @endverbatim
 *
 *  ============================================================================
 */
extern CSL_Status CSL_i2cRead(    
    CSL_I2cHandle   hI2c,    
    void            *buf
);

/** ============================================================================
 *   @n@b CSL_i2cWrite
 *
 *   @b Description
 *   @n Writes the specified data into I2C Data Transmit register
 *
 *   @b Arguments
     @verbatim
            hI2c   Handle of already opened peripheral
            buf    Pointer to data to be written
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Data successfully written
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *                  
 *   <b> Pre Condition </b>
 *   @n  Both @a CSL_i2cInit() and @a CSL_i2cOpen() must be called successfully
 *
 *   <b> Post Condition </b>
 *   @n  XSMT flag bit in ICSTR register is set
 *       ICXRDY flag bit in ICSTR register is cleared
 *
 *   @b Modifies
 *   @n ICDXR register 
 *
 *
 *  @b Example:
 *  @verbatim

        Uint16          inData;
        CSL_Status      status;
        CSL_I2cHandle   hI2c;
        ...
        // I2C object defined and HwSetup structure defined and initialized
        ...

        // Init, Open, HwSetup successfully done in that order
        ...

        status = CSL_i2cWtrite (hi2c, &inData);
    @endverbatim
 *
 *  ============================================================================
 */
extern CSL_Status CSL_i2cWrite(    
    CSL_I2cHandle   hI2c,    
    void            *buf
);

/** ============================================================================
 *   @n@b CSL_i2cHwSetupRaw
 *
 *   @b Description
 *   @n This function initializes the device registers with the register-values
 *      provided through the Config Data structure.
 *
 *   @b Arguments
 *   @verbatim
            hI2c        Handle to the I2C  
            config      Pointer to config structure
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Configuration successful
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVPARAMS  - Configuration is not
 *                                                properly initialized
 *
 *   <b> Pre Condition </b>
 *   @n  Both CSL_i2cInit() and a CSL_i2cOpen() must be called
 *
 *
 *   <b> Post Condition </b>
 *   @n  The registers of the specified I2C instance will be setup
 *       according to value passed.
 *
 *   @b Modifies
 *   @n Hardware registers of the specified I2C instance.
 *
 *   @b Example
 *   @verbatim
        CSL_I2cHandle       hI2c;
        CSL_I2cConfig       config = CSL_I2C_CONFIG_DEFAULTS;
        CSL_Status          status;

        status = CSL_i2cHwSetupRaw (hI2c, &config);

     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_i2cHwSetupRaw (
    CSL_I2cHandle           hI2c,
    CSL_I2cConfig           *config
);

/** ============================================================================
 *   @n@b CSL_i2cGetHwStatus
 *
 *   @b Description
 *   @n Gets the status of the different operations of I2C.
 *
 *   @b Arguments
 *   @verbatim
            hI2c        Handle to the I2C instance 
            query       The query to this API of I2C which indicates the
                        status to be returned.
            response    Placeholder to return the status.

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Status info return successful
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVQUERY   - Invalid query command
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *
 *   <b> Pre Condition </b>
 *   @n  i2c opened properly
 *
 *   <b> Post Condition </b>
 *   @n  none
 *
 *   @b  Modifies
 *   @n  response variable holds the queried value
 *
 *   @b Example
 *   @verbatim
        CSL_I2cHandle           hI2c;
        CSL_I2cHwStatusQuery    query;
        void                    *reponse;

        status = CSL_Geti2cHwStatus (hI2c, query, &response);

     @endverbatim
 * =============================================================================
 */ 
extern CSL_Status  CSL_i2cGetHwStatus(
    /** Pointer to the object that holds reference to the
    *  instance of I2C requested after the call
    */
    CSL_I2cHandle                         hI2c,
    /** The query to this API which indicates the status
    *  to be returned
    */
    CSL_I2cHwStatusQuery                  query,
    /** Placeholder to return the status. @a void* casted */
    void                                  *response
);


/** ============================================================================
 *   @n@b CSL_i2cGetBaseAddress
 *
 *   @b Description
 *   @n  Function to get the base address of the peripheral instance.
 *       This function is used for getting the base address of the peripheral
 *       instance. This function will be called inside the CSL_i2cOpen()
 *       function call. 
 *
 *   @b Arguments
 *   @verbatim
 
            i2cNum        Specifies the instance of the I2C to be opened.
            pI2cParam     Module specific parameters.   
            pBaseAddress  Pointer to baseaddress structure containing base
                          address details.

     @endverbatim
 *
 *   <b> Return Value </b> CSL_Status
 *   @li                   CSL_OK              Open call is successful
 *   @li                   CSL_ESYS_FAIL       The instance number is invalid.
 *   @li                   CSL_ESYS_INVPARAMS  Invalid parameter 
 *                     
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  Base Address structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable  
 *         2. Base address structure is modified.
 *
 *   @b Example
 *   @verbatim
        CSL_Status          status;
        CSL_I2cBaseAddress  baseAddress;

       ...
      status = CSL_i2cGetBaseAddress (CSL_I2C_0, NULL, &baseAddress);

    @endverbatim
 * ===========================================================================
 */
extern CSL_Status   CSL_i2cGetBaseAddress (
    CSL_InstNum             i2cNum,
    CSL_I2cParam            *pI2cParam,
    CSL_I2cBaseAddress      *pBaseAddress
);

#ifdef __cplusplus
}
#endif


#endif /* _CSL_I2C_H_ */