Spi.h

Go to the documentation of this file.

/*
*
* Copyright (c) 2024 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.
*
*/

/*
 * Below are the global design requirements which are met by this SPI handler
 * driver which can't be mapped to a particular source ID
 */
/*
 * Design: MCAL-6422,MCAL-6412,MCAL-6690,MCAL-6487,MCAL-6429,MCAL-6683,MCAL-6384,MCAL-6478,MCAL-6383,MCAL-6593,MCAL-6573,MCAL-6381,MCAL-6492,MCAL-6610,MCAL-6658,MCAL-6451,MCAL-6449,MCAL-6448,MCAL-6581,MCAL-6710,MCAL-6527,MCAL-6642,MCAL-6458,MCAL-6544
 */

/*
 * Below are the SPI's module environment design requirements which can't be mapped
 * to this driver.
 */
/*
 * Design: MCAL-6719,MCAL-6486,MCAL-6415,MCAL-6685,MCAL-6421,MCAL-6390,MCAL-6608,MCAL-6670,MCAL-6643
 */

#ifndef SPI_H_
#define SPI_H_

/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
#include "Std_Types.h"
#include "Spi_Cfg.h"
#if defined (SOC_J721E) || defined (SOC_J7200) || defined (SOC_J721S2) || defined (SOC_J784S4)
#include <ti/drv/udma/udma.h>
#endif
#include "Spi/mcspi_hw/V0/mcspi.h"

#ifdef __cplusplus
extern "C"
{
#endif

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

#define SPI_SW_MAJOR_VERSION            (9U)

#define SPI_SW_MINOR_VERSION            (0U)

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

#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_IB                          (0U)

#define SPI_EB                          (1U)

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


/*
 * Design: MCAL-6691,MCAL-6394,MCAL-6615
 */
typedef uint8 Spi_DataBufferType;
/*
 * Design: MCAL-6625,MCAL-6669
 */
typedef uint16 Spi_NumberOfDataType;
/*
 * Design: MCAL-6528,MCAL-6493,MCAL-6687
 */
typedef uint8 Spi_ChannelType;
/*
 * Design: MCAL-6457,MCAL-6689,MCAL-6728
 */
typedef uint16 Spi_JobType;
/*
 * Design: MCAL-6639,MCAL-6505,MCAL-6729
 */
typedef uint8 Spi_SequenceType;
/*
 * Design: MCAL-6655,MCAL-6682,MCAL-6707
 */
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)
/* @} */

/*
 * Design: MCAL-6699
 */
#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)

#define  SPI_CFG_ID_6     (0x40U)

#define  SPI_CFG_ID_7     (0x80U)
/* @} */

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

/*
 * Design: MCAL-6531,MCAL-6648,MCAL-6537,MCAL-6574
 */
typedef enum
{
    SPI_UNINIT = 0U,
    SPI_IDLE = 1U,
    SPI_BUSY = 2U
} Spi_StatusType;

/*
 * Design: MCAL-6703,MCAL-6425,MCAL-6430
 */
typedef enum
{
    SPI_JOB_OK = 0U,
    SPI_JOB_PENDING = 1U,
    SPI_JOB_FAILED = 2U,
    SPI_JOB_QUEUED = 3U
} Spi_JobResultType;

/*
 * Design: MCAL-6512,MCAL-6607,MCAL-6686
 */
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;

/*
 * Design: MCAL-6502,MCAL-6659,MCAL-6420,MCAL-6475,MCAL-6419,MCAL-6517,MCAL-6641
 */
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;

/*
 * Design: MCAL-6597
 */
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 enum
{
    SPI_NO_EVENT = 0U,
    SPI_EVENT_PENDING = 1U,
    SPI_STATUS_READ_FAIL = 2U,
} Mcspi_IrqStatusType;

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

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

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

/*
 * Design: MCAL-6529,MCAL-6519,MCAL-6649,MCAL-6716,MCAL-6619
 */
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;

/*
 * Design: MCAL-6692,MCAL-6437,MCAL-6684,MCAL-6522,MCAL-6572,MCAL-6406,MCAL-6632,MCAL-6476
 */
typedef struct
{
    Spi_JobPriorityType  jobPriority;
    Spi_HWUnitType       hwUnitId;
    Spi_JobEndNotifyType Spi_JobEndNotification;
    uint32               channelPerJob;
    Spi_ChannelType      channelList[SPI_MAX_CHANNELS_PER_JOB];
} Spi_JobConfigType;

/*
 * Design: MCAL-6496,MCAL-6536,MCAL-6742,MCAL-6413
 */
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;

/*
 * Design: MCAL-6570,MCAL-6423,MCAL-6588,MCAL-6485,MCAL-6733
 */
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;

/*
 * Design: MCAL-6717,MCAL-6650
 */
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;
    uint32       mcspiModulctrl;
    uint32       mcspiSysConfig;
    uint32       mcspiCh0config;
    uint32       mcspiCh1config;
    uint32       mcspiCh2config;
    uint32       mcspiCh3config;
    uint32       mcspiIrqenable;
} 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) */

#if (STD_ON == SPI_SAFETY_API)

FUNC(Std_ReturnType, SPI_CODE) Spi_dataOverflowUnderflowIntrEnable(
    Spi_HWUnitType HWUnit, uint32 intFlags );

FUNC(Std_ReturnType, SPI_CODE)  Spi_dataOverflowUnderflowIntrDisable(
    Spi_HWUnitType HWUnit, uint32 intFlags);

FUNC(Mcspi_IrqStatusType, SPI_CODE) Spi_dataOverflowUnderflowIntrGetStatus(
    Spi_HWUnitType HWUnit, uint32 intFlags);

FUNC(Std_ReturnType, SPI_CODE)  Spi_dataOverflowUnderflowIntrStatusClear(
    Spi_HWUnitType HWUnit, uint32 intFlags);

#endif /* #if (STD_ON == SPI_SAFETY_API) */

#ifdef __cplusplus
}
#endif

#endif  /* #ifndef SPI_H_ */

/* @} */