/*   ==========================================================================
 *   Copyright (c) Texas Instruments Inc , 2004
 *
 *   Use of this software is controlled by the terms and conditions found
 *   in the license agreement under which this software has been supplied
 *   provided
 *   ==========================================================================
*/

/** @mainpage MCBSP CSL 3.x
 *
 * @section Introduction
 *
 * @subsection xxx Purpose and Scope
 *  The purpose of this document is to identify a set of common CSL APIs for
 *  the MCBSP 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 MCBSP module.While other cases
 *  this list of APIs may not be sufficient to cover all the features of a
 *  particular MCBSP Module. The CSL developer should use his discretion 
 *  designing new APIs or extending the existing ones to cover these.
 *
 * @subsection aaa Terms and Abbreviations
 *   -# CSL:  Chip Support Library
 *   -# API:  Application Programmer Interface
 *
 * @subsection References
 *    -# CSL-001-DES, CSL 3.x Design Specification DocumentVersion 1.02
 *
 */


/** @file csl_mcbsp.h
 *
 *  @brief Header file for functional layer of McBSP CSL
 *
 *  Description
 *  - The different symbolic constants, enumerations, structure definitions
 *    and function prototype declarations
 *
 *  @date    29 June, 2004
 *  @author  Pratheesh Gangadhar
 */

/* ============================================================================
 *  Revision History
 *  ===============
 *  15-Feb-2005 NSR  updated CSL_McbspObj and added CSL_McbspBaseAddress,
 *                  CSL_McbspParam,CSL_McbspContext,CSL_McbspConfig structures.
 *               - Updated comments for H/W control cmd and status query enums.
 *               - Added prototypes for CSL_mcbspGetBaseAdddress and
 *                 CSL_mcbspHwSetupRaw.
 *               - Changed prototypes of CSL_mcbspInit, CSL_mcbspOpen.
 *               - Updated respective comments along with that of
 *                 CSL_mcbspClose.
 * ============================================================================
 */

/**
 * @defgroup CSL_MCBSP_API MCBSP
 */

/**
 * @defgroup CSL_MCBSP_DATASTRUCT MCBSP Data Structures
 * @ingroup CSL_MCBSP_API
 */
/**
 * @defgroup CSL_MCBSP_SYMBOL  Symbols
 * @ingroup CSL_MCBSP_API
 */
/**
 * @defgroup CSL_MCBSP_ENUM  Enumerated Data Types
 * @ingroup CSL_MCBSP_API
 */
/**
 * @defgroup CSL_MCBSP_FUNCTION  Functions
 * @ingroup CSL_MCBSP_API
 */

#ifndef _CSL_MCBSP_H_
#define _CSL_MCBSP_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <soc.h>
#include <csl_types.h>
#include <csl_error.h>
#include <cslr_mcbsp.h>
#include <csl_resId.h>
/**************************************************************************\
* MCBSP global macro declarations
\**************************************************************************/

/** @defgroup CSL_MCBSP_IO_SYMBOL General purpose IO pin selection
 * @ingroup CSL_MCBSP_SYMBOL
 *
 * Use this symbol as pin mask for @a CSL_mcbspIoRead() and
 * @a CSL_mcbspIoWrite() functions
 *
 * @{ */
/** I/O Pin Input/Output configuration for CLKX Pin       */
#define CSL_MCBSP_IO_CLKX                             (1)

/** I/O Pin Input/Output configuration for FSX  Pin       */
#define CSL_MCBSP_IO_FSX                              (2)

/** Not Configurable. Always Output.                      */
#define CSL_MCBSP_IO_DX                               (4)

/** I/O Pin Input/Output configuration for CLKR Pin       */
#define CSL_MCBSP_IO_CLKR                             (8)

/** I/O Pin Input/Output configuration for FSR Pin        */
#define CSL_MCBSP_IO_FSR                              (16)

/** Not Configurable. Always Input.                        */
#define CSL_MCBSP_IO_DR                               (32)

/** Not Configurable. Always Input.                        */
#define CSL_MCBSP_IO_CLKS                             (64)
/**
@} */


/** @defgroup CSL_MCBSP_IDLECTRL_SYMBOL Idle Control
 * @ingroup CSL_MCBSP_SYMBOL
 *
 * Use this symbol as enable/disable idle control bitmask for
 * @a CSL_mcbspHwControl() function
 *
 * @{ */
