Features Supported

Controller and Peripheral mode of operation
Per transfer selection of different channels/chip select
Non-blocking (Callback) transfers

Features NOT Supported

Default TX data feature is not supported in DMA mode.
In DMA mode, FIFO is not enabled.

Usage Overview

API Sequence

To use the MCSPI driver to send data over the SPI bus, the application calls the following APIs:

MCSPI_lld_init(): Initialize the MCSPI driver.
MCSPI_lld_readWrite() / MCSPI_lld_readWriteIntr() / MCSPI_lld_readWriteDma(): Read and Write data in polling, interrupt, and Dma mode respectively.
MCSPI_lld_read() / MCSPI_lld_readIntr() / MCSPI_lld_readDma(): Read data in polling, interrupt, and Dma mode respectively.
MCSPI_lld_write() / MCSPI_lld_writeIntr() / MCSPI_lld_writeDma(): Write data in polling, interrupt, and Dma mode respectively.
MCSPI_lld_deInit(): De-initialize the MCSPI instance.

Initializing the MCSPI Driver

MCSPI_lld_init() must be called before any other MCSPI APIs. This function iterates till the channel count. This function uses mcspi handle to initialize each instance. Calling MCSPI_lld_init() a second time with the same handle previously passed to MCSPI_lld_init() will result in an error. You can, though, re-use the handle if the instance is closed via MCSPI_lld_deInit(). In DMA mode, MCSPI_lld_initDma() needs to be called instead of MCSPI_lld_init() to acquire and initialize mcspi instance. Please note that initializing MCSPI driver is taken care by the SysConfig generated code.

MCSPI Transfer Mode

The MCSPI driver supports three transfer modes of operation: Interrupt, Polling and DMA Mode. Interrupt and DMA mode, it supports only callback mode. Once a MCSPI driver is opened, the only way to change the operation mode is to close and re-open the MCSPI instance with the new transfer mode.

In callback mode, a MCSPI transaction functions asynchronously, which means that it does not block code execution. After a MCSPI transaction has been completed, the MCSPI driver calls a user-provided hook function. Callback mode is supported in the execution context of tasks and hardware interrupt routines.

In multichannel mode connected to multiple external devices, the MCSPI exchanges data with one MCSPI device at a time and FIFO is enabled per each channel at a time.

Important Usage Guidelines

The MCSPI protocol does not account for a built-in handshaking mechanism and neither does this driver. Therefore, when operating in MCSPI_MS_MODE_PERIPHERAL mode, the application must provide such a mechanism to ensure that the MCSPI peripheral is ready for the MCSPI controller. The MCSPI peripheral must call MCSPI_lld_readWrite() / MCSPI_lld_readWriteIntr() / MCSPI_lld_readWriteDma() before the controller starts transmitting. Some example application mechanisms could include:
- Timed delays on the MCSPI controller to guarantee the MCSPI peripheral is ready for a MCSPI transaction.
- A form of GPIO flow control from the peripheral to the MCSPI controller to notify the controller when ready.
In case of DMA mode, as R5F core is not Cache Coherent, Cache Writeback is required if R5F writes to the buffers. And before reading the buffers, application needs to invalidate those. Please refer MCSPI Loopback DMA LLD.

Example Usage

Include the below file to access the APIs

#include <kernel/dpl/DebugP.h>
#include <kernel/dpl/SystemP.h>
#include <kernel/dpl/SemaphoreP.h>
#include <kernel/dpl/HwiP.h>
#include <kernel/dpl/MutexArmP.h>
#include <kernel/nortos/dpl/r5/HwiP_armv7r_vim.h>
#include <drivers/mcspi/v0/lld/mcspi_lld.h>

Instance Open Example

    int32_t status = MCSPI_STATUS_SUCCESS;
    gMcspiHandle0 = &gMcspiObject[CONFIG_MCSPI0];
 
    status = MCSPI_lld_init(gMcspiHandle0);
    DebugP_assert(status == MCSPI_STATUS_SUCCESS);
 

