/** @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_spi1.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
 *
 *  Modification 3
 *    - modified on: 10/05/2004
 *    - reason: removed MIB from code & documnentaion
 *
 *  @date 26th Dec, 2003
 *  @author Sumant S. NaikKhanvte
 */

/** @file csl_spi.h
 *
 * @brief   Header file for functional layer of CSL
 *
 * Description
 *    - The defines inline function definitions
 *
 */

/* =============================================================================
 *  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 macro declarations
\**************************************************************************/


/**************************************************************************\
* 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_RXINTEN, ENABLE),
    /** interrupt on receiver overrun */
    CSL_SPI_INT_OVRN     =  CSL_FMKT(SPI_SPIINT0_OVRNINTEN, ENABLE),
    /** interrupt on bit error */
    CSL_SPI_INT_BITERR   =  CSL_FMKT(SPI_SPIINT0_BITERRENA, ENABLE),
    /** interrupt on loss of synchronization between master & slave */
    CSL_SPI_INT_DESYNC   =  CSL_FMKT(SPI_SPIINT0_DESYNCENA, ENABLE),
    /** interrupt on parity error */
    CSL_SPI_INT_PARERR   =  CSL_FMKT(SPI_SPIINT0_PARERRENA, ENABLE),
    /** interrupt on timeout error */
    CSL_SPI_INT_TIMEOUT  =  CSL_FMKT(SPI_SPIINT0_TIMEOUTENA, 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_PARITYENA_ENABLE |
                               (CSL_SPI_SPIFMT_PARPOL_EVEN << 1)),
    /** enable odd parity */
    CSL_SPI_PARITY_ODD      =  (CSL_SPI_SPIFMT_PARITYENA_ENABLE |
                               (CSL_SPI_SPIFMT_PARPOL_ODD << 1)),
    /** disable parity */
    CSL_SPI_PARITY_DISABLE  =  CSL_SPI_SPIFMT_PARITYENA_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_SpiClkPolarity;


/** @brief enumeration to control phase relationship between data & clock */
typedef enum {
    /** data & clock in phase */
    CSL_SPI_PHASE_IN   =  CSL_SPI_SPIFMT_PHASE_IN,