Spi.h

Go to the documentation of this file.

/*
*
* Copyright (c) 2019 Texas Instruments Incorporated
*
* All rights reserved not granted herein.
*
* Limited License.
*
* Texas Instruments Incorporated grants a world-wide, royalty-free, non-exclusive
* license under copyrights and patents it now or hereafter owns or controls to make,
* have made, use, import, offer to sell and sell ("Utilize") this software subject to the
* terms herein.  With respect to the foregoing patent license, such license is granted
* solely to the extent that any such patent is necessary to Utilize the software alone.
* The patent license shall not apply to any combinations which include this software,
* other than combinations with devices manufactured by or for TI ("TI Devices").
* No hardware patent is licensed hereunder.
*
* Redistributions must preserve existing copyright notices and reproduce this license
* (including the above copyright notice and the disclaimer and (if applicable) source
* code license limitations below) in the documentation and/or other materials provided
* with the distribution
*
* Redistribution and use in binary form, without modification, are permitted provided
* that the following conditions are met:
*
* *       No reverse engineering, decompilation, or disassembly of this software is
* permitted with respect to any software provided in binary form.
*
* *       any redistribution and use are licensed by TI for use only with TI Devices.
*
* *       Nothing shall obligate TI to provide you with source code for the software
* licensed and provided to you in object code.
*
* If software source code is provided to you, modification and redistribution of the
* source code are permitted provided that the following conditions are met:
*
* *       any redistribution and use of the source code, including any resulting derivative
* works, are licensed by TI for use only with TI Devices.
*
* *       any redistribution and use of any object code compiled from the source code
* and any resulting derivative works, are licensed by TI for use only with TI Devices.
*
* Neither the name of Texas Instruments Incorporated nor the names of its suppliers
*
* may be used to endorse or promote products derived from this software without
* specific prior written permission.
*
* DISCLAIMER.
*
* THIS SOFTWARE IS PROVIDED BY TI AND TI'S LICENSORS "AS IS" AND ANY EXPRESS
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL TI AND TI'S LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
* OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
*
*/

/* Design : SPI_DesignId_001, SPI_DesignId_002, SPI_DesignId_005,
 *          SPI_DesignId_006, SPI_DesignId_024, SPI_DesignId_008 */
/*
 * Below are the global requirements which are met by this SPI handler
 * driver which can't be mapped to a particular source ID
 */
/*
 * Requirements : MCAL-1237, MCAL-1241, MCAL-1242, MCAL-1243,
 *                MCAL-1263, MCAL-1273, MCAL-1274, MCAL-1280,
 *                MCAL-1295, MCAL-1498, MCAL-1505, MCAL-1296,
 *                MCAL-1266, MCAL-1267, MCAL-1329, MCAL-1268
 *                MCAL-981,  MCAL-4482, MCAL-4474
 */

/*
 * Below are the SPI's module environment requirements which can't be mapped
 * to this driver.
 */
/* Design : SPI_DesignId_023 */
/*
 * Requirements : MCAL-1446, MCAL-1456, MCAL-1461, MCAL-1238,
 *                MCAL-1429, MCAL-1501, MCAL-1479, MCAL-1271,
 *                MCAL-1270
 */

#ifndef SPI_H_
#define SPI_H_

/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */

#include "Std_Types.h"
#include "Spi_Cfg.h"
#include "Spi_Irq.h"
#include <ti/drv/udma/udma.h>

