csl_i2c.h

ccs下对dm6446的测试程序

/*  ============================================================================
 *   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.
 *   ===========================================================================
 */

/** @file csl_i2c.h
 *
 *  @brief    Header file for functional layer of CSL
 *
 *  Description
 *    - The different enumerations, structure definitions
 *      and function declarations
 *
 *  PATH  \\(CSLPATH)\\ipmodules\\i2c\\src
 *
 *  Modification 1
 *    - modified on: 28/5/2004
 *    - reason: Created the sources
 *
 *
 *  Date 28th May, 2004
 *  Author Santosh Narayanan.
 */

/** @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 this module. 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 Document Version 1.02
 *    -# i2c_fs_25.pdf, I2C Peripheral Module Design Requirement/Specification
 *       V2.5
 *
 */

/* =============================================================================
 *  Revision History
 *  ===============
 *  11-oct-2004 Hs updated according to code review comments.
 *  30-aug-2004 Hs updated CSL_I2cObj and added CSL_I2cBaseAddress,
 *              CSL_i2cParam, CSL_i2cContext, CSL_i2cConfig structures.
 *               - Updated comments for H/W control cmd and status query enums.
 *               - Added prototypes for CSL_i2cGetBaseAdddress and
 *                 CSL_I2cHwSetupRaw.
 *               - Changed prototypes of CSL_i2cInit, CSL_i2cOpen.
 *               - Updated respective comments along with that of CSL_i2cClose.
 * =============================================================================
 */

#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
\**************************************************************************/

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

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

/* Constants for status bit clear
 */
/** @brief Clear the Arbitration Lost status bit */
#define CSL_I2C_CLEAR_AL 0x1
/** @brief Clear the No acknowledge status bit */
#define CSL_I2C_CLEAR_NACK 0x2
/** @brief Clear the Register access ready status bit */
#define CSL_I2C_CLEAR_ARDY 0x4
/** @brief Clear the Receive ready status bit */
#define CSL_I2C_CLEAR_RRDY 0x8
/** @brief Clear the Transmit ready status bit */
#define CSL_I2C_CLEAR_XRDY 0x10
/** @brief 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 {
    /** The register overlay structure of I2C.
     */
    CSL_I2cRegsOvly regs;
    /** This is the instance of I2C being referred to by this object
     */
    CSL_InstNum perNum;
} CSL_I2cObj;

/** @brief Holds the base-address information for I2C 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;

/** @brief I2C Configuration Structure, is used to configure I2C
 *         using the @a CSL_i2cHwSetupRaw() function.
 */
typedef struct  {
    volatile Uint16 ICOAR;      /**< I2C Own address register       */
    volatile Uint16 ICIMR;      /**< I2C Interrupt Mask register    */
    volatile Uint16 ICSTR;      /**< I2C Status register            */
    volatile Uint16 ICCLKL;     /**< I2C Clock low register         */
    volatile Uint16 ICCLKH;     /**< I2C clock high register        */
    volatile Uint16 ICCNT;      /**< I2C Data Count register        */
    volatile Uint16 ICSAR;      /**< I2C Slave address register     */
    volatile Uint16 ICDXR;      /**< I2C Data Transmit register     */
    volatile Uint16 ICMDR;      /**< I2C Data Receive register      */
    volatile Uint16 ICIVR;      /**< I2C Interrupt vector register  */
    volatile Uint16 ICEMDR;     /**< I2C Extended mode register     */
    volatile Uint16 ICPSC;      /**< I2C Prescalar register         */
    volatile Uint32 ICPFUNC;    /**< I2C GPIO Function register     */
    volatile Uint32 ICPDIR;     /**< I2C GPIO Direction register    */
    volatile Uint32 ICPDOUT;    /**< I2C GPIO data out register     */
    volatile Uint32 ICPDSET;    /**< I2C GPIO data set register     */
    volatile Uint32 ICPDCLR;    /**< I2C GPIO data clear register   */
} CSL_I2cConfig;

/** @brief 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        \
}

/** @brief Handle to the I2C object
 *
 *  Handle is used in all accesses to the device parameters.
 */
typedef struct CSL_I2cObj *CSL_I2cHandle;

/** @brief The clock setup structure has all the fields required to configure
 *         the I2C clock.
 */
typedef struct {
    /** 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 {
    /** 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 and Clock High 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,