csl_spi.h

dsp在音频处理中的运用

/** @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
*   -# MibSPI: Multi Buffer SPI
*
* @subsection References
*    -# CSL 3.x Technical Requirements Specifications Version 0.5, dated
*       May 14th, 2003
*    -# MibSPI functional specification: 
*http://dspdesign.india.ti.com/twiki/pub/Trinity/TrinityMiBSPI/SPI_SPI_Platform.pdf
*
*/


/** @file csl_spi.h
 *
 *  @brief Header file for functional layer of CSL
 *
 *  Description
 *    - The different enumerations, structure definitions
 *      and function declarations
 *
 *  Modification 1
 *    - modified on: 26/12/2003
 *    - reason: created the sources
 *
 *  Modification 2
 *    - modified on: 31/12/2003
 *    - reason: created better documentation
 *
 *  @date 26th Dec, 2003
 *  @author Sumant S. NaikKhanvte
 *
 *  Modification 3
 *    - modified on 06/01/2005
 *    - reason: Added -CSL_SPI_CMD_DISABLE command
 *                    -CSL_SpiEnable, CSL_SpiEnaLvl, 
 *                     CSL_SpiIdleMode,CSL_SpiWakeupEn enumeration
 *                    -Macros -Prescale time value macros,
 *                            -Transfer enable macros,
 *                            -Interrupt event macros,
 *                            -Default settings for CSL_SpiConfig structure   
 *                    -CSL_SpiConfig structure
 *                    -Updated documentation
 *
 *  Modification 4
 *    - modified on 04/02/2005
 *    - reason: Removed MibSPI compatiblity and updated documentation 
 *              accordingly.
 *
 *  @author S Prasad
 */

#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 <cslr_spi.h>

/**************************************************************************\
* SPI global macro declarations
\**************************************************************************/


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

/** Transfer enable macros */
/** Spi Read */
#define CSL_SPI_READWRITE           (1)
/** Spi Write */
#define CSL_SPI_WRITE               (2)

/** Prescale time values */
/** scale value 1 */
#define CSL_SPI_PRESCALE_1          (0)
/** scale value 2 */
#define CSL_SPI_PRESCALE_2          (1)
/** scale value 4 */
#define CSL_SPI_PRESCALE_4          (2)
/** scale value 8 */
#define CSL_SPI_PRESCALE_8          (3)
/** scale value 16 */
#define CSL_SPI_PRESCALE_16         (4)
/** scale value 32 */
#define CSL_SPI_PRESCALE_32         (5)
/** scale value 64 */
#define CSL_SPI_PRESCALE_64         (6)
/** scale value 128 */
#define CSL_SPI_PRESCALE_128        (7)
/** scale value 256 */
#define CSL_SPI_PRESCALE_256        (8)
/** scale value 512 */
#define CSL_SPI_PRESCALE_512        (9)
/** scale value 1024 */
#define CSL_SPI_PRESCALE_1024       (10)
/** scale value 2048 */
#define CSL_SPI_PRESCALE_2048       (11)
/** scale value 1096 */
#define CSL_SPI_PRESCALE_4096       (12)

/** Spi general interrupts */
/** Read end */
#define CSL_SPI_INT_RX          CSL_SPI_INT_RX_MASK
/** Write end */
#define CSL_SPI_INT_TX          CSL_SPI_INT_TX_MASK
/** Receive overflow */
#define CSL_SPI_RX_OVRFLW       CSL_SPI_INT_RX_OVER_FLOW_MASK
/** Transmit underflow */
#define CSL_SPI_TX_UNDRFLW      CSL_SPI_INT_TX_UNDER_FLOW_MASK
/** Wakeup enable */
#define CSL_SPI_WAKEUP_EN       CSL_SPI_INT_WAKEUP_MASK

