The Multi Channel Serial Peripheral Interface (MCSPI) driver is a generic, full-duplex driver that transmits and receives data on the SPI bus. The SPI protocol defines the format of a data transfer over the SPI bus, but it leaves flow control, data formatting, and handshaking mechanisms to higher-level software layers.
SysConfig can be used to configure below parameters apart from common configuration like Clock,MPU,RAT and others.
To use the MCSPI driver to send data over the SPI bus, the application calls the following APIs:
MCSPI_init() must be called before any other MCSPI APIs. This function iterates through the elements of the MCSPI_config[] array, calling the element's device implementation MCSPI initialization function. Please note that initializing MCSPI driver is taken care by the SysConfig generated code.
After initializing the MCSPI driver by calling MCSPI_init(), the application can open a MCSPI instance by calling MCSPI_open(). Please note that opening MCSPI driver is taken care by the SysConfig generated code. This function takes an index into the MCSPI_config[] array, and the MCSPI parameters data structure. The MCSPI instance is specified by the index of the SPI in MCSPI_config[]. Calling MCSPI_open() a second time with the same index previously passed to MCSPI_open() will result in an error. You can, though, re-use the index if the instance is closed via MCSPI_close(). In DMA mode, MCSPI_dmaChConfig() needs to be called after MCSPI_open() to acquire and initialize DMA channels. This is also taken care by the SysConfig generated code.
If no MCSPI_OpenParams structure is passed to MCSPI_open(), default values are used. If the open call is successful, it returns a non-NULL value.
The MCSPI driver supports three transfer modes of operation: Interrupt, Polling and DMA Mode. In Interrupt and DMA mode, it again supports two modes: blocking and callback. The transfer mode is determined by the MCSPI_OpenParams.transferMode parameter. The MCSPI driver defaults to blocking mode, if the application does not set it. 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 blocking mode, a task's code execution is blocked until a MCSPI transaction has completed or a timeout has occurred. This ensures that only one MCSPI transfer operates at a given time. Other tasks requesting MCSPI transfers while a transfer is currently taking place will receive a error return value. If a timeout occurs the transfer is canceled, the task is unblocked & will receive a error return value. The transaction count field will have the amount of frames which were transferred successfully before the timeout. In blocking mode, transfers cannot be performed in software or hardware ISR context.
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.
The MCSPI driver can configure the device's MCSPI peripheral to transfer data in several MCSPI format options: MCSPI (with various polarity and phase settings). The frame format is set with MCSPI_ChConfig.frameFormat.
The smallest single unit of data transmitted onto the MCSPI bus is called a MCSPI frame and is of size MCSPI_Transaction.dataSize. A series of MCSPI frames transmitted/received on a MCSPI bus is referred to as a MCSPI transaction.
A MCSPI transaction consists of a series of MCSPI frames transmitted/received on a MCSPI bus. A MCSPI transaction is performed using MCSPI_transfer(). MCSPI_transfer() accepts a pointer to a MCSPI_Transaction structure that dictates the quantity of data to be sent and received. The MCSPI_Transaction.txBuf and MCSPI_Transaction.rxBuf are both pointers to data buffers. If txBuf is NULL, the driver sends MCSPI frames with all data set to the default value specified in the hardware attributes. If rxBuf is NULL, the driver discards all MCSPI frames received. MCSPI_transfer() of a MCSPI transaction is performed atomically.
MCSPI_Transaction.dataSize determines the element types of txBuf and rxBuf. If the dataSize is from 4 to 8 bits, the driver assumes the data buffers are of type uint8_t (unsigned char). If the dataSize is from 9 to 16 bits, the driver assumes the data buffers are of type uint16_t (unsigned short). If the dataSize is greater than 16 bits, the driver assumes the data buffers are uint32_t (unsigned long).
MCSPI_Transaction.csDisable can be set to TRUE/FALSE to disable CS(chip select). If it is set to TRUE, CS is de-asseted automatically at the end of the transfer. If user wants to chain more transfers under one CS pulse, user needs to set it to FALSE for each transfer and for the last transfer, user needs to set to TRUE to de-assert CS. Generally this is useful when SPI needs to communicate with memory device where usually command/address is sent first and then the data will be sent.
The optional MCSPI_Transaction.args variable can only be used when the MCSPI driver has been opened in callback mode. This variable is used to pass a user-defined value into the user-defined callback function.
MCSPI_transfer() always performs full-duplex MCSPI transactions. This means the MCSPI simultaneously receives data as it transmits data. The application is responsible for formatting the data to be transmitted as well as determining whether the data received is meaningful. Specifics about MCSPI frame formatting and data sizes are provided in device-specific data sheets and technical reference manuals.
In case of MCSPI operating in MCSPI_MS_MODE_SLAVE mode if Rx overflow or Tx underflow occurs, driver cancels the current transfer and return status MCSPI_TRANSFER_CANCELLED to the application. Application need to check the status and reinitiate transfers again.
Include the below file to access the APIs
Instance Open Example
Instance Close Example
Blocking Transfer Example
Chain Transfer Example Blocking Mode
Non-Blocking Transfer Example