/** To disable idle controller */
#define CSL_MCBSP_CTRL_IDLE_DISABLE                     (0)

/** To enable idle controller  */
#define CSL_MCBSP_CTRL_IDLE_ENABLE                      (1)
/**
@} */



/** @defgroup CSL_MCBSP_CTRL_SYMBOL Enable/Disable Controls
 * @ingroup CSL_MCBSP_SYMBOL
 *
 * Use this symbol as enable/disable control bitmask for
 * @a CSL_mcbspHwControl() function
 *
 * @{ */
/** To enable Receiver in resetControl Function             */
#define CSL_MCBSP_CTRL_RX_ENABLE                      (1)

/** To enable Transmitter in resetControl Function          */
#define CSL_MCBSP_CTRL_TX_ENABLE                      (2)

/** To disable Receiver in resetControl Function            */
#define CSL_MCBSP_CTRL_RX_DISABLE                     (4)

/** To disable Transmitter in resetControl Function         */
#define CSL_MCBSP_CTRL_TX_DISABLE                     (8)

/** To enable Frame Sync Generation in resetControl Function */
#define CSL_MCBSP_CTRL_FSYNC_ENABLE                   (16)

/** To enable Sample Rate Generator in resetControl Function */
#define CSL_MCBSP_CTRL_SRG_ENABLE                     (32)

/** To disable Frame Sync Generation in resetControl Function */
#define CSL_MCBSP_CTRL_FSYNC_DISABLE                  (64)

/** To disable Sample Rate Generator in resetControl Function */
#define CSL_MCBSP_CTRL_SRG_DISABLE                    (128)
/**
@} */

/** @defgroup CSL_DEVSTATUS_SYMBOL RCV/XMT status symbols
 * @ingroup CSL_MCBSP_SYMBOL
 *
 * Use this symbol to compare the return value of @a CSL_mcbspGetHwStatus()
 * function for @a CSL_MCBSP_QUERY_DEV_STATUS query
 * \n For eg:- On RFULL event, (response & CSL_MCBSP_RFULL) == 0x0004
 *
 * @{ */
/** RCV ready status */
#define CSL_MCBSP_RRDY        0x0001
/** XMT ready status */
#define CSL_MCBSP_XRDY        0x0002
/** RCV full status */
#define CSL_MCBSP_RFULL       0x0004
/** XMT empty status */
#define CSL_MCBSP_XEMPTY      0x0008
/** RCV frame sync error status */
#define CSL_MCBSP_RSYNCERR    0x0010
/** XMT frame sync error status */
#define CSL_MCBSP_XSYNCERR    0x0020
/**
@} */

/** @defgroup CSL_EMCBSP_SYMBOL Error codes
 * @ingroup CSL_MCBSP_SYMBOL
 *
 * @{ */
/** Invalid Control Command */
#define CSL_EMCBSP_INVCNTLCMD                         (CSL_EMCBSP_FIRST - 0)

/** Invalid Query */
#define CSL_EMCBSP_INVQUERY                           (CSL_EMCBSP_FIRST - 1)

/** Invalid Parameter */
#define CSL_EMCBSP_INVPARAMS                          (CSL_EMCBSP_FIRST - 2)

/** Invalid Size */
#define CSL_EMCBSP_INVSIZE                            (CSL_EMCBSP_FIRST - 3)

/** 'Does not exist' */
#define CSL_EMCBSP_NOTEXIST                           (CSL_EMCBSP_FIRST - 4)

/** Invalid mode to conduct operation */
#define CSL_EMCBSP_INVMODE                            (CSL_EMCBSP_FIRST - 5)
/**
@} */

/**
 * @defgroup CSL_MCBSP_DEFAULT_SYMBOL MCBSP CSL Defaults
 * @ingroup CSL_MCBSP_SYMBOL
 *
 * @{ */

/** Data Setup defaults */
#define CSL_MCBSP_DATASETUP_DEFAULTS   {                  \
    (CSL_McbspPhase)CSL_MCBSP_PHASE_SINGLE,               \
    (CSL_McbspWordLen)CSL_MCBSP_WORDLEN_16,               \
    1,                                                    \
    (CSL_McbspWordLen)0,                                  \
    0,                                                    \
    (CSL_McbspFrmSync)CSL_MCBSP_FRMSYNC_DETECT,           \
    (CSL_McbspCompand)CSL_MCBSP_COMPAND_OFF_MSB_FIRST,    \
    (CSL_McbspDataDelay)CSL_MCBSP_DATADELAY_0_BIT,        \
    (CSL_McbspRjustDxena)0,                               \
    (CSL_McbspIntMode)CSL_MCBSP_INTMODE_ON_READY,         \
    (CSL_McbspBitReversal)CSL_MCBSP_32BIT_REVERS_DISABLE }\


