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

/** @mainpage SPI
 *
 * @section Introduction
 *
 * @subsection xxx Purpose and Scope
 * The purpose of this document is to identify a set of common CSL APIs for
 * the SPI 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 SPI Module. While
 * in other cases this list of APIs may not be sufficient to cover all the
 * features of a particular SPI Module. The CSL developer should use his
 * discretion in designing new APIs or extending the existing ones to cover
 * these.
 *
 *
 * @subsection aaa Terms and Abbreviations
 *   -# CSL:  Chip Support Library
 *   -# API:  Application Programmer Interface
 *   -# SPI:  Serial Port Interface
 *   -# MibSPI1: Multi Buffer SPI
 *
 * @subsection References
 *    -# CSL 3.x Technical Requirements Specifications Version 0.5, dated
 *       May 14th, 2003
 *    -# MibSPI1 functional specification:
 *       http://dspdesign.india.ti.com/twiki/pub/Trinity/TrinityMiBSPI1/SPI_SPI_Platform.pdf
 *
 * @subsection Assumptions
 *     The abbreviations SPI, spi1 and Spi have been used throughout
 *     this document to refer to the Multi Buffer Serial Port Interface Module
 */

/** @file csl_spi.h
 *
 *  @brief Header file for functional layer of SPI CSL
 *
 *  Description
 *    - The different enumerations, structure definitions
 *      and function declarations
 *
 *  Path: \\(CSLPATH)\\ipmodules\\spi\\src
 *
 *  Modification 1
 *    - modified on: 26/12/2003
 *    - reason: created the sources
 *
 *  Modification 2
 *    - modified on: 31/12/2003
 *    - reason: created better documentation
 *
 *  Modification 3
 *    - modified on: 10/05/2004
 *    - reason: removed MIB from code & documnentaion
 *
 *  Date 26th Dec, 2003
 *  Author Sumant S. NaikKhanvte
 */

/* =============================================================================
 *  Revision History
 *  ===============
 *  11-oct-2004 Hs updated code review comments
 *  10-sep-2004 Hs updated CSL_SpiObj and added CSL_SpiBaseAddress,CSL_spiParam,
 *                 CSL_spiContext,  CSL_spiConfig structures.
 *                - Updated comments for H/W control cmd and status query enums.
 *                - Added prototypes for CSL_spiGetBaseAdddress and
 *                  CSL_spiHwSetupRaw.
 *                - Changed prototypes of CSL_spiInit, CSL_spiOpen.
 *                - Updated respective comments along with that of CSL_spiClose.
 * =============================================================================
 */

#ifndef _CSL_SPI_H_
#define _CSL_SPI_H_