#ifdef __cplusplus
extern "C"
{
#endif

/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */

#define SPI_SW_MAJOR_VERSION            (1U)

#define SPI_SW_MINOR_VERSION            (3U)

#define SPI_SW_PATCH_VERSION            (2U)
/* @} */

#define SPI_AR_RELEASE_MAJOR_VERSION    (4U)

#define SPI_AR_RELEASE_MINOR_VERSION    (3U)

#define SPI_AR_RELEASE_REVISION_VERSION (1U)
/* @} */

#define SPI_VENDOR_ID                   ((uint16) 44U)

#define SPI_MODULE_ID                   ((uint16) 83U)

#define SPI_INSTANCE_ID                 ((uint8) 0U)
/* @} */

#define SPI_UNIT_MCU_MCSPI0                 ((Spi_HWUnitType) CSIB0)

#define SPI_UNIT_MCU_MCSPI1                 ((Spi_HWUnitType) CSIB1)

#define SPI_UNIT_MCU_MCSPI2                 ((Spi_HWUnitType) CSIB2)

#define SPI_UNIT_MCSPI0                     ((Spi_HWUnitType) CSIB3)

#define SPI_UNIT_MCSPI1                     ((Spi_HWUnitType) CSIB4)

#define SPI_UNIT_MCSPI2                     ((Spi_HWUnitType) CSIB5)

#define SPI_UNIT_MCSPI3                     ((Spi_HWUnitType) CSIB6)
#if defined (SOC_J721E) || defined (SOC_J7200)

#define SPI_UNIT_MCSPI4                     ((Spi_HWUnitType) CSIB7)

#define SPI_UNIT_MCSPI5                     ((Spi_HWUnitType) CSIB8)

#define SPI_UNIT_MCSPI6                     ((Spi_HWUnitType) CSIB9)

#define SPI_UNIT_MCSPI7                     ((Spi_HWUnitType) CSIB10)
#endif
/* @} */

#if defined (SOC_J721E) || defined (SOC_J7200)
#define SPI_HW_UNIT_CNT                 (11U)
#endif

#define SPI_IB                          (0U)

#define SPI_EB                          (1U)

#define SPI_IB_EB                       (2U)
/* @} */


/* Requirements : MCAL-1363, MCAL-1364, MCAL-1365 */
typedef uint8 Spi_DataBufferType;
/* Requirements : MCAL-1366, MCAL-1367 */
typedef uint16 Spi_NumberOfDataType;
/* Requirements : MCAL-1368, MCAL-1369, MCAL-1370 */
typedef uint8 Spi_ChannelType;
/* Requirements : MCAL-1371, MCAL-1372, MCAL-1373 */
typedef uint16 Spi_JobType;
/* Requirements : MCAL-1374, MCAL-1375, MCAL-1376 */
typedef uint8 Spi_SequenceType;
/* Requirements : MCAL-1377, MCAL-1378, MCAL-1379 */
typedef uint8 Spi_HWUnitType;

#ifndef SPI_E_PARAM_CHANNEL

#define SPI_E_PARAM_CHANNEL             ((uint8) 0x0AU)
#endif
#ifndef SPI_E_PARAM_JOB

#define SPI_E_PARAM_JOB                 ((uint8) 0x0BU)
#endif
#ifndef SPI_E_PARAM_SEQ

#define SPI_E_PARAM_SEQ                 ((uint8) 0x0CU)
#endif
#ifndef SPI_E_PARAM_LENGTH

#define SPI_E_PARAM_LENGTH              ((uint8) 0x0DU)
#endif
#ifndef SPI_E_PARAM_UNIT

#define SPI_E_PARAM_UNIT                ((uint8) 0x0EU)
#endif
#ifndef SPI_E_PARAM_POINTER

#define SPI_E_PARAM_POINTER             ((uint8) 0x10U)
#endif
#ifndef SPI_E_UNINIT

#define SPI_E_UNINIT                    ((uint8) 0x1AU)
#endif
#ifndef SPI_E_SEQ_PENDING

#define SPI_E_SEQ_PENDING               ((uint8) 0x2AU)
#endif
#ifndef SPI_E_SEQ_IN_PROCESS

#define SPI_E_SEQ_IN_PROCESS            ((uint8) 0x3AU)
#endif
#ifndef SPI_E_ALREADY_INITIALIZED

#define SPI_E_ALREADY_INITIALIZED       ((uint8) 0x4AU)
#endif
#ifndef SPI_E_SEQUENCE_NOT_OK

#define SPI_E_SEQUENCE_NOT_OK           ((uint8) 0x5AU)
#endif

/* @} */

#define SPI_SID_INIT                    ((uint8) 0x00U)

#define SPI_SID_DEINIT                  ((uint8) 0x01U)

#define SPI_SID_WRITE_IB                ((uint8) 0x02U)

#define SPI_SID_ASYNC_TRANSMIT          ((uint8) 0x03U)

#define SPI_SID_READ_IB                 ((uint8) 0x04U)

#define SPI_SID_SETUP_EB                ((uint8) 0x05U)

#define SPI_SID_GET_STATUS              ((uint8) 0x06U)

#define SPI_SID_GET_JOB_RESULT          ((uint8) 0x07U)

#define SPI_SID_GET_SEQ_RESULT          ((uint8) 0x08U)

#define SPI_SID_GET_VERSION_INFO        ((uint8) 0x09U)

#define SPI_SID_SYNC_TRANSMIT           ((uint8) 0x0AU)

#define SPI_SID_GET_HW_UNIT_STATUS      ((uint8) 0x0BU)

#define SPI_SID_CANCEL                  ((uint8) 0x0CU)

#define SPI_SID_SET_ASYNC_MODE          ((uint8) 0x0DU)

#define SPI_SID_MAINFUNCTION_HANDLING   ((uint8) 0x10U)
/* @} */

/* Requirements : MCAL-1232 */
#define SPI_MCSPI_FCLK                  (48000000U)

#define  SPI_CFG_ID_0     (0x01U)

#define  SPI_CFG_ID_1     (0x02U)

#define  SPI_CFG_ID_2     (0x04U)

#define  SPI_CFG_ID_3     (0x08U)

#define  SPI_CFG_ID_4     (0x10U)

#define  SPI_CFG_ID_5     (0x20U)
/* @} */

/* ========================================================================== */
/*                         Structures and Enums                               */
/* ========================================================================== */

/* Requirements : MCAL-1340, MCAL-1341, MCAL-1344 */
typedef enum
{
    SPI_UNINIT = 0U,
    SPI_IDLE = 1U,
    SPI_BUSY = 2U
} Spi_StatusType;

typedef enum
{
    CSIB0 = 0U,
    CSIB1,
    CSIB2,
    CSIB3,
    CSIB4,
    CSIB5,
    CSIB6,
#if defined (SOC_J721E) || defined (SOC_J7200)
    CSIB7,
    CSIB8,
    CSIB9,
    CSIB10,
#endif
} Spi_HwUnitType;

/* Requirements : MCAL-1350, MCAL-1351, MCAL-1353 */
typedef enum
{
    SPI_JOB_OK = 0U,
    SPI_JOB_PENDING = 1U,
    SPI_JOB_FAILED = 2U,
    SPI_JOB_QUEUED = 3U
} Spi_JobResultType;

/* Requirements : MCAL-1355, MCAL-1357, MCAL-1359 */
typedef enum
{
    SPI_SEQ_OK = 0U,
    SPI_SEQ_PENDING = 1U,
    SPI_SEQ_FAILED = 2U,
    SPI_SEQ_CANCELLED = 3U
} Spi_SeqResultType;

typedef enum
{
    SPI_HW_UNIT_OK = 0U,
    SPI_HW_UNIT_PENDING = 1U,
    SPI_HW_UNIT_FAILED = 2U
} Spi_HwUnitResultType;

/* Requirements : MCAL-1380, MCAL-1381, MCAL-1382, MCAL-1383,
 *                MCAL-1384, MCAL-1385, MCAL-1300 */
typedef enum
{
    SPI_POLLING_MODE = 0U,
    SPI_INTERRUPT_MODE = 1U
} Spi_AsyncModeType;

typedef enum
{
    SPI_MSB = 0U,
    SPI_LSB = 1U
} Spi_TransferType;

typedef enum
{
    SPI_LOW = STD_LOW,
    SPI_HIGH
} Spi_LevelType;

typedef enum
{
    SPI_CS0 = 0U,
    SPI_CS1,
    SPI_CS2,
    SPI_CS3
} Spi_CsPinType;

typedef enum
{
    SPI_CLK_MODE_0 = 0x00U,
    SPI_CLK_MODE_1 = 0x01U,
    SPI_CLK_MODE_2 = 0x02U,
    SPI_CLK_MODE_3 = 0x03U,
} Spi_ClkMode;

typedef enum
{
    SPI_TX_RX_MODE_BOTH = 0x00U,
    SPI_TX_RX_MODE_TX_ONLY = 0x02U,
} Spi_TxRxMode;

/* Requirements : MCAL-1277 */
typedef enum
{
    SPI_JOB_PRIORITY_0 = 0U,
    SPI_JOB_PRIORITY_1,
    SPI_JOB_PRIORITY_2,
    SPI_JOB_PRIORITY_3
} Spi_JobPriorityType;

typedef enum
{
    SPI_SINGLE = 0U,
    SPI_CONTINUOUS = 1U
} Spi_CsModeType;

typedef enum
{
    SPI_DATADELAY_0 = 0U,
    SPI_DATADELAY_1 = 1U,
    SPI_DATADELAY_2 = 2U,
    SPI_DATADELAY_3 = 3U,
} Spi_DataDelayType;

typedef enum
{
    DATA_LINE_0_RECEPTION = 0U,
    DATA_LINE_1_RECEPTION = 1U,
} Spi_DataLineReceiveType;

typedef enum
{
    DATA_LINE_NO_TRANSMISSION = 0x3U,
    DATA_LINE_0_TRANSMISSION = 0x2U,
    DATA_LINE_1_TRANSMISSION = 0x1U,
    DATA_LINE_BOTH_TRANSMISSION = 0x0U,
} Spi_DataLineTransmitType;

typedef void (*Spi_CacheWbInv)(uint8 *BufPtr,
                               uint16 LenByte);

typedef void (*Spi_CacheWb)(uint8 *BufPtr,
                            uint16 LenByte);

typedef void (*Spi_CacheInv)(uint8 *BufPtr,
                             uint16 LenByte);

/*
 * Requirements : MCAL-1256, MCAL-1257, MCAL-1264, MCAL-1265,
 *                MCAL-1336
 */
typedef struct
{
    uint8                 channelBufType;
    uint8                 dataWidth;
    uint32                defaultTxData;
    Spi_NumberOfDataType  maxBufLength;
    Spi_TransferType      transferType;
} Spi_ChannelConfigType;

typedef struct
{
    uint16            csEnable;
    Spi_CsModeType    csMode;
    Spi_LevelType     csPolarity;
    Spi_DataDelayType csIdleTime;
    uint32            clkDivider;
    Spi_ClkMode       clkMode;
    Spi_TxRxMode      txRxMode;
    uint16            startBitEnable;
    Spi_LevelType     startBitLevel;
    Spi_DataLineReceiveType     receptionLineEnable;
    Spi_DataLineTransmitType    transmissionLineEnable;
} Spi_McspiExternalDeviceConfigType;

typedef struct
{
    Spi_McspiExternalDeviceConfigType mcspi;
} Spi_ExternalDeviceConfigType;

/* Requirements : MCAL-1231, MCAL-1244
 *                MCAL-1248, MCAL-1249, MCAL-1276, MCAL-1337,
 *                MCAL-1339
 */
typedef struct
{
    Spi_JobPriorityType  jobPriority;
    Spi_HWUnitType       hwUnitId;
    Spi_JobEndNotifyType Spi_JobEndNotification;
    uint32               channelPerJob;
    Spi_ChannelType      channelList[SPI_MAX_CHANNELS_PER_JOB];
} Spi_JobConfigType;

/* Requirements : MCAL-1251, MCAL-1338, MCAL-1286  */
typedef struct
{
    uint8                seqInterruptible;
    Spi_SeqEndNotifyType Spi_SequenceEndNotification;
    uint32               jobPerSeq;
    Spi_JobType          jobList[SPI_MAX_JOBS_PER_SEQ];
} Spi_SeqConfigType;

typedef struct
{
    Spi_HWUnitType hwUnitId;
    boolean        enabledmaMode;
    uint32         dmaTxChIntrNum;
    uint32         dmaRxChIntrNum;
} Spi_HwUnitConfigType;

/*
 * Requirements : MCAL-1333, MCAL-1334, MCAL-1335, MCAL-1502,
 *                MCAL-1503
 */
typedef struct Spi_ConfigType_s
{
    uint8                        maxChannels;
    uint8                        maxJobs;
    uint8                        maxSeq;
    uint8                        maxHwUnit;
    uint8                        maxExtDevCfg;
    uint32 udmaInstId;
    Spi_CacheWbInv               cacheWbInv;
    Spi_CacheWb                  cacheWb;
    Spi_CacheInv                 cacheInv;
    Spi_ChannelConfigType        channelCfg[SPI_MAX_CHANNELS];
    Spi_JobConfigType            jobCfg[SPI_MAX_JOBS];
    Spi_SeqConfigType            seqCfg[SPI_MAX_SEQ];
    Spi_HwUnitConfigType         hwUnitCfg[SPI_MAX_HW_UNIT];
    Spi_ExternalDeviceConfigType extDevCfg[SPI_MAX_EXT_DEV];
} Spi_ConfigType;

typedef struct Spi_ChannelConfigType_PC_s
{
    Spi_ChannelType      channelId;
} Spi_ChannelConfigType_PC;

/* Requirements : MCAL-1245, MCAL-1246 */
typedef struct Spi_JobConfigType_PC_s
{
    Spi_JobType          jobId;
    Spi_CsPinType        csPin;
    uint8                externalDeviceCfgId;
} Spi_JobConfigType_PC;

typedef struct Spi_SeqConfigType_PC_s
{
    Spi_SequenceType     seqId;
} Spi_SeqConfigType_PC;

#if (STD_ON == SPI_REGISTER_READBACK_API)

typedef struct
{
    /*
     * McSPI related registers
     */
    uint32      mcspiHlRev;
    uint32      mcspiHlHwInfo;
    uint32      mcspiHlSysConfig;
    uint32      mcspiRev;
    uint32      mcspiSysStatus;
    uint32      mcspiSyst;
} Spi_RegisterReadbackType;
#endif  /* #if (STD_ON == SPI_REGISTER_READBACK_API) */

/* @} */
/* @} */
/* ========================================================================== */
/*                          Function Declarations                             */
/* ========================================================================== */

FUNC(void, SPI_CODE) Spi_Init(
    P2CONST(Spi_ConfigType, AUTOMATIC, SPI_CONFIG_DATA) CfgPtr);

FUNC(Std_ReturnType, SPI_CODE) Spi_DeInit(void);

FUNC(Spi_StatusType, SPI_CODE) Spi_GetStatus(void);

FUNC(Spi_JobResultType, SPI_CODE) Spi_GetJobResult(Spi_JobType Job);

FUNC(Spi_SeqResultType, SPI_CODE) Spi_GetSequenceResult(
    Spi_SequenceType Sequence);

#if (STD_ON == SPI_VERSION_INFO_API)

FUNC(void, SPI_CODE) Spi_GetVersionInfo(
    P2VAR(Std_VersionInfoType, AUTOMATIC, SPI_APPL_DATA) versioninfo);
#endif  /* #if (STD_ON == SPI_VERSION_INFO_API) */

#if (STD_ON == SPI_HW_STATUS_API)

FUNC(Spi_StatusType, SPI_CODE) Spi_GetHWUnitStatus(Spi_HWUnitType HWUnit);
#endif  /* #if (STD_ON == SPI_HW_STATUS_API) */

#if ((SPI_CHANNELBUFFERS == SPI_IB) || (SPI_CHANNELBUFFERS == SPI_IB_EB))

FUNC(Std_ReturnType, SPI_CODE) Spi_WriteIB(
    Spi_ChannelType Channel,
    P2CONST(Spi_DataBufferType, AUTOMATIC, SPI_APPL_DATA) DataBufferPtr);

FUNC(Std_ReturnType, SPI_CODE) Spi_ReadIB(
    Spi_ChannelType Channel,
    P2VAR(Spi_DataBufferType, AUTOMATIC, SPI_APPL_DATA) DataBufferPointer);
#endif  /* #if SPI_IB || SPI_IB_EB */

#if ((SPI_CHANNELBUFFERS == SPI_EB) || (SPI_CHANNELBUFFERS == SPI_IB_EB))

FUNC(Std_ReturnType, SPI_CODE) Spi_SetupEB(
    Spi_ChannelType Channel,
    P2CONST(Spi_DataBufferType, AUTOMATIC, SPI_APPL_DATA) SrcDataBufferPtr,
    P2VAR(Spi_DataBufferType, AUTOMATIC, SPI_APPL_DATA) DesDataBufferPtr,
    Spi_NumberOfDataType Length);
#endif  /* #if ((SPI_CHANNELBUFFERS == SPI_EB) || (SPI_CHANNELBUFFERS ==
         *SPI_IB_EB)) */