/** Clock Setup defaults */
#define CSL_MCBSP_CLOCKSETUP_DEFAULTS  {                \
    (CSL_McbspFsClkMode)CSL_MCBSP_FSCLKMODE_EXTERNAL,      \
    (CSL_McbspFsClkMode)CSL_MCBSP_FSCLKMODE_EXTERNAL,      \
    (CSL_McbspTxRxClkMode)CSL_MCBSP_TXRXCLKMODE_INTERNAL,  \
    (CSL_McbspTxRxClkMode)CSL_MCBSP_TXRXCLKMODE_EXTERNAL,  \
    (CSL_McbspFsPol)0,                                     \
    (CSL_McbspFsPol)0,                                     \
    (CSL_McbspClkPol)0,                                    \
    (CSL_McbspClkPol)0,                                    \
    1,                                                     \
    0x40,                                                  \
    0xFF,                                                  \
    (CSL_McbspSrgClk)0,                                    \
    (CSL_McbspClkPol)0,                                    \
    (CSL_McbspTxFsMode)CSL_MCBSP_TXFSMODE_SRG,             \
    (CSL_McbspClkgSyncMode)CSL_MCBSP_CLKGSYNCMODE_OFF     }\


/** Multichannel Setup defaults */
#define CSL_MCBSP_MULTICHAN_DEFAULTS  {                 \
    (CSL_McbspPartMode)CSL_MCBSP_PARTMODE_2PARTITION,      \
    (CSL_McbspPartMode)CSL_MCBSP_PARTMODE_2PARTITION,      \
    (Uint16)0,                                             \
    (Uint16)0,                                             \
    (CSL_McbspPABlk)CSL_MCBSP_PABLK_0,                     \
    (CSL_McbspPBBlk)CSL_MCBSP_PBBLK_1,                     \
    (CSL_McbspPABlk)CSL_MCBSP_PABLK_0,                     \
    (CSL_McbspPBBlk)CSL_MCBSP_PBBLK_1,                     \
    (Uint16)0,                                             \
    (Uint16)0                                             }\


/** Global parameters Setup defaults */
#define CSL_MCBSP_GLOBALSETUP_DEFAULTS  {                  \
    (CSL_McbspIOMode)CSL_MCBSP_IOMODE_TXDIS_RXDIS,         \
    (CSL_McbspDlbMode)CSL_MCBSP_DLBMODE_OFF,               \
    (CSL_McbspClkStp)CSL_MCBSP_CLKSTP_DISABLE }            \


/** Default Emulation mode - Stop */
#define CSL_MCBSP_EMUMODE_DEFAULT  CSL_MCBSP_EMU_STOP

/** Default DX state */
#define CSL_MCBSP_DXSTATE_DEFAULT  CSL_MCBSP_DX_HIGHZ

/** Default Receive superframe configuration */
#define CSL_MCBSP_RSYNCCNT_DEFAULT  (Uint16)0

/** Default Transmit superframe configuration */
#define CSL_MCBSP_XSYNCCNT_DEFAULT  (Uint16)0

/** Extend Setup default - NULL */
#define CSL_MCBSP_EXTENDSETUP_DEFAULT  NULL


/**
@} */

/**************************************************************************\
* MCBSP global typedef declarations
\**************************************************************************/

/**
 * @defgroup CSL_MCBSP_WORDLEN_ENUM Word length
 * @ingroup CSL_MCBSP_ENUM
 *
 * @brief Word lengths supported on MCBSP
 *
 * Use this symbol for setting Word Length in each Phase for every Frame
 * @{ */