#ifdef __cplusplus
extern "C" {
#endif

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

/******************************************************************************\
* SPI global typedef declarations
\******************************************************************************/

/** @brief Enumeration for control commands passed to @a CSL_spiHwControl()
 *
 * This is the set of commands that are passed to the @a CSL_spiHwControl()
 * with an optional argument type-casted to @a void* . The arguments to be
 * passed with each enumeration if any are specified next to the enumeration
 */
typedef enum {
    /**
     * @brief   reset the SPI
     * @param   (None)
     */
    CSL_SPI_CMD_PRI_RESET       =  1,
    /**
     * @brief   power up the SPI
     * @param   (None)
     */
    CSL_SPI_CMD_POWER_UP        =  2,
    /**
     * @brief   power down the SPI
     * @param   (None)
     */
    CSL_SPI_CMD_POWER_DOWN      =  3,
    /**
     * @brief   enable DMA transaction capability for DMA in compatibility mode
     * @param   (None)
     */
    CSL_SPI_CMD_CPT_DMA_ENABLE  =  4,
    /**
     * @brief   enable DMA transaction capability for DMA in compatibility mode
     * @param   (None)
     */
    CSL_SPI_CMD_CPT_DMA_DISABLE =  5,
    /**
     * @brief   write data in argument to SPIDAT0 register for transmitting out
     * @param   Uint16*
     */
    CSL_SPI_CMD_CPT_WRITE0      =  6,
    /**
     * @brief   write data in argument to SPIDAT1 register for transmitting out
     * @param   Uint16*
     */
    CSL_SPI_CMD_CPT_WRITE1      =  7,
    /**
     * @brief   read the data in SPIBUF register to the argument
     * @param   CSL_SpiCptData*
     */
    CSL_SPI_CMD_CPT_READ        =  8,
    /**
     * @brief   enable the interrupts in the bit-vector argument
     * @param   Uint16*
     */
    CSL_SPI_CMD_INT_ENABLE      =  9,
    /**
     * @brief   disable the interrupts in the bit-vector argument
     * @param   Uint16*
     */
    CSL_SPI_CMD_INT_DISABLE     =  10,
    /**
     * @brief   set value passed in argument over pins configured as GPIO
     * @param   Uint16*
     */
    CSL_SPI_CMD_PINS_VALUE      =  11,
    /**
     * @brief   set pins passed in bit-vector argument if configured as GPIO
     * @param   Uint16*
     */
    CSL_SPI_CMD_PINS_SET        =  12,
    /**
     * @brief   clear pins passed in bit-vector argument if configured as GPIO
     * @param   Uint16*
     */
    CSL_SPI_CMD_PINS_CLEAR      =  13,
    /**
     * @brief   enable the data-transfer section of the SPI
     * @param   (None)
     */
    CSL_SPI_CMD_XFER_ENABLE     =  14,
    /**
     * @brief   disable the data-transfer section of the SPI
     * @param   (None)
     */
    CSL_SPI_CMD_XFER_DISABLE    =  15
} CSL_SpiHwControlCmd;

/** @brief Enumeration for queries passed to @a CSL_spiGetHwStatus()
 *
 * This is used to get the status of different operations or to get the
 * existing setup of SPI. The arguments to be passed with each enumeration
 * if any are specified next to the enumeration */
typedef enum {
    /**
     * @brief   get the power status of the SPI
     * @param   CSL_SpiPwrStat*
     */
    CSL_SPI_QUERY_POWER_STATUS      =  1,
    /**
     * @brief   get the value present on the pins as a bit-vector
     * @param   Uint16*
     */
    CSL_SPI_QUERY_PINS_VALUE        =  2,
    /**
     * @brief   get value of highest priority int that has occured on INT0 line
     * @param   CSL_SpiMbfInt*
     */
    CSL_SPI_QUERY_INT_VECTOR0       =  3,
    /**
     * @brief   get value of highest priority int that has occured on INT1 line
     * @param   CSL_SpiMbfInt*
     */
    CSL_SPI_QUERY_INT_VECTOR1       =  4,
    /**
     * @brief   get the bit-vector of interrupts that have been enabled
     * @param   Uint16*
     */
    CSL_SPI_QUERY_INT_ENABLED       =  5,
    /**
     * @brief   get the status of whether DMA is enabled in compatibility mode
     * @param   CSL_SpiCptDma*
     */
    CSL_SPI_QUERY_CPT_DMA_ENABLED   =  6
} CSL_SpiHwStatusQuery;

/** @brief enumeration for Spi general interrupts
 */
typedef enum {
    /** interrupt on successful receive */
    CSL_SPI_INT_RX       =  CSL_FMKT(SPI_SPIINT0_RXINT, ENABLE),
    /** interrupt on receiver overrun */
    CSL_SPI_INT_OVRN     =  CSL_FMKT(SPI_SPIINT0_OVRNINT, ENABLE),
    /** interrupt on bit error */
    CSL_SPI_INT_BITERR   =  CSL_FMKT(SPI_SPIINT0_BITERR, ENABLE),
    /** interrupt on loss of synchronization between master & slave */
    CSL_SPI_INT_DESYNC   =  CSL_FMKT(SPI_SPIINT0_DESYNC, ENABLE),
    /** interrupt on parity error */
    CSL_SPI_INT_PARERR   =  CSL_FMKT(SPI_SPIINT0_PARERR, ENABLE),
    /** interrupt on timeout error */
    CSL_SPI_INT_TIMEOUT  =  CSL_FMKT(SPI_SPIINT0_TIMEOUT, ENABLE)
} CSL_SpiInt;

/** @brief enumeration for Spi status bits
 */
typedef enum {
    /** indicates that a word has been received in SPIBUF */
    CSL_SPI_BUFSTATUS_RXINT   =  (1 << 7),
    /** indicates that receive BUF is empty */
    CSL_SPI_BUFSTATUS_RXEPTY  =  (1 << 6),
    /** indicates that overrun occured/not */
    CSL_SPI_BUFSTATUS_RXOVRN  =  (1 << 5),
    /** indicates that transmit BUF is full */
    CSL_SPI_BUFSTATUS_TXFULL  =  (1 << 4),
    /** indicates that a bit error occurred during transaction */
    CSL_SPI_BUFSTATUS_BITERR  =  (1 << 3),
    /** indicates that desynchronization with slave detected */
    CSL_SPI_BUFSTATUS_DESYNC  =  (1 << 2),
    /** indicates that parity error is detected */
    CSL_SPI_BUFSTATUS_PARITY  =  (1 << 1),
    /** indicates timeout */
    CSL_SPI_BUFSTATUS_TMOUT   =  (1 << 0)
} CSL_SpiBufStatus;

/** @brief enumeration to hold the chip select active between 2 transfers
 */
typedef enum {
    /** hold chip select active between consecutive transfers */
    CSL_SPI_CSHOLD_YES  =  CSL_SPI_SPIDAT1_CSHOLD_YES,
    /** chip select to be inactivated after the each transfer */
    CSL_SPI_CSHOLD_NO   =  CSL_SPI_SPIDAT1_CSHOLD_NO
} CSL_SpiCsHold;

/** @brief enumeration to control applying the format delay to consecutive
 *         transfers
 */
typedef enum {
    /** enable format delay between 2 consecutive transfers */
    CSL_SPI_WDELAYEN_YES  =  CSL_SPI_SPIDAT1_WDEL_DELAY,
    /** disable format delay between 2 consecutive transfers */
    CSL_SPI_WDELAYEN_NO   =  CSL_SPI_SPIDAT1_WDEL_NODELAY
} CSL_SpiWDelayEn;

/** @brief enumeration to select the required data transfer format
 */
typedef enum {
    /** select format 0 */
    CSL_SPI_FMTSEL_0  =  CSL_SPI_SPIDAT1_DFSEL_FMT0,
    /** select format 1 */
    CSL_SPI_FMTSEL_1  =  CSL_SPI_SPIDAT1_DFSEL_FMT1,
    /** select format 2 */
    CSL_SPI_FMTSEL_2  =  CSL_SPI_SPIDAT1_DFSEL_FMT2,
    /** select format 3 */
    CSL_SPI_FMTSEL_3  =  CSL_SPI_SPIDAT1_DFSEL_FMT3
} CSL_SpiFmtSel;

/** @brief enumeration to control the dependence of transfer in ENA signal in
 *         master mode
 */
typedef enum {
    /** if in master mode; wait for ENA signal from slave */
    CSL_SPI_WAITEN_YES  =  CSL_SPI_SPIFMT_WAITEN_YES,
    /** do not wait for ENA signal from slave */
    CSL_SPI_WAITEN_NO   =  CSL_SPI_SPIFMT_WAITEN_NO
} CSL_SpiWaitEn;

/** @brief enumeration to control the parity setting in the data format
 */
typedef enum {
    /** enable even parity */
    CSL_SPI_PARITY_EVEN     =  (CSL_SPI_SPIFMT_PARITY_ENABLE |
                               (CSL_SPI_SPIFMT_PARPOL_EVEN << 1)),
    /** enable odd parity */
    CSL_SPI_PARITY_ODD      =  (CSL_SPI_SPIFMT_PARITY_ENABLE |
                               (CSL_SPI_SPIFMT_PARPOL_ODD << 1)),
    /** disable parity */
    CSL_SPI_PARITY_DISABLE  =  CSL_SPI_SPIFMT_PARITY_DISABLE
} CSL_SpiParity;

/** @brief enumeration to control the polarity of serial clock
 */
typedef enum {
    /** clock is low when inactive */
    CSL_SPI_POLARITY_INACTIVELO = CSL_SPI_SPIFMT_POLARITY_INACTIVELO,
    /** clock is high when inactive */
    CSL_SPI_POLARITY_INACTIVEHI = CSL_SPI_SPIFMT_POLARITY_INACTIVEHI
} CSL_SpiPolarity;

/** @brief enumeration to control phase relationship between data & clock
 */
typedef enum {
    /** data & clock in phase */
    CSL_SPI_PHASE_IN   =  CSL_SPI_SPIFMT_PHASE_IN,
    /** data 1/2 cycle before clock */
    CSL_SPI_PHASE_OUT  =  CSL_SPI_SPIFMT_PHASE_OUT
} CSL_SpiPhase;

/** @brief enumeration to control direction of the word during transfer
 */
typedef enum {
    /** transfer MSB first */
    CSL_SPI_SHDIR_MSBFIRST  =  CSL_SPI_SPIFMT_SHIFTDIR_MSBFIRST,
    /** transfer LSB first */
    CSL_SPI_SHDIR_LSBFIRST  =  CSL_SPI_SPIFMT_SHIFTDIR_LSBFIRST
} CSL_SpiShDir;

/** @brief enumeration to control the protocol of Spi
 */
typedef enum {
    /** use the multi-buffer mode */
    CSL_SPI_PROTOCOL_MULTIBUFFER  =  CSL_SPI_MIBSPIE_MIBSPIENA_YES,
    /** use the compatibility mode */
    CSL_SPI_PROTOCOL_COMPATIBLE   =  CSL_SPI_MIBSPIE_MIBSPIENA_NO
} CSL_SpiProtocol;

/** @brief enumeration to control the operating mode of Spi
 */
typedef enum {
    /** operate as master */
    CSL_SPI_OPMOD_MASTER  =  ((CSL_SPI_SPIGCR1_CLKMOD_INTERNAL << 1) |
                             CSL_SPI_SPIGCR1_MASTER_YES),
    /** operate as slave */
    CSL_SPI_OPMOD_SLAVE   =  ((CSL_SPI_SPIGCR1_CLKMOD_EXTERNAL << 1) |
                             CSL_SPI_SPIGCR1_MASTER_NO)
} CSL_SpiOpMod;

/** @brief enumeration to control the SPIENA status when inactive
 */
typedef enum {
    /** force SPIENA signal high-z when inactive */
    CSL_SPI_ENAHIZ_YES  =  CSL_SPI_SPIINT0_ENAHIGHZ_ENABLE,
    /** keep SPIENA signal a value when inactive */
    CSL_SPI_ENAHIZ_NO   =  CSL_SPI_SPIINT0_ENAHIGHZ_DISABLE
} CSL_SpiEnaHiZ;

/** @brief enumeration for register selection
 */
typedef enum {
    /** operate on functionality register */
    CSL_SPI_GPIOTYPE_FUNC      =  0,
    /** operate on direction register */
    CSL_SPI_GPIOTYPE_DIR       =  1,
    /** operate on pull control register */
    CSL_SPI_GPIOTYPE_PULLCTRL  =  2,
    /** operate on open drain register */
    CSL_SPI_GPIOTYPE_OPNDRAIN  =  3
} CSL_SpiGpioType;

/** @brief enumeration for Spi power modes
 */
typedef enum {
    /** Spi is in active state */
    CSL_SPI_PWRSTAT_ACTIVE  =  CSL_SPI_SPIGCR1_PWRDN_ACTIVE,
    /** Spi is powered down */
    CSL_SPI_PWRSTAT_DOWN    =  CSL_SPI_SPIGCR1_PWRDN_PWRDN
} CSL_SpiPwrStat;

/** @brief enumeartion for Spi serial communication pins
 */
typedef enum {
    /** SOMI pin */
    CSL_SPI_PINTYPE_SOMI  =  CSL_FMKT(SPI_SPIPC0_SOMIFUN, SPI),
    /** SIMO pin */
    CSL_SPI_PINTYPE_SIMO  =  CSL_FMKT(SPI_SPIPC0_SIMOFUN, SPI),
    /** CLK pin */
    CSL_SPI_PINTYPE_CLK   =  CSL_FMKT(SPI_SPIPC0_CLKFUN, SPI),
    /** ENA pin */
    CSL_SPI_PINTYPE_ENA   =  CSL_FMKT(SPI_SPIPC0_ENAFUN, SPI),
    /** SCS7 pin */
    CSL_SPI_PINTYPE_SCS7  =  CSL_FMKT(SPI_SPIPC0_SCSFUN7, SPI),
    /** SCS6 pin */
    CSL_SPI_PINTYPE_SCS6  =  CSL_FMKT(SPI_SPIPC0_SCSFUN6, SPI),
    /** SCS5 pin */
    CSL_SPI_PINTYPE_SCS5  =  CSL_FMKT(SPI_SPIPC0_SCSFUN5, SPI),
    /** SCS4 pin */
    CSL_SPI_PINTYPE_SCS4  =  CSL_FMKT(SPI_SPIPC0_SCSFUN4, SPI),
    /** SCS3 pin */
    CSL_SPI_PINTYPE_SCS3  =  CSL_FMKT(SPI_SPIPC0_SCSFUN3, SPI),