/*  ============================================================================ *   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 __cplusplusextern "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),