typedef enum {
    /** Word Length for Frame is 8 */
    CSL_MCBSP_WORDLEN_8        =                  0,
    /** Word Length for Frame is 12 */
    CSL_MCBSP_WORDLEN_12       =                  1,
    /** Word Length for Frame is 16 */
    CSL_MCBSP_WORDLEN_16       =                  2,
    /** Word Length for Frame is 20 */
    CSL_MCBSP_WORDLEN_20       =                  3,
    /** Word Length for Frame is 24 */
    CSL_MCBSP_WORDLEN_24       =                  4,
    /** Word Length for Frame is 32 */
    CSL_MCBSP_WORDLEN_32       =                  5
} CSL_McbspWordLen;
/**
@} */

/**
 * @defgroup CSL_MCBSP_COMPAND_ENUM Companding options
 * @ingroup CSL_MCBSP_ENUM
 *
 * @brief MCBSP companding options
 *
 * Use this symbol to set Companding related options
 * @{ */
typedef enum {
    /** no companding for msb */
    CSL_MCBSP_COMPAND_OFF_MSB_FIRST =                 0,
    /** no companding for lsb */
    CSL_MCBSP_COMPAND_OFF_LSB_FIRST =                 1,
    /** mu-law comapanding enable for channel */
    CSL_MCBSP_COMPAND_MULAW         =                 2,
    /** A-law comapanding enable for channel */
    CSL_MCBSP_COMPAND_ALAW          =                 3
} CSL_McbspCompand;
/**
@} */

/**
 * @defgroup CSL_MCBSP_DATADELAY_ENUM Data delay
 * @ingroup CSL_MCBSP_ENUM
 *
 * @brief Data delay in bits
 *
 * Use this symbol to set XMT/RCV Data Delay (in bits)
 * @{ */
typedef enum {
    /** sets XMT/RCV Data Delay is 0 */
    CSL_MCBSP_DATADELAY_0_BIT      =                 0,
    /** sets XMT/RCV Data Delay is 1 */
    CSL_MCBSP_DATADELAY_1_BIT      =                 1,
    /** sets XMT/RCV Data Delay is 2 */
    CSL_MCBSP_DATADELAY_2_BITS     =                 2
} CSL_McbspDataDelay;
/**
@} */

/**
 * @defgroup CSL_MCBSP_EVENT_ENUM Interrupt mode
 * @ingroup CSL_MCBSP_ENUM
 *
 * @brief MCBSP Interrupt mode
 *
 * Use this symbol to set Interrupt mode (i.e. source of interrupt generation).
 * This symbol is used on both RCV and XMT for RINT and XINT generation mode.
 * @{ */
typedef enum {
    /** Interrupt generated on RRDY of RCV or XRDY of XMT */
    CSL_MCBSP_INTMODE_ON_READY         =                  0,
    /** Interrupt generated on end of 16-channel block transfer
     *  in multichannel mode */
    CSL_MCBSP_INTMODE_ON_EOB           =                  1,
    /** Interrupt generated on frame sync */
    CSL_MCBSP_INTMODE_ON_FSYNC         =                  2,
    /** Interrupt generated on synchronisation error */
    CSL_MCBSP_INTMODE_ON_SYNCERR       =                  3
} CSL_McbspIntMode;
/**
@} */

/**
 * @defgroup CSL_MCBSP_FSCLKMODE_ENUM Frame sync clock source
 * @ingroup CSL_MCBSP_ENUM
 *
 * @brief Frame sync clock source
 *
 * Use this symbol to set the frame sync clock source as internal or external
 * @{ */
typedef enum {
    /** frame sync clock source as internal */
    CSL_MCBSP_FSCLKMODE_EXTERNAL    =                  0,
    /** frame sync clock source as external */
    CSL_MCBSP_FSCLKMODE_INTERNAL    =                  1
} CSL_McbspFsClkMode;
/**
@} */

/**
 * @defgroup CSL_MCBSP_CLKMODE_ENUM Clock Mode
 * @ingroup CSL_MCBSP_ENUM
 *
 * @brief Clock source
 *
 * Use this symbol to set the clock source as internal or external
 * @{ */
typedef enum {
    /** clock source as internal */
    CSL_MCBSP_TXRXCLKMODE_EXTERNAL    =                  0,
    /** clock source as external */
    CSL_MCBSP_TXRXCLKMODE_INTERNAL    =                  1
} CSL_McbspTxRxClkMode;
/**
@} */

/**
 * @defgroup CSL_MCBSP_FSPOLAR_ENUM Frame sync polarity
 * @ingroup CSL_MCBSP_ENUM
 *
 * @brief Frame sync polarity