Instance Close Example

    int32_t status = MCSPI_STATUS_SUCCESS;
 
    status = MCSPI_lld_deInit(gMcspiHandle0);
    DebugP_assert(status == MCSPI_STATUS_SUCCESS);

Non-Blocking Transfer Example

    uint32_t              bufIndex;
    uint32_t              count;
    uint32_t              timeout = MCSPI_WAIT_FOREVER;
    int32_t               status = MCSPI_STATUS_SUCCESS;
    MCSPI_ExtendedParams  extendedParams;
 
    /*  Interrupt configuration and registration*/
    intrNum = gConfigMcspi0InitObject[CONFIG_MCSPI0].intrNum;
    gMcspiVimStsAddr = gVimBaseAddr + (0x404u + (((intrNum)>> 5) & 0xFu) * 0x20u);
    gMcspiVimStsClrMask = 0x1u << ((intrNum) & 0x1Fu);
 
    HwiP_setVecAddr(intrNum, (uintptr_t)&App_MCSPI_ISR);
    HwiP_setPri(intrNum, gConfigMcspi0InitObject[CONFIG_MCSPI0].intrPriority);
    HwiP_enableInt(intrNum);
 
    if(status == MCSPI_STATUS_SUCCESS)
    {
        DebugP_log("\n[MCSPI] Loopback example started ...\r\n");
 
        /* Memfill buffers */
        for(bufIndex = 0U; bufIndex < APP_MCSPI_MSGSIZE; bufIndex++)
        {
            gMcspiTxBuffer[bufIndex] = bufIndex;
            gMcspiRxBuffer[bufIndex] = 0U;
        }
 
        gMcspiObject[CONFIG_MCSPI0].transferMutex = &gMutexLockUnlock;
 
        /* populate extended parameters */
        extendedParams.channel    = 0;
        extendedParams.csDisable  = TRUE;
        extendedParams.dataSize   = 32;
        count = APP_MCSPI_MSGSIZE / (extendedParams.dataSize/8);
 
        status = MCSPI_lld_readWriteIntr(gMcspiHandle0, \
                                         gMcspiTxBuffer, \
                                         &gMcspiRxBuffer, \
                                         count, \
                                         timeout, \
                                         &extendedParams);
        while(try_lock_mutex(gMcspiObject[CONFIG_MCSPI0].transferMutex) == MUTEX_ARM_LOCKED);
 
        if(MCSPI_TRANSFER_COMPLETED != status)
        {
            DebugP_assert(FALSE); /* MCSPI transfer failed!! */
        }
        else
        {
            /* Compare data */
            for(bufIndex = 0U; bufIndex < APP_MCSPI_MSGSIZE; bufIndex++)
            {
                if(gMcspiTxBuffer[bufIndex] != gMcspiRxBuffer[bufIndex])
                {
                    status = MCSPI_STATUS_FAILURE;   /* Data mismatch */
                    DebugP_log("Data Mismatch at offset %d\r\n", bufIndex);
                    break;
                }
            }
        }
    }
 
    /* Deregister IRQ */
    HwiP_setVecAddr(intrNum, 0);
    HwiP_setPri(intrNum, 15);
 
    if(MCSPI_STATUS_SUCCESS == status)
    {
        DebugP_log("All tests have passed!!\r\n");
    }
    else
    {
        DebugP_log("Some tests have failed!!\r\n");
    }
 

Non-Blocking Example transfer callback

void MCSPI_lld_transferCallback(void *args, uint32_t transferStatus)
{
    unlock_mutex(gMcspiObject[CONFIG_MCSPI0].transferMutex);
}

Non-Blocking Example ISR CALL callback

static __attribute__((__section__(".text.hwi"), noinline, naked, target("arm"), aligned(4))) void App_MCSPI_ISR(void)
{
    ISR_CALL_LEVEL_NONFLOAT_REENTRANT(MCSPI_lld_controllerIsr, \
                                      gMcspiHandle0, \
                                      intrNum, \
                                      gMcspiVimStsAddr, \
                                      gMcspiVimStsClrMask,
                                      gVimBaseAddr);
}

API

APIs for MCSPI LLD