/** @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 {
    /** reset the SPI : no argument */
    CSL_SPI_CMD_PRI_RESET  =  1,
    /** switch on the loop back mode, used in debug */
    CSL_SPI_CMD_DLP_ENABLE,
    /** switch off the loop back mode, used in debug */
    CSL_SPI_CMD_DLP_DISABLE,
    /** enable the DMA transaction capability for DMA : no argument */
    CSL_SPI_CMD_CPT_DMA_ENABLE,
    /** disable the DMA transaction capability for DMA : no argument */
    CSL_SPI_CMD_CPT_DMA_DISABLE,
    /** enable the interrupts : argument :
     * @a Uint16* */
    CSL_SPI_CMD_INT_ENABLE,
    /** disable the interrupts : argument :
     * @a Uint16* */
    CSL_SPI_CMD_INT_DISABLE,
    /** clear the events in the bit-vector argument : argument :
     * @a Uint16* */
    CSL_SPI_CMD_EVT_CLEAR,
    /** enable the data-transfer section of the SPI : no argument */
    CSL_SPI_CMD_XFER_ENABLE,
    /** disable the data-transfer section of the SPI : no argument */
    CSL_SPI_CMD_XFER_DISABLE,
    /** chip select command : argument : chip select id
     * @a Uint8 */
    CSL_SPI_CMD_CSEL_SET,
    /** NBits set : argument : nBits starting from 1
     * @a Uint8 */
    CSL_SPI_CMD_NB_SET,
    /** SPI Enable : no argument */
    CSL_SPI_CMD_ENABLE,
    /** SPI Disable : no arguement */
    CSL_SPI_CMD_DISABLE
} 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 {
    /** get the interrupts that have been enabled : argument :
     * @a Uint16* */
    CSL_SPI_QUERY_INT_ENABLED,
    /** get the events that have occured : argument :
     * @a Uint16* */
    CSL_SPI_QUERY_EVT_STATUS,
    /** get the values of data status register : argument : 
     * @a Uint8* */
    CSL_SPI_QUERY_CPT_BUF_STATUS,
    /** get the status of, whether DMA is enabled : argument : 
     * @a CSL_SpiCptDma* */
    CSL_SPI_QUERY_CPT_DMA_ENABLED
} CSL_SpiHwStatusQuery;

/** @brief enumeration to control the inactive edge of shift register clock */
typedef enum {
    /** Inactive state of clock is low */
    CSL_SPI_POLARITY_LOW    =   0,
    /** Inactive state of clock is high */
    CSL_SPI_POLARITY_HIGH   =   1
} CSL_SpiPolarity;

/** @brief sets the shift register enable level */
typedef enum {
    /** Active level of shift register enable : Low */
    CSL_SPI_ENA_LVL_LOW     =   0,
    /** Active level of shift register enable : High */
    CSL_SPI_ENA_LVL_HIGH    =   1
}CSL_SpiEnaLvl;

/** @brief enumeration to control phase relationship between data & clock */
typedef enum {
    /** Shift register clock toggles at the middle of data transfer */
    CSL_SPI_PHASE_OUT       =   0,
    /** Shift register clock toggles at the beginning of data transfer */
    CSL_SPI_PHASE_IN        =   1
} CSL_SpiPhase;

/** @brief enumeration tocontrol the operating mode of Spi */
typedef enum {
    /** operate as master */
    CSL_SPI_OPMOD_MASTER  =  CSL_SPI_SPISET2_MASTER_YES,
    /** operate as slave */
    CSL_SPI_OPMOD_SLAVE   =  CSL_SPI_SPISET2_MASTER_NO
} CSL_SpiOpMod;

/** @brief enumeration to control DMA enabling in compatibility mode */
typedef enum {
    /** enable dma servicing in compatibility mode */
    CSL_SPI_CPTDMA_ENABLE   =  CSL_SPI_SPISET1_DMA_ENABLE,
    /** disable dma servicing in compatibility mode */
    CSL_SPI_CPTDMA_DISABLE  =  CSL_SPI_SPISET1_DMA_DISABLE
} CSL_SpiCptDma;

/** @brief sets the idle mode configuration */
typedef enum {
    /** Force idle */
    CSL_SPI_FORCE_IDLE      =   CSL_SPI_SPISCR_IDLEMODE_FRC,
    /** No idle */
    CSL_SPI_NO_IDLE         =   CSL_SPI_SPISCR_IDLEMODE_NO,
    /** Smart idle */
    CSL_SPI_SMRT_IDLE       =   CSL_SPI_SPISCR_IDLEMODE_SMRT
}CSL_SpiIdleMode;

/** @brief wakeup enable feature */
typedef enum {
    /** Wakeup enabled */
    CSL_SPI_WAKEUP_ENABLE   =   CSL_SPI_SPISCR_WAKEUPEN_EN,
    /** Wakeup disabled */
    CSL_SPI_WAKEUP_DISABLE  =   CSL_SPI_SPISCR_WAKEUPEN_DIS
}CSL_SpiWakeupEn;

/** @brief internal OCP clock gating strategy */
typedef enum {
    /** OCP clock is free running */
    CSL_SPI_AUTOIDLE_FREE_RUN   =   0,
    /** Automatic OCP clock gating strategy is applied */
    CSL_SPI_AUTOIDLE_CLK_GATED  =   1
}CSL_SpiAutoIdle;

