csl_i2c.h

Configuring External Interrupts on TMS320C672x Devices

/*  ============================================================================
 *   Copyright (c) Texas Instruments Inc 2002, 2003, 2004, 2005
 *
 *   Use of this software is controlled by the terms and conditions found
 *   in the license agreement under which this software has been supplied.
 *  ============================================================================
 */
 
/** @mainpage I2C CSL 3.x
 *
 * @section Introduction
 *
 * @subsection xxx Purpose and Scope
 * The purpose of this document is to identify a set of common CSL APIs for
 * the I2C module across various devices. The CSL developer is expected to
 * refer to this document while designing APIs for these modules. Some of the
 * listed APIs may not be applicable to a given I2C module. While other cases
 * this list of APIs may not be sufficient to cover all the features of a
 * particular I2C Module. The CSL developer should use his discretion designing
 * new APIs or extending the existing ones to cover these.
 *
 * @subsection aaa Terms and Abbreviations
 *   -# CSL:  Chip Support Library
 *   -# API:  Application Programmer Interface
 *
 * @subsection References
 *    -# CSL-001-DES, CSL 3.x Design Specification DocumentVersion 1.02
 *
 */

/** @file csl_i2c.h
 *
 * @brief    Header file for functional layer of CSL
 *
 * Description
 *    - The different enumerations, structure definitions
 *      and function declarations
 *
 * Modification 
 *    - modified on: 14/1/2005
 *    - reason: Created the sources
 *	  - Modified on: 25/10/2005
 *	  - Added command for setting I2C as master/slave
 *
 * 
 * @author RMathew.
 *
 */



#ifndef _CSL_I2C_H_
#define _CSL_I2C_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <cslr.h>
#include <csl_error.h>
#include <soc.h>
#include <csl_types.h>
#include <cslr_i2c.h>

/**************************************************************************\
* I2C global macro declarations
\**************************************************************************/


/**
 * @brief   Invalid handle
 */

#define CSL_I2C_BADHANDLE        (0)


/** Constants for passing parameters to the I2C Hardware Setup function  */
/** For setting the SLAVE Mode for I2C           */
#define CSL_I2C_MODE_SLAVE                            (0)
/** For setting the MASTER Mode for I2C          */
#define CSL_I2C_MODE_MASTER                           (1)
/** For setting the RECEIVER Mode for I2C        */
#define CSL_I2C_DIR_RECEIVE                           (0)
/** For setting the TRANSMITTER Mode for I2C     */
#define CSL_I2C_DIR_TRANSMIT                          (1)
/** For setting the 7-bit Addressing Mode for I2C*/
#define CSL_I2C_ADDRSZ_SEVEN                          (0)
/** For setting the 10-bit Addressing Mode       */
#define CSL_I2C_ADDRSZ_TEN                            (1)
/** For Disabling the Start Byte Mode for I2C(Normal Mode) */
#define CSL_I2C_STB_DISABLE                           (0)
/** For Enabling the Start Byte Mode for I2C     */
#define CSL_I2C_STB_ENABLE                            (1)
/** For enabling the tx of a ACK to the TX-ER, while in the RECEIVER mode */
#define CSL_I2C_ACK_ENABLE                            (0)
/** For enabling the tx of a NACK to the TX-ER, while in the RECEIVER mode */
#define CSL_I2C_ACK_DISABLE                           (1)
/** For enabling the free run mode of the I2C */
#define CSL_I2C_FREE_MODE_ENABLE                      (1)
/** For disabling the free run mode of the I2C */
#define CSL_I2C_FREE_MODE_DISABLE                     (0)
/** For enabling the Repeat Mode of the I2C */
#define CSL_I2C_REPEAT_MODE_ENABLE                    (1)
/** For disabling the Repeat Mode of the I2C */
#define CSL_I2C_REPEAT_MODE_DISABLE                   (0)
/** For enabling DLB mode of I2C (applicable only in case of MASTER TX-ER) */
#define CSL_I2C_DLB_ENABLE                            (1)
/** For disabling DLB mode of I2C (applicable only in case of MASTER TX-ER) */
#define CSL_I2C_DLB_DISABLE                           (0)
/** For putting the I2C in Reset */
#define CSL_I2C_IRS_ENABLE                            (0)
/** For taking the I2C out of Reset */
#define CSL_I2C_IRS_DISABLE                           (1)
/** For enabling the Free Data Format of I2C */
#define CSL_I2C_FDF_ENABLE                            (1)
/** For disabling the Free Data Format of I2C */
#define CSL_I2C_FDF_DISABLE                           (0)
/** For enabling the Backward Compatibility mode of I2C */
#define CSL_I2C_BCM_ENABLE                            (1)
/** For disabling the Backward Compatibility mode of I2C */
#define CSL_I2C_BCM_DISABLE                           (0)

