Serial Peripheral Interface - Peripheral Abstraction Layer(SPI PAL)

Detailed Description

Serial Peripheral Interface - Peripheral Abstraction Layer.

The SPI PAL driver allows communication on an SPI bus. It was designed to be portable across all platforms and IPs which support SPI communication.

How to integrate DSPI in your application

Unlike the other drivers, SPI PAL modules need to include a configuration file named spi_pal_cfg.h, which allows the user to specify which IPSs are used and how many resources are allocated for each of them (state structures). The following code example shows how to configure one instance for each available SPI IPs.

#ifndef SPI_PAL_cfg_H
#define SPI_PAL_cfg_H
/* Define which IP instance will be used in current project */
#define SPI_OVER_LPSPI
#define SPI_OVER_FLEXIO
#define SPI_OVER_DSPI
/* Define the resources necessary for current project */
#define NO_OF_LPSPI_INSTS_FOR_SPI 1U
#define NO_OF_FLEXIO_INSTS_FOR_SPI 1U
#define NO_OF_DSPI_INSTS_FOR_SPI 1U
#endif /* SPI_PAL_cfg_H */

The following table contains the matching between platforms and available IPs

IP/MCUS32K118S32K116S32K142S32K144S32K148MPC5748GMPC5746CMPC5744P
FLEXIO YES YES YES YES YES NO NO NO
LPSPI YES YES YES YES YES NO NO NO
DSPI/SPI NO NO NO NO NO YES YES YES

In order to use the SPI driver it must be first initialized in either master or slave mode, using functions SPI_MasterInit() or SPI_SlaveInit(). Once initialized, it cannot be initialized again for the same SPI module instance until it is de-initialized, using SPI_SlaveDeinit() or SPI_MasterDeinit. Different SPI module instances can work independently of each other.

In each mode (master/slave) are available two types of transfers: blocking and non-blocking. The functions which initiate blocking transfers will configure the time out for transmission. If time expires SPI_MasterTransferBlocking() or SPI_SlaveTransferBlocking() will return error and the transmission will be aborted.

The configuration structure includes a special field named extension. It will be used only for SPI transfers over FLEXIO and should contain a pointer to extension_flexio_for_spi_t structure. The purpose of this structure is to configure which FLEXIO pins are used by the applications and their functionality (MISO, MOSI, SCK, SS). One FLEXIO hardware instance can implements spi, so if instType is SPI_INST_TYPE_FLEXIO instIdx can be 0 or 1.

If device name is from MPC574xP family it can't be used as master in DMA mode and PAL will automatically switch the functionality to interrupt mode.

Important Notes

Example code

/* Configure SPI master */
spi_master_t spi10_MasterConfig0 =
{
.baudRate = 100000,
.ssPolarity = SPI_ACTIVE_HIGH,
.frameSize = 8,
.clockPhase = READ_ON_ODD_EDGE,
.clockPolarity = SPI_ACTIVE_HIGH,
.transferType = SPI_USING_INTERRUPTS,
.rxDMAChannel = 255,
.txDMAChannel = 255,
.callback = NULL,
.callbackParam = NULL,
.ssPin = 0,
.extension = NULL
};
/* Configure FLEXIO pins routing */
extension_flexio_for_spi_t extension;
extension.misoPin = 0;
extension.mosiPin = 1;
extension.sckPin = 2;
extension.ssPin = 3;
spi0_MasterConfig0.extension = &extension;
/* Configure instances used in this example */
spi_instance_t lpspiInstance, flexioInstance;
lpspiInstance.instIdx = 0U;
lpspiInstance.instType = SPI_INST_TYPE_LPSPI;
flexioInstance.instIdx = 1U;
lpspiInstance.instType = SPI_INST_TYPE_FLEXIO;
/* Buffers */
uint8_t tx[5] = {1,2,3,4,5};
uint8_t rx[5];
/* Initializes SPI master for LPSPI 0 and send 5 frames */
SPI_MasterInit(&lpspiInstance, &spi0_MasterConfig0);
SPI_MasterTransfer(&lpspiInstance, tx, rx, 5);
/* Initializes SPI master for FLEXIO 0 and send 5 frames */
SPI_MasterInit(&flexioInstance, &spi1_MasterConfig0);
SPI_MasterTransfer(&flexioInstance, tx, rx, 5);

Data Structures

struct  spi_master_t
 Defines the configuration structure for SPI master Implements : spi_master_t_Class. More...
 
struct  spi_slave_t
 Defines the configuration structure for SPI slave Implements: spi_slave_t_Class. More...
 

Enumerations

enum  spi_transfer_type_t { SPI_USING_DMA = 0U, SPI_USING_INTERRUPTS = 1U }
 Defines the mechanism to update the rx or tx buffers Implements : spi_transfer_type_t_Class. More...
 
enum  spi_polarity_t { SPI_ACTIVE_HIGH = 0U, SPI_ACTIVE_LOW = 1U }
 Defines the polarity of signals Implements : spi_polarity_t_Class. More...
 