#if ((SPI_SCALEABILITY == SPI_LEVEL_1) || (SPI_SCALEABILITY == \
                                                   SPI_LEVEL_2))

FUNC(Std_ReturnType, SPI_CODE) Spi_AsyncTransmit(Spi_SequenceType Sequence);
#endif  /* #if ((SPI_SCALEABILITY == SPI_LEVEL_1) ||
         *(SPI_SCALEABILITY == SPI_LEVEL_2)) */

#if (STD_ON == SPI_CANCEL_API)

FUNC(void, SPI_CODE) Spi_Cancel(Spi_SequenceType Sequence);
#endif  /* #if (STD_ON == SPI_CANCEL_API) */

#if ((SPI_SCALEABILITY == SPI_LEVEL_0) || (SPI_SCALEABILITY == \
                                                   SPI_LEVEL_2))

FUNC(Std_ReturnType, SPI_CODE) Spi_SyncTransmit(Spi_SequenceType Sequence);
#endif  /* #if ((SPI_SCALEABILITY == SPI_LEVEL_0) ||
         *(SPI_SCALEABILITY == SPI_LEVEL_2)) */

#if (SPI_SCALEABILITY == SPI_LEVEL_2)

FUNC(Std_ReturnType, SPI_CODE) Spi_SetAsyncMode(Spi_AsyncModeType Mode);
#endif  /* #if (SPI_SCALEABILITY == SPI_LEVEL_2) */

FUNC(void, SPI_CODE) Spi_MainFunction_Handling(void);

#if (STD_ON == SPI_REGISTER_READBACK_API)

FUNC(Std_ReturnType, SPI_CODE) Spi_RegisterReadback(
    Spi_HWUnitType HWUnit,
    P2VAR(Spi_RegisterReadbackType, AUTOMATIC, SPI_APPL_DATA) RegRbPtr);
#endif  /* #if (STD_ON == SPI_REGISTER_READBACK_API) */

#ifdef __cplusplus
}
#endif

#endif  /* #ifndef SPI_H_ */

/* @} */