/** Constants for passing parameters to the I2C Status Query function */
/** For indicating the non-completion of Reset    */
#define CSL_I2C_RESET_NOT_DONE                        (0)
/** For indicating the completion of Reset    */
#define CSL_I2C_RESET_DONE                            (1)
/** For indicating that the bus is not busy    */
#define CSL_I2C_BUS_NOT_BUSY                          (0)
/** For indicating that the bus is busy    */
#define CSL_I2C_BUS_BUSY                              (1)
/** For indicating that the Receive ready signal is low    */
#define CSL_I2C_RX_NOT_READY                          (0)
/** For indicating that the Receive ready signal is high    */
#define CSL_I2C_RX_READY                              (1)
/** For indicating that the Transmit ready signal is low    */
#define CSL_I2C_TX_NOT_READY                          (0)
/** For indicating that the Transmit ready signal is high    */
#define CSL_I2C_TX_READY                              (1)
/** For indicating that the Access ready signal is low    */
#define CSL_I2C_ACS_NOT_READY                         (0)
/** For indicating that the Access ready signal is high    */
#define CSL_I2C_ACS_READY                             (1)
/** For indicating Single Byte Data signal is set */
#define CSL_I2C_SINGLE_BYTE_DATA                      (1)
/** For indicating Receive overflow signal is set */
#define CSL_I2C_RECEIVE_OVERFLOW                      (1)
/** For indicating Transmit underflow signal is set */
#define CSL_I2C_TRANSMIT_UNDERFLOW                    (1)
/** For indicating Arbitration Lost signal is set */
#define CSL_I2C_ARBITRATION_LOST                      (1)

/** Constants for status bit clear  */
/** Clear the Arbitration Lost status bit        */
#define CSL_I2C_CLEAR_AL 0x1
/** Clear the No acknowledge status bit          */
#define CSL_I2C_CLEAR_NACK 0x2
/** Clear the Register access ready status bit   */
#define CSL_I2C_CLEAR_ARDY 0x4
/** Clear the Receive ready status bit           */
#define CSL_I2C_CLEAR_RRDY 0x8
/** Clear the Transmit ready status bit          */
#define CSL_I2C_CLEAR_XRDY 0x10
/** Clear the Stop Condition Detect  status bit  */
#define CSL_I2C_CLEAR_SCD 0x20

/**************************************************************************\
* I2C global typedef declarations
\**************************************************************************/

/** @brief This object contains the reference to the instance of I2C opened
 *  using the @a CSL_i2cOpen().
 *
 *  The pointer to this, is passed to all I2C CSL APIs.
 */
typedef struct CSL_I2cObj {
    /** Base-address of the Configuration registers of I2C. */
    CSL_I2cRegsOvly regs;
    /** This is the instance of I2C being referred to by this object  */
    CSL_InstNum perNum;
}CSL_I2cObj;

/** @brief This will have the base-address information for the peripheral
 *  instance
 */
typedef struct {
    /** Base-address of the Configuration registers of I2C. */
    CSL_I2cRegsOvly regs;
} CSL_I2cBaseAddress;

/** @brief I2C specific parameters. Present implementation doesn't have
 *  any specific parameters.
 */
typedef struct {
   /** 
    *   Bit mask to be used for module specific parameters.
    *   The below declaration is just a place-holder for future
    *   implementation.
    */
    CSL_BitMask16   flags;
} CSL_I2cParam;

/** 
 *  @brief I2C specific context information. Present implementation doesn't
 *  have any Context information.
 */

typedef struct {
   /** 
    *  Context information of I2C.
    *  The below declaration is just a place-holder for future
    *  implementation.
    */
    Uint16  contextInfo;
} CSL_I2cContext;

typedef struct  {
   /** Config structure of I2C. This is used to configure I2C
    *  using CSL_HwSetupRaw function
    */
    /* I2C Own Address Register */
    volatile Uint16 ICOAR;
    /* I2C Interrupt Mask Register */
    volatile Uint16 ICIMR;
    /* I2C Status Register */
    volatile Uint16 ICSTR;
    /* I2C Clock Divider Low Register */
    volatile Uint16 ICCLKL;
    /* I2C Clock Divider High Register */
    volatile Uint16 ICCLKH;
    /* I2C Data Count Register */
    volatile Uint16 ICCNT;
    /* I2C Slave Address Register */
    volatile Uint16 ICSAR;
    /* I2C Data Transmit Register */
    volatile Uint16 ICDXR;
    /* I2C Mode Register */
    volatile Uint16 ICMDR;
    /* I2C Interrupt Vector Register */
    volatile Uint16 ICIVR;
    /* I2C Extended Mode Register */
    volatile Uint16 ICEMDR;
    /* I2C Prescaler Register */
    volatile Uint16 ICPSC;
    /* I2C Pin Function Register */
    volatile Uint32 ICPFUNC;
    /* I2C Pin Direction Register */
    volatile Uint32 ICPDIR;
    /* I2C Pin Data Out Register */
    volatile Uint32 ICPDOUT;
    /* I2C Pin Data Set Register */
    volatile Uint32 ICPDSET;
    /* I2C Pin Data Clear Register */
    volatile Uint32 ICPDCLR;    
} CSL_I2cConfig;