enum  spi_clock_phase_t { READ_ON_ODD_EDGE = 0U, READ_ON_EVEN_EDGE = 1U }
 Defines the edges used for sampling and shifting Implements : spi_clock_phase_t_Class. More...
 
enum  spi_transfer_bit_order_t { SPI_TRANSFER_MSB_FIRST = 0U, SPI_TRANSFER_LSB_FIRST = 1U }
 Defines the bit order Implements : spi_transfer_bit_order_t_Class. More...
 

Functions

status_t SPI_MasterInit (const spi_instance_t *const instance, const spi_master_t *config)
 Initializes the SPI module in master mode. More...
 
status_t SPI_SlaveInit (const spi_instance_t *const instance, const spi_slave_t *config)
 Initializes the SPI module in slave mode. More...
 
status_t SPI_SetSS (const spi_instance_t *const instance, uint8_t ss)
 Update the SS. More...
 
status_t SPI_MasterTransfer (const spi_instance_t *const instance, const void *txBuffer, void *rxBuffer, uint16_t numberOfFrames)
 Initializes a non-blocking master transfer. More...
 
status_t SPI_MasterTransferBlocking (const spi_instance_t *const instance, const void *txBuffer, void *rxBuffer, uint16_t numberOfFrames, uint16_t timeout)
 Initializes a blocking master transfer. More...
 
status_t SPI_SlaveTransfer (const spi_instance_t *const instance, const void *txBuffer, void *rxBuffer, uint16_t numberOfFrames)
 Initializes a non-blocking slave transfer. More...
 
status_t SPI_SlaveTransferBlocking (const spi_instance_t *const instance, const void *txBuffer, void *rxBuffer, uint16_t numberOfFrames, uint16_t timeout)
 Initializes a blocking slave transfer. More...
 
status_t SPI_GetStatus (const spi_instance_t *const instance)
 Gets the status of the last transfer. More...
 
status_t SPI_GetDefaultMasterConfig (spi_master_t *config)
 Gets the default configuration structure for master. More...
 
status_t SPI_GetDefaultSlaveConfig (spi_slave_t *config)
 Gets the default configuration structure for slave. More...
 
status_t SPI_MasterDeinit (const spi_instance_t *const instance)
 De-initializes the spi master module. More...
 
status_t SPI_SlaveDeinit (const spi_instance_t *const instance)
 De-initializes the spi slave module. More...
 
status_t SPI_MasterSetDelay (const spi_instance_t *const instance, uint32_t delayBetweenTransfers, uint32_t delaySCKtoPCS, uint32_t delayPCStoSCK)
 Configures the SPI_PAL master mode bus timing delay options. More...
 

Enumeration Type Documentation

Defines the edges used for sampling and shifting Implements : spi_clock_phase_t_Class.

Enumerator
READ_ON_ODD_EDGE 

The SPI signal is read on odd edges of SCK and counting starts after SS activation

READ_ON_EVEN_EDGE 

The SPI signal is read on even edges of SCK and counting starts after SS activation

Definition at line 63 of file spi_pal.h.

Defines the polarity of signals Implements : spi_polarity_t_Class.

Enumerator
SPI_ACTIVE_HIGH 

The signal is active high

SPI_ACTIVE_LOW 

The signal is active low

Definition at line 53 of file spi_pal.h.

Defines the bit order Implements : spi_transfer_bit_order_t_Class.

Enumerator
SPI_TRANSFER_MSB_FIRST 

Transmit data starting with most significant bit

SPI_TRANSFER_LSB_FIRST 

Transmit data starting with least significant bit

Definition at line 73 of file spi_pal.h.

Defines the mechanism to update the rx or tx buffers Implements : spi_transfer_type_t_Class.

Enumerator
SPI_USING_DMA 

The driver will use DMA to perform SPI transfer

SPI_USING_INTERRUPTS 

The driver will use interrupts to perform SPI transfer

Definition at line 43 of file spi_pal.h.

Function Documentation

status_t SPI_GetDefaultMasterConfig ( spi_master_t config)

Gets the default configuration structure for master.

The default configuration structure is:

Parameters
[out]configPointer to configuration structure
Returns
Error or success status returned by API

Definition at line 613 of file spi_pal.c.

status_t SPI_GetDefaultSlaveConfig ( spi_slave_t config)

Gets the default configuration structure for slave.

The default configuration structure is:

Parameters
[out]configPointer to configuration structure
Returns
Error or success status returned by API

Definition at line 638 of file spi_pal.c.

status_t SPI_GetStatus ( const spi_instance_t *const  instance)

Gets the status of the last transfer.

This function return the status of the last transfer. Using this function the user can check if the transfer is still in progress or if time-out event occurred.

Parameters
[in]instanceThe name of the instance
[in]txBufferPointer to tx buffer.
[in]rxBufferPointer to rx buffer.
[in]numberOfFramesNumber of frames sent/received
[in]timeoutTransfer time-out in ms
Returns
Error or success status returned by API