/** @brief this object contains the reference to the instance of SPI
 * opened using the @a CSL_spiOpen()
 *
 * An object related to this structure is passed to all SPI CSL APIs
 * as the first argument */
typedef struct CSL_SpiObj {
    /** This is a pointer to the registers of the instance of SPI referred
     * to by this object */
    CSL_SpiRegsOvly  	regs;
    /** This is the instance of SPI being referred to by this object */
    CSL_InstNum       	perNum;
} CSL_SpiObj;

/** @brief a pointer to @a CSL_SpiObj; this is passed to all SPI CSL
 * APIs */
typedef struct CSL_SpiObj *CSL_SpiHandle;

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

/** @brief Module specific parameters. Present implementation doesn't have
 *  any module 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_SpiParam;

/** @brief Module specific context information. Present implementation doesn't 
 *  have any Context information.
 */
typedef struct {
    /** Context information of SPI.
         *  The below declaration is just a place-holder for future
     *  implementation.
     */
    Uint16              contextInfo;
} CSL_SpiContext;

/** @brief sets up the format for accessing devices connected
 *
 * This object is used to set up or get the setup of the format registers in
 * Spi
 */
typedef struct CSL_SpiFmt {
    /** Clock phase */
    CSL_SpiPhase        clkPhase;
    /** Shift register enable */
    CSL_SpiEnaLvl       enaLvl;
    /** Clock polarity */
    CSL_SpiPolarity     polarity;
}CSL_SpiFmt;

/** @brief main structure that is used to setup the SPI
 * This structure is used to setup or obtain the existing setup of SPI
 * using @a CSL_spiHwSetup() & @a CSL_spiGetHwStatus() functions
 * respectively
 */
typedef struct CSL_SpiHwSetup {
    /** Operation mode */
    CSL_SpiOpMod        opMode;
    /** OCP clock gating strategy */
    CSL_SpiAutoIdle     autoIdle;
    /** Wakeup enable feature */
    CSL_SpiWakeupEn     wakeupEnable;
    /** Idle mode */
    CSL_SpiIdleMode     idleMode;
    /** Prescale value */
    Uint8               prescale;
    /** Devices' access parameters */
    CSL_SpiFmt          spiFmt[5];
}CSL_SpiHwSetup;

/** @brief Command Args for read/write
 *
 * This structure is used as command arg for read/write */
typedef struct CSL_SpiXevArg {
    /** the data to be transmitted/received */
    Uint32              *data;
    /** the size (in bytes) of the data */
    Uint8               nBytes;
} CSL_SpiXevArg;

/** @brief SPI config structure */
typedef struct CSL_SpiConfig {
    /** System configuration register */
    Uint32              SPI_SCR;
    /** Interrupt status register */
    Uint32              SPI_ISR;
    /** Interrupt Enable register */
    Uint32              SPI_IER;
    /** Setup 1 register */
    Uint32              SPI_SET1;
    /** Setup 2 register */
    Uint32              SPI_SET2;
    /** Control register */
    Uint32              SPI_CTRL;
    /** Transmit register */
    Uint32              SPI_TX;
    /** Test register */
    Uint32              SPI_TEST;
} CSL_SpiConfig;

/** default setting for @a CSL_SpiHwSetup */
#define CSL_SPI_HWSETUP_DEFAULTS {  \
    CSL_SPI_OPMOD_MASTER,           \
    CSL_SPI_AUTOIDLE_FREE_RUN,      \
    CSL_SPI_WAKEUP_ENABLE,          \
    CSL_SPI_SMRT_IDLE,              \
    CSL_SPI_PRESCALE_2,             \
    {                               \
        CSL_SPI_FMT_DEFAULTS,       \
        CSL_SPI_FMT_DEFAULTS,       \
        CSL_SPI_FMT_DEFAULTS,       \
        CSL_SPI_FMT_DEFAULTS,       \
        CSL_SPI_FMT_DEFAULTS        \
    }                               \
}

/** default setting for @a CSL_SpiConfig */
#define CSL_SPI_CONFIG_DEFAULTS {   \
    CSL_SPI_SPISCR_RESETVAL,        \
    CSL_SPI_SPIISR_RESETVAL,        \
    CSL_SPI_SPIIER_RESETVAL,        \
    CSL_SPI_SPISET1_RESETVAL,       \
    CSL_SPI_SPISET2_RESETVAL,       \
    CSL_SPI_SPICTRL_RESETVAL,       \
    CSL_SPI_SPITX_RESETVAL,         \
    CSL_SPI_SPITEST_RESETVAL        \