/** Default Values for Config structure */
#define CSL_I2C_CONFIG_DEFAULTS {   \
        CSL_I2C_ICOAR_RESETVAL,     \
        CSL_I2C_ICIMR_RESETVAL,     \
        CSL_I2C_ICSTR_RESETVAL,     \
        CSL_I2C_ICCLKL_RESETVAL,    \
        CSL_I2C_ICCLKH_RESETVAL,    \
        CSL_I2C_ICCNT_RESETVAL,     \
        CSL_I2C_ICSAR_RESETVAL,     \
        CSL_I2C_ICDXR_RESETVAL,     \
        CSL_I2C_ICMDR_RESETVAL,     \
        CSL_I2C_ICIVR_RESETVAL,     \
        CSL_I2C_ICEMDR_RESETVAL,    \
        CSL_I2C_ICPSC_RESETVAL,     \
        CSL_I2C_ICPFUNC_RESETVAL,   \
        CSL_I2C_ICPDIR_RESETVAL,    \
        CSL_I2C_ICPDOUT_RESETVAL,   \
        CSL_I2C_ICPDSET_RESETVAL,   \
        CSL_I2C_ICPDCLR_RESETVAL    \
}

typedef struct CSL_I2cObj *CSL_I2cHandle;

/** 
 *  @brief This has all the fields required to configure the
 *  I2C clock
 */
typedef struct CSL_I2cClkSetup_{
    /** Prescalar to the input clock     */
    Uint16 prescalar;
    /** Low time period of the clock     */
    Uint16 clklowdiv;
    /** High time period of the clock    */
    Uint16 clkhighdiv;
}CSL_I2cClkSetup;


/** 
 *  @brief This has all the fields required to configure I2C at Power Up
 *  (After a Hardware Reset) or a Soft Reset
 *
 *  This structure is used to setup or obtain existing setup of
 *  I2C using @a CSL_i2cHwSetup() & @a CSL_i2cGetHwSetup() functions
 *  respectively.
 */
typedef struct CSL_I2cHwSetup_ {
    /** Master or Slave Mode : 1==> Master Mode, 0==> Slave Mode  */
    Uint16 mode;
    /** Transmitter Mode or Receiver Mode: 1==> Transmitter Mode,
     *  0 ==> Receiver Mode
     */
    Uint16 dir;
    /** Addressing Mode :0==> 7-bit Mode, 1==> 10-bit Mode       */
    Uint16 addrMode;
    /** Start Byte Mode : 1 ==> Start Byte Mode, 0 ==> Normal Mode */
    Uint16 sttbyteen;
    /** Address of the own device    */
    Uint16 ownaddr;
    /** ACK mode while receiver: 0==> ACK Mode, 1==> NACK Mode */
    Uint16 ackMode;
    /** Run mode of I2C: 0==> No Free Run, 1==> Free Run mode */
    Uint16 runMode;
    /** Repeat Mode of I2C: 0==> No repeat mode 1==> Repeat mode */
    Uint16 repeatMode;
    /** DLBack mode of I2C (master tx-er only):
     *                  0==> No loopback,
     *                  1==> Loopback Mode
     */
    Uint16 loopBackMode;
    /** Free Data Format of I2C:
     *                  0==>Free data format disable,
     *                  1==> Free data format enable
     */
    Uint16 freeDataFormat;
    /** I2C Reset Mode: 0==> Reset, 1==> Out of reset */
    Uint16 resetMode;
    /** I2C Backward Compatibility Mode :
     *                  0==> Not compatible,
     *                  1==> Compatible
     */
    Uint16 bcm;
    /** Interrupt Enable mask The mask can be for one interrupt or
     *  OR of multiple interrupts.
     */
    Uint16 inten;
    /** Prescalar, Clock Low Time and Clock High Time for Clock Setup  */
    CSL_I2cClkSetup *clksetup;
}CSL_I2cHwSetup;


/** @brief Enumeration for queries passed to @a CSL_i2cGetHwStatus()
 *
 * This is used to get the status of different operations or to get the
 * existing setup of I2C.
 */
typedef enum {
    /**
    * @brief   Get current clock setup parameters   
    * @param   (CSL_I2cClkSetup*)
    */
    CSL_I2C_QUERY_CLOCK_SETUP   = 1,
    /**
    * @brief   Get the Bus Busy status information  
    * @param   (Uint16*)
    */
    CSL_I2C_QUERY_BUS_BUSY      = 2,
    /**
    * @brief   Get the Receive Ready status information
    * @param   (Uint16*)
    */
    CSL_I2C_QUERY_RX_RDY        = 3,
    /**
    * @brief   Get the Transmit Ready status information   
    * @param   (Uint16*) 
    */
    CSL_I2C_QUERY_TX_RDY        = 4,
    /**
    * @brief   Get the Register Ready status information 
    * @param   (Uint16*)    
    */
    CSL_I2C_QUERY_ACS_RDY       = 5,
    /**
    * @brief   Get the Stop Condition Data bit information  
    * @param   (Uint16*) 
    */
    CSL_I2C_QUERY_SCD           = 6,
    /**
    * @brief   Get the Address Zero Status (General Call) detection status 
    * @param   (Uint16*)