Definition at line 819 of file spi_pal.c.

status_t SPI_MasterDeinit ( const spi_instance_t *const  instance)

De-initializes the spi master module.

This function de-initialized the spi master module.

Parameters
[in]instanceThe name of the instance
Returns
Error or success status returned by API

Definition at line 661 of file spi_pal.c.

status_t SPI_MasterInit ( const spi_instance_t *const  instance,
const spi_master_t config 
)

Initializes the SPI module in master mode.

This function initializes and enables the requested SPI module in master mode, configuring the bus parameters.

Parameters
[in]instanceThe name of the instance
[in]configThe configuration structure
Returns
Error or success status returned by API

Definition at line 205 of file spi_pal.c.

status_t SPI_MasterSetDelay ( const spi_instance_t *const  instance,
uint32_t  delayBetweenTransfers,
uint32_t  delaySCKtoPCS,
uint32_t  delayPCStoSCK 
)

Configures the SPI_PAL master mode bus timing delay options.

This function involves the DSPI module's delay options to "fine tune" some of the signal timings and match the timing needs of a slower peripheral device. This is an optional function that can be called after the SPI_PAL module has been initialized for master mode. The timings are adjusted in terms of microseconds. The bus timing delays that can be adjusted are listed below:

SCK to PCS Delay: Adjustable delay option between the last edge of SCK to the de-assertion of the PCS signal.

PCS to SCK Delay: Adjustable delay option between the assertion of the PCS signal to the first SCK edge.

Delay between Transfers: Adjustable delay option between the de-assertion of the PCS signal for a frame to the assertion of the PCS signal for the next frame.

Definition at line 887 of file spi_pal.c.

status_t SPI_MasterTransfer ( const spi_instance_t *const  instance,
const void *  txBuffer,
void *  rxBuffer,
uint16_t  numberOfFrames 
)

Initializes a non-blocking master transfer.

This function initializes a non-blocking master transfer.

Parameters
[in]instanceThe name of the instance
[in]txBufferPointer to tx buffer.
[in]rxBufferPointer to rx buffer.
[in]numberOfFramesNumber of frames sent/received
Returns
Error or success status returned by API

Definition at line 327 of file spi_pal.c.

status_t SPI_MasterTransferBlocking ( const spi_instance_t *const  instance,
const void *  txBuffer,
void *  rxBuffer,
uint16_t  numberOfFrames,
uint16_t  timeout 
)

Initializes a blocking master transfer.

This function initializes a blocking master transfer.

Parameters
[in]instanceThe name of the instance
[in]txBufferPointer to tx buffer.
[in]rxBufferPointer to rx buffer.
[in]numberOfFramesNumber of frames sent/received
[in]timeoutTransfer time-out in ms
Returns
Error or success status returned by API

Definition at line 372 of file spi_pal.c.

status_t SPI_SetSS ( const spi_instance_t *const  instance,
uint8_t  ss 
)

Update the SS.

This function changes the SS, if this feature is available.

Parameters
[in]instanceThe name of the instance
[in]ssThe number of SS
Returns
Error or success status returned by API

Definition at line 773 of file spi_pal.c.

status_t SPI_SlaveDeinit ( const spi_instance_t *const  instance)

De-initializes the spi slave module.

This function de-initialized the spi slave module.

Parameters
[in]instanceThe name of the instance
Returns
Error or success status returned by API

Definition at line 717 of file spi_pal.c.

status_t SPI_SlaveInit ( const spi_instance_t *const  instance,
const spi_slave_t config 
)

Initializes the SPI module in slave mode.

This function initializes and enables the requested SPI module in slave mode, configuring the bus parameters.

Parameters
[in]instanceThe name of the instance
[in]configThe configuration structure
Returns
Error or success status returned by API

Definition at line 417 of file spi_pal.c.

status_t SPI_SlaveTransfer ( const spi_instance_t *const  instance,
const void *  txBuffer,
void *  rxBuffer,
uint16_t  numberOfFrames 
)

Initializes a non-blocking slave transfer.

This function initializes a non-blocking slave transfer.

Parameters
[in]instanceThe name of the instance
[in]txBufferPointer to tx buffer.
[in]rxBufferPointer to rx buffer.
[in]numberOfFramesNumber of frames sent/received
Returns
Error or success status returned by API

Definition at line 526 of file spi_pal.c.

status_t SPI_SlaveTransferBlocking ( const spi_instance_t *const  instance,
const void *  txBuffer,
void *  rxBuffer,
uint16_t  numberOfFrames,
uint16_t  timeout 
)

Initializes a blocking slave transfer.

This function initializes a blocking slave transfer.

Parameters
[in]instanceThe name of the instance
[in]txBufferPointer to tx buffer.
[in]rxBufferPointer to rx buffer.
[in]numberOfFramesNumber of frames sent/received
[in]timeoutTransfer time-out in ms
Returns
Error or success status returned by API

Definition at line 570 of file spi_pal.c.