/* ============================================================================
* Copyright (c) Texas Instruments Inc 2002, 2003, 2004, 2005, 2008
*
* 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_spi.h
*
* @brief SPI functional layer API header file
*
* Path: \(CSLPATH)/inc
*/
/* ============================================================================
* Revision History
* ================
* 22-Aug-2008 Created
* ============================================================================
*/
/** @defgroup CSL_SPI_API SPI
*
* @section Introduction
*
* @subsection xxx Overview
* SPI stands for Serial periferal interface
*
*/
#ifndef _CSL_SPI_H_
#define _CSL_SPI_H_
#ifdef __cplusplus
extern "C" {
#endif
#include "soc.h"
#include "csl_error.h"
#include "csl_types.h"
#include "csl_general.h"
/**
@defgroup CSL_SPI_SYMBOL SPI Symbols Defined
@ingroup CSL_SPI_API
*/
/**
@defgroup CSL_SPI_DATASTRUCT SPI Data Structures
@ingroup CSL_SPI_API
*/
/**
@defgroup CSL_SPI_FUNCTION SPI Functions
@ingroup CSL_SPI_API
*/
/**
@defgroup CSL_SPI_ENUM SPI Enumerated Data Types
@ingroup CSL_SPI_API
*/
/**
@defgroup CSL_SPI_GLOBALS SPI Global declarations
@ingroup CSL_SPI_API
*/
/*****************************************************************************\
* I2S global macro declarations
\*****************************************************************************/
/**
@addtogroup CSL_SPI_SYMBOL
@{
*/
/** SPI Frame intrupt disable */
#define CSL_SPI_SPICR1_FIRQ_DISABLE (Uint16)0
/** SPI Frame intrupt enable */
#define CSL_SPI_SPICR1_FIRQ_ENABLE (Uint16)1
/** SPI read command */
#define SPI_READ_CMD (Uint16)1
/** SPI write command */
#define SPI_WRITE_CMD (Uint16)2
/** SPI bit disable */
#define SPI_DISABLE (0)
/** SPI bit enable */
#define SPI_ENABLE (1)
/** SPI module active */
#define SPI_ACTIVE (0)
/**
@}*/
/**************************************************************************\
* I2S global enum declaration *
\**************************************************************************/
/**
@addtogroup CSL_SPI_ENUM
@{*/
/**
* \brief SPI chip select.
*
* SPI support four chip select.
*/
typedef enum
{
SPI_CS_NUM_0, /**< SPI device chip select 1 */
SPI_CS_NUM_1, /**< SPI device chip select 2 */
SPI_CS_NUM_2, /**< SPI device chip select 3 */
SPI_CS_NUM_3, /**< SPI device chip select 4 */
SPI_CS_NUM_INVALID /**< SPI device chip select Invalid */
}SPI_HwMode;
/**
* \brief SPI word length.
*
* SPI support maximum 32 bit word length.
*/
typedef enum
{
SPI_WORD_LENGTH_1 = 0, /**< SPI Word length 1 */
SPI_WORD_LENGTH_2, /**< SPI Word length 2 */
SPI_WORD_LENGTH_3, /**< SPI Word length 3 */
SPI_WORD_LENGTH_4, /**< SPI Word length 4 */
SPI_WORD_LENGTH_5, /**< SPI Word length 5 */
SPI_WORD_LENGTH_6, /**< SPI Word length 6 */
SPI_WORD_LENGTH_7, /**< SPI Word length 7 */
SPI_WORD_LENGTH_8, /**< SPI Word length 8 */
SPI_WORD_LENGTH_9, /**< SPI Word length 9 */
SPI_WORD_LENGTH_10, /**< SPI Word length 10 */
SPI_WORD_LENGTH_11, /**< SPI Word length 11 */
SPI_WORD_LENGTH_12, /**< SPI Word length 12 */
SPI_WORD_LENGTH_13, /**< SPI Word length 13 */
SPI_WORD_LENGTH_14, /**< SPI Word length 14 */
SPI_WORD_LENGTH_15, /**< SPI Word length 15 */
SPI_WORD_LENGTH_16, /**< SPI Word length 16 */
SPI_WORD_LENGTH_17, /**< SPI Word length 17 */
SPI_WORD_LENGTH_18, /**< SPI Word length 18 */
SPI_WORD_LENGTH_19, /**< SPI Word length 19 */
SPI_WORD_LENGTH_20, /**< SPI Word length 20 */
SPI_WORD_LENGTH_21, /**< SPI Word length 21 */
SPI_WORD_LENGTH_22, /**< SPI Word length 22 */
SPI_WORD_LENGTH_23, /**< SPI Word length 23 */
SPI_WORD_LENGTH_24, /**< SPI Word length 24 */
SPI_WORD_LENGTH_25, /**< SPI Word length 25 */
SPI_WORD_LENGTH_26, /**< SPI Word length 26 */
SPI_WORD_LENGTH_27, /**< SPI Word length 27 */
SPI_WORD_LENGTH_28, /**< SPI Word length 28 */
SPI_WORD_LENGTH_29, /**< SPI Word length 29 */
SPI_WORD_LENGTH_30, /**< SPI Word length 30 */
SPI_WORD_LENGTH_31, /**< SPI Word length 31 */
SPI_WORD_LENGTH_32, /**< SPI Word length 32 */
SPI_MAX_WORD_LEN /**< SPI Word length invalid */
}SPI_WordLen;
/**
* \brief SPI word intrupt.
*
* SPI word intrupt enable or disable.
*/
typedef enum
{
SPI_WORD_IRQ_DISABLE, /**< SPI Word intrupt disable */
SPI_WORD_IRQ_ENABLE /**< SPI Word intrupt enable */
}SPI_WordCntEnb;
/**
* \brief SPI frame intrupt.
*
* SPI frame intrupt enable or disable.
*/
typedef enum
{
SPI_FRAME_IRQ_DISABLE, /**< SPI frame intrupt disable */
SPI_FRAME_IRQ_ENABLE /**< SPI frame intrupt enable */
}SPI_FrameCntEnb;
/**
* \brief SPI Command.
*
* SPI data read and write command.
*/
typedef enum SPI_Command
{
SPI_RSVD_CMD = 0, /**< SPI reserve command */
SPI_READ, /**< SPI read command */
SPI_WRITE, /**< SPI write command */
SPI_RSVD1_CMD /**< SPI reserve1 command */
} SPI_Command;
/**
* \brief SPI data delay.
*
* SPI supports four data delay.
*/
typedef enum
{
SPI_DATA_DLY_0 = 0, /**< SPI data delay 0 */
SPI_DATA_DLY_1, /**< SPI data delay 1 */
SPI_DATA_DLY_2, /**< SPI data delay 2 */
SPI_DATA_DLY_3, /**< SPI data delay 3 */
SPI_DATA_DLY_UNKNOWN /**< SPI data delay unknowen */
} SPI_DataDly;
/**
* \brief SPI clock polarity.
*
* SPI clock polarity high or low at idle mode.
*/
typedef enum
{
SPI_CLKP_LOW_AT_IDLE = 0, /**< SPI clock polarity low */
SPI_CLKP_HIGH_AT_IDLE /**< SPI clock polarity high */
}SPI_ClkPolarity;
/**
* \brief SPI chip select polarity.
*
* SPI chip select polarity high or low at active mode.
*/
typedef enum
{
SPI_CSP_ACTIVE_LOW = 0, /**< SPI chip select polarity low */
SPI_CSP_ACTIVE_HIGH /**< SPI chip select polarity high */
} SPI_ChipSelPol;
/**
* \brief SPI clock phase.
*
* SPI clock phase falling or rising.
*/
typedef enum
{
SPI_CLK_PH_FALL_EDGE = 0, /**< SPI clock phase falling */
SPI_CLK_PH_RISE_EDGE /**< SPI clock phase resing */
} SPI_ClkPh;
/**
* \brief SPI Operation mode.
*
* SPI operation mode .
*/
typedef enum
{
SPI_POLLING_MODE, /**< SPI Polling mode */
SPI_INTERRUPT_MODE /**< SPI Intrrupt mode */
}SPI_OperMode;
/**
@}*/
/**************************************************************************\
* SPI global data structures *
\**************************************************************************/
/**
\addtogroup CSL_SPI_DATASTRUCT
@{*/
/**
* \brief Object structure.
*
* object structure for handler
*/
typedef struct
{
Uint16 configured; /**< Check for device configuration */
SPI_HwMode mode; /**< Chip select mode */
SPI_OperMode opMode; /**< operation mode */
}CSL_SpiObj;
/**
* \brief Configuration structure.
*
* Hardware register configuration structure
*/
typedef struct
{
Uint16 spiClkDiv; /**< clock division (minimum value is 3)*/
SPI_WordLen wLen; /**< Word length set for data transmission
or receive (supporting 8 bit or 16 bit) */
Uint16 frLen; /** Return Value CSL_SOK
* @n Return value CSL_SOK for success
*
* Pre Condition
* @n This functionality has to call before any function call.
*
* Post Condition
* @n None
*
* @b Modifies
* @n None
*
* @b Example
* @verbatim
void
result = SPI_init();
...
@endverbatim
* ===========================================================================
*/
CSL_Status SPI_init(void);
/** ===========================================================================
* @n@b SPI_deInit
*
* @b Description
* @n This function unintialize and activate the SPI module
*
* @b Arguments
* @verbatim
void No parameter
@endverbatim
*
* Return Value CSL_SOK
* @n Return value CSL_SOK for success
*
* Pre Condition
* @n This function call call after SPI_init function.
*
* Post Condition
* @n SPI_close function can be call after this function call.
*
* @b Modifies
* @n 1. Set the register to activate SPI module
* @n 2.
*
* @b Example
* @verbatim
void
result = SPI_deInit();
...
@endverbatim
* ===========================================================================
*/
CSL_Status SPI_deInit(void);
/** ===========================================================================
* @n@b SPI_open
*
* @b Description
* @n This function returns the handle to the SPI
* instance. This handle is passed to all other CSL APIs.
*
* @b Arguments
* @verbatim
Mode chip select mode.
@endverbatim
*
* Return Value CSL_SpiHandle
* @n Valid SPI handle will be returned if
* handler value is not equal to NULL.
*
* Pre Condition
* @n SPI_init function has to call before call this function.
*
* Post Condition
* @n 1. The status is returned in the status variable. If status
* returned is
* @li NULL - InValid SPI handle is returned
* @n 2.
*
* @b Modifies
* @n 1. CSL_SpiObj SPI object structure
* @n 2.
*
* @b Example
* @verbatim
SPI_HwMode csNum;
SPI_OperMode opMode(Polling/Interrupt)
...
hSpi = SPI_open(SPI_HwMode csNum, SPI_OperMode opMode);
...
@endverbatim
* ===========================================================================
*/
CSL_SpiHandle SPI_open(SPI_HwMode csNum, SPI_OperMode opMode);
/** ===========================================================================
* @n@b SPI_close
*
* @b Description
* @n This function closes the specified handle to SPI.
*
* @b Arguments
* @verbatim
spiHandle Handle to the spi
@endverbatim
*
* Return Value CSL_Status
* @li CSL_SOK - Close successful
* @li CSL_ESYS_BADHANDLE - Invalid handle
*
* Pre Condition
* @n SPI_open() function has to call before call this function.
*
* Post Condition
* @n There should not be any function call after this function call.
*
* @b Modifies
* @n None
*
* @b Example
* @verbatim
CSL_SpiHandle hSpi;
CSL_status status;
status = SPI_close(hSpi);
@endverbatim
* ===========================================================================
*/
CSL_Status SPI_close(CSL_SpiHandle hSpi);
/** ===========================================================================
* @n@b SPI_config
*
* @b Description
* @n It configures the SPI Controller registers of particular handle as per
* the values passed in the SPI config structure.
*
* @b Arguments
* @verbatim
spiHandle Handle to the spi.
spiHwConfig Pointer to spi Config structure.
@endverbatim
*
* Return Value CSL_Status
* @li CSL_SOK - Hardware setup successful
* @li CSL_ESYS_BADHANDLE - Invalid handle
* @li CSL_ESYS_INVPARAMS - Congig Parameter is invalid.
*
* Pre Condition
* @n SPI_open function should call before call this function.
*
* Post Condition
* @n SPI_close function can call after this function call.
*
* @b Modifies
* @n 1. SPI registers will be updated as per config parameter
* @n 2. CSL_SpiObj Object will be updated to store some info
* as passed config parameter.
*
* @b Example
* @verbatim
CSL_SpiHandle hSpi;
SPI_Config spiHwConfig;
Int16 status;
status = SPI_config(hSpi, &spiHwConfig);
...
@endverbatim
* ===========================================================================
*/
CSL_Status SPI_config (CSL_SpiHandle hSpi, SPI_Config *spiHwConfig);
/** ===========================================================================
* @n@b SPI_read
*
* @b Description
* @n This function Read data form specified device.
*
* @b Arguments
* @verbatim
hSpi Pointer to handler
readBuff Pointer to the read buffer.
buffLen Maximum read buffer size.
@endverbatim
*
* Return Value CSL_Status
* @li CSL_SOK - Read successful
* @li CSL_ESYS_BADHANDLE - Invalid handle
*
* Pre Condition
* @n This function can call by SPI_dataTransaction function.
*
* Post Condition
* @n SPI_deInit can be call after this function call.
*
* @b Modifies
* @n
*
* @b Example
* @verbatim
CSL_SpiHandle hSpi
Uint16 readBuff[size];
Uint16 buffLen;
CSL_status status;
status = SPI_read(hSpi,&readBuff, buffLen);
@endverbatim
* ===========================================================================
*/
CSL_Status SPI_read (CSL_SpiHandle hSpi, Uint16 *readBuffer, Uint16 bufLen);
/** ===========================================================================
* @n@b SPI_write
*
* @b Description
* @n This function Write data to specified device.
*
* @b Arguments
* @verbatim
hSpi Pointer to handler
writeBuff Pointer to the write buffer.
buffLen Maximum read buffer size.
@endverbatim
*
* Return Value CSL_Status
* @li CSL_SOK - Write successful
* @li CSL_ESYS_BADHANDLE - Invalid handle
*
* Pre Condition
* This function can call by SPI_dataTransaction function.
*
* Post Condition
* @n SPI_deInit can be call after this function call.
*
* @b Modifies
* @n
*
* @b Example
* @verbatim
CSL_SpiHandle hSpi
Uint16 writeBuff[size];
Uint16 buffLen;
CSL_status status;
status = SPI_write(hSpi,&writeBuff, buffLen);
@endverbatim
* ===========================================================================
*/
CSL_Status SPI_write (CSL_SpiHandle hSpi, Uint16 *writeBuffer, Uint16 bufLen);
/** ===========================================================================
* @n@b SPI_dataTransaction
*
* @b Description
* @n This function read or Write data to specified device.
*
* @b Arguments
* @verbatim
spiHandle Handle to the spi
writeBuff Pointer to the write buffer.
buffLen Maximum read buffer size.
readOrWrite Read or write command.
@endverbatim
*
* Return Value CSL_Status
* @li CSL_SOK - transation success
* @li CSL_ESYS_BADHANDLE - Invalid handle
*
*
* Pre Condition
* This function can after SPI_open function.
*
* Post Condition
* @n SPI_deInit can be call after this function call.
*
* @b Modifies
* @n
*
* @b Example
* @verbatim
CSL_SpiHandle hSpi;
Uint16 writeBuff[size];
Uint16 buffLen;
SPI_Command readOrWrite
CSL_status status;
...
...
status = SPI_dataTransaction(hSpi, &rwBuffer,
rwBufLen, readOrWrite);
@endverbatim
* ===========================================================================
*/
CSL_Status SPI_dataTransaction(CSL_SpiHandle hSpi,
Uint16 *rwBuffer,
Uint16 rwBufLen,
SPI_Command readOrWrite);
/**
@} */
/*****************************************************************************\
* SPI Global variable *
\*****************************************************************************/
/** @addtogroup CSL_SPI_GLOBALS
@{ */
static CSL_SpiObj SPI_Instance;
/**< Object to store the information of SPI Handler */
/**
@} */
#ifdef __cplusplus
}
#endif
#endif /* _CSL_SPI_H_ */