Overview

SPI driver includes functional APIs and transactional APIs.

Functional APIs are feature/property target low level APIs. Functional APIs can be used for SPI initialization/configuration/operation for optimization/customization purpose. Using the functional API requires the knowledge of the SPI peripheral and how to organize functional APIs to meet the application requirements. All functional API use the peripheral base address as the first parameter. SPI functional operation groups provide the functional API set.

Transactional APIs are transaction target high level APIs. Transactional APIs can be used to enable the peripheral and in the application if the code size and performance of transactional APIs satisfy the requirements. If the code size and performance are a critical requirement, see the transactional API implementation and write a custom code. All transactional APIs use the spi_handle_t as the first parameter. Initialize the handle by calling the SPI_MasterTransferCreateHandle() or SPI_SlaveTransferCreateHandle() API.

Transactional APIs support asynchronous transfer. This means that the functions SPI_MasterTransferNonBlocking() and SPI_SlaveTransferNonBlocking() set up the interrupt for data transfer. When the transfer completes, the upper layer is notified through a callback function with the kStatus_SPI_Idle status.

Files
file	fsl_spi.h

Data Structures
struct	spi_delay_config_t
	SPI delay time configure structure. More...

struct	spi_master_config_t
	SPI master user configure structure. More...

struct	spi_transfer_t
	SPI transfer structure. More...

struct	spi_config_t
	Internal configuration structure used in 'spi' and 'spi_dma' driver. More...

struct	spi_master_handle_t
	SPI transfer handle structure. More...

Macros
#define	SPI_DUMMYDATA (0xFFU)
	SPI dummy transfer data, the data is sent while txBuff is NULL. More...

#define	SPI_RETRY_TIMES 0U /* Define to zero means keep waiting until the flag is assert/deassert. */
	Retry times for waiting flag. More...

Typedefs
typedef void(*	spi_master_callback_t )(SPI_Type base, spi_master_handle_t handle, status_t status, void *userData)
	SPI master callback for finished transmit.

typedef void(*	spi_master_irq_handler_t )(SPI_Type base, spi_master_handle_t handle)
	Typedef for master interrupt handler. More...

Enumerations
enum	spi_xfer_option_t { kSPI_FrameDelay = (SPI_FIFOWR_EOF_MASK), kSPI_FrameAssert = (SPI_FIFOWR_EOT_MASK) }
	SPI transfer option. More...

enum	spi_shift_direction_t { kSPI_MsbFirst = 0U, kSPI_LsbFirst = 1U }
	SPI data shifter direction options. More...

enum	spi_clock_polarity_t { kSPI_ClockPolarityActiveHigh = 0x0U, kSPI_ClockPolarityActiveLow }
	SPI clock polarity configuration. More...

enum	spi_clock_phase_t { kSPI_ClockPhaseFirstEdge = 0x0U, kSPI_ClockPhaseSecondEdge }
	SPI clock phase configuration. More...

enum	spi_txfifo_watermark_t { kSPI_TxFifo0 = 0, kSPI_TxFifo1 = 1, kSPI_TxFifo2 = 2, kSPI_TxFifo3 = 3, kSPI_TxFifo4 = 4, kSPI_TxFifo5 = 5, kSPI_TxFifo6 = 6, kSPI_TxFifo7 = 7 }
	txFIFO watermark values More...

enum	spi_rxfifo_watermark_t { kSPI_RxFifo1 = 0, kSPI_RxFifo2 = 1, kSPI_RxFifo3 = 2, kSPI_RxFifo4 = 3, kSPI_RxFifo5 = 4, kSPI_RxFifo6 = 5, kSPI_RxFifo7 = 6, kSPI_RxFifo8 = 7 }
	rxFIFO watermark values More...

enum	spi_data_width_t { kSPI_Data8Bits = 7, kSPI_Data16Bits = 15 }
	Transfer data width. More...

enum	spi_ssel_t { kSPI_Ssel0 = 0 }
	Slave select. More...

enum	spi_spol_t
	ssel polarity

enum	{ kStatus_SPI_Busy = MAKE_STATUS(kStatusGroup_LPC_SPI, 0), kStatus_SPI_Idle = MAKE_STATUS(kStatusGroup_LPC_SPI, 1), kStatus_SPI_Error = MAKE_STATUS(kStatusGroup_LPC_SPI, 2), kStatus_SPI_BaudrateNotSupport, kStatus_SPI_Timeout = MAKE_STATUS(kStatusGroup_LPC_SPI, 4) }
	SPI transfer status. More...

enum	_spi_interrupt_enable { kSPI_RxErrIrq = SPI_FIFOINTENSET_RXERR_MASK, kSPI_TxErrIrq = SPI_FIFOINTENSET_TXERR_MASK, kSPI_RxLvlIrq = SPI_FIFOINTENSET_RXLVL_MASK, kSPI_TxLvlIrq = SPI_FIFOINTENSET_TXLVL_MASK, kSPI_SlaveSelectAssertIrq = SPI_INTENSET_SSAEN_MASK << SPI_INTEN_IRQ_SHIFT, kSPI_SlaveSelectDeassertIrq = SPI_INTENSET_SSDEN_MASK << SPI_INTEN_IRQ_SHIFT, kSPI_MasterIdleIrq = SPI_INTENSET_MSTIDLEEN_MASK << SPI_INTEN_IRQ_SHIFT }
	SPI interrupt sources. More...

enum	_spi_statusflags { kSPI_TxEmptyFlag = SPI_FIFOSTAT_TXEMPTY_MASK, kSPI_TxNotFullFlag = SPI_FIFOSTAT_TXNOFULL_MASK, kSPI_RxNotEmptyFlag = SPI_FIFOSTAT_RXNOTEMPTY_MASK, kSPI_RxFullFlag = SPI_FIFOSTAT_RXFULL_MASK }
	SPI status flags. More...

Functions
uint32_t	SPI_GetInstance (SPI_Type *base)
	Returns instance number for SPI peripheral base address. More...

Variables
volatile uint8_t	s_dummyData []
	Global variable for dummy data value setting. More...

Driver version
#define	FSL_SPI_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))
	SPI driver version. More...

Initialization and deinitialization
void	SPI_MasterGetDefaultConfig (spi_master_config_t *config)
	Sets the SPI master configuration structure to default values. More...

status_t	SPI_MasterInit (SPI_Type base, const spi_master_config_t config, uint32_t srcClock_Hz)
	Initializes the SPI with master configuration. More...

void	SPI_Deinit (SPI_Type *base)
	De-initializes the SPI. More...

static void	SPI_Enable (SPI_Type *base, bool enable)
	Enable or disable the SPI Master or Slave. More...

Status
static uint32_t	SPI_GetStatusFlags (SPI_Type *base)
	Gets the status flag. More...

Interrupts
static void	SPI_EnableInterrupts (SPI_Type *base, uint32_t irqs)
	Enables the interrupt for the SPI. More...

static void	SPI_DisableInterrupts (SPI_Type *base, uint32_t irqs)
	Disables the interrupt for the SPI. More...

DMA Control
void	SPI_EnableTxDMA (SPI_Type *base, bool enable)
	Enables the DMA request from SPI txFIFO. More...

void	SPI_EnableRxDMA (SPI_Type *base, bool enable)
	Enables the DMA request from SPI rxFIFO. More...

Bus Operations
void *	SPI_GetConfig (SPI_Type *base)
	Returns the configurations. More...

status_t	SPI_MasterSetBaud (SPI_Type *base, uint32_t baudrate_Bps, uint32_t srcClock_Hz)
	Sets the baud rate for SPI transfer. More...

void	SPI_WriteData (SPI_Type *base, uint16_t data, uint32_t configFlags)
	Writes a data into the SPI data register. More...

static uint32_t	SPI_ReadData (SPI_Type *base)
	Gets a data from the SPI data register. More...

static void	SPI_SetTransferDelay (SPI_Type base, const spi_delay_config_t config)
	Set delay time for transfer. More...

void	SPI_SetDummyData (SPI_Type *base, uint8_t dummyData)
	Set up the dummy data. More...

Transactional
status_t	SPI_MasterTransferCreateHandle (SPI_Type base, spi_master_handle_t handle, spi_master_callback_t callback, void *userData)
	Initializes the SPI master handle. More...

status_t	SPI_MasterTransferBlocking (SPI_Type base, spi_transfer_t xfer)
	Transfers a block of data using a polling method. More...

status_t	SPI_MasterTransferNonBlocking (SPI_Type base, spi_master_handle_t handle, spi_transfer_t *xfer)
	Performs a non-blocking SPI interrupt transfer. More...

status_t	SPI_MasterTransferGetCount (SPI_Type base, spi_master_handle_t handle, size_t *count)
	Gets the master transfer count. More...

void	SPI_MasterTransferAbort (SPI_Type base, spi_master_handle_t handle)
	SPI master aborts a transfer using an interrupt. More...

void	SPI_MasterTransferHandleIRQ (SPI_Type base, spi_master_handle_t handle)
	Interrupts the handler for the SPI. More...

Data Structure Documentation

struct spi_delay_config_t

Note: The DLY register controls several programmable delays related to SPI signalling, it stands for how many SPI clock time will be inserted. The maxinun value of these delay time is 15.

Data Fields
uint8_t	preDelay
	Delay between SSEL assertion and the beginning of transfer. More...

uint8_t	postDelay
	Delay between the end of transfer and SSEL deassertion. More...

uint8_t	frameDelay
	Delay between frame to frame. More...

uint8_t	transferDelay
	Delay between transfer to transfer. More...

Field Documentation

uint8_t spi_delay_config_t::preDelay

uint8_t spi_delay_config_t::postDelay

uint8_t spi_delay_config_t::frameDelay

uint8_t spi_delay_config_t::transferDelay

struct spi_master_config_t

Data Fields
bool	enableLoopback
	Enable loopback for test purpose.

bool	enableMaster
	Enable SPI at initialization time.

spi_clock_polarity_t	polarity
	Clock polarity.

spi_clock_phase_t	phase
	Clock phase.

spi_shift_direction_t	direction
	MSB or LSB.

uint32_t	baudRate_Bps
	Baud Rate for SPI in Hz.

spi_data_width_t	dataWidth
	Width of the data.

spi_ssel_t	sselNum
	Slave select number.

spi_spol_t	sselPol
	Configure active CS polarity.

uint8_t	txWatermark
	txFIFO watermark

uint8_t	rxWatermark
	rxFIFO watermark

spi_delay_config_t	delayConfig
	Delay configuration. More...

Field Documentation

spi_delay_config_t spi_master_config_t::delayConfig

struct spi_transfer_t

Data Fields
uint8_t *	txData
	Send buffer.

uint8_t *	rxData
	Receive buffer.

uint32_t	configFlags
	Additional option to control transfer, spi_xfer_option_t. More...

size_t	dataSize
	Transfer bytes.

Field Documentation

uint32_t spi_transfer_t::configFlags

struct spi_config_t

struct _spi_master_handle

Master handle type.

Data Fields
uint8_t *volatile	txData
	Transfer buffer.

uint8_t *volatile	rxData
	Receive buffer.

volatile size_t	txRemainingBytes
	Number of data to be transmitted [in bytes].

volatile size_t	rxRemainingBytes
	Number of data to be received [in bytes].

volatile int8_t	toReceiveCount
	The number of data expected to receive in data width. More...

size_t	totalByteCount
	A number of transfer bytes.

volatile uint32_t	state
	SPI internal state.

spi_master_callback_t	callback
	SPI callback.

void *	userData
	Callback parameter.

uint8_t	dataWidth
	Width of the data [Valid values: 1 to 16].

uint8_t	sselNum
	Slave select number to be asserted when transferring data [Valid values: 0 to 3].

uint32_t	configFlags
	Additional option to control transfer.

uint8_t	txWatermark
	txFIFO watermark

uint8_t	rxWatermark
	rxFIFO watermark

Field Documentation

volatile int8_t spi_master_handle_t::toReceiveCount

Since the received count and sent count should be the same to complete the transfer, if the sent count is x and the received count is y, toReceiveCount is x-y.

Macro Definition Documentation

#define FSL_SPI_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))

#define SPI_DUMMYDATA (0xFFU)

#define SPI_RETRY_TIMES 0U /* Define to zero means keep waiting until the flag is assert/deassert. */

Typedef Documentation

typedef void(* spi_master_irq_handler_t)(SPI_Type *base, spi_master_handle_t *handle)

Enumeration Type Documentation

enum spi_xfer_option_t

Enumerator
kSPI_FrameDelay	A delay may be inserted, defined in the DLY register.
kSPI_FrameAssert	SSEL will be deasserted at the end of a transfer.

enum spi_shift_direction_t

Enumerator
kSPI_MsbFirst	Data transfers start with most significant bit.
kSPI_LsbFirst	Data transfers start with least significant bit.

enum spi_clock_polarity_t

Enumerator
kSPI_ClockPolarityActiveHigh	Active-high SPI clock (idles low).
kSPI_ClockPolarityActiveLow	Active-low SPI clock (idles high).

enum spi_clock_phase_t

Enumerator
kSPI_ClockPhaseFirstEdge	First edge on SCK occurs at the middle of the first cycle of a data transfer.
kSPI_ClockPhaseSecondEdge	First edge on SCK occurs at the start of the first cycle of a data transfer.

enum spi_txfifo_watermark_t

Enumerator
kSPI_TxFifo0	SPI tx watermark is empty.
kSPI_TxFifo1	SPI tx watermark at 1 item.
kSPI_TxFifo2	SPI tx watermark at 2 items.
kSPI_TxFifo3	SPI tx watermark at 3 items.
kSPI_TxFifo4	SPI tx watermark at 4 items.
kSPI_TxFifo5	SPI tx watermark at 5 items.
kSPI_TxFifo6	SPI tx watermark at 6 items.
kSPI_TxFifo7	SPI tx watermark at 7 items.

enum spi_rxfifo_watermark_t

Enumerator
kSPI_RxFifo1	SPI rx watermark at 1 item.
kSPI_RxFifo2	SPI rx watermark at 2 items.
kSPI_RxFifo3	SPI rx watermark at 3 items.
kSPI_RxFifo4	SPI rx watermark at 4 items.
kSPI_RxFifo5	SPI rx watermark at 5 items.
kSPI_RxFifo6	SPI rx watermark at 6 items.
kSPI_RxFifo7	SPI rx watermark at 7 items.
kSPI_RxFifo8	SPI rx watermark at 8 items.

enum spi_data_width_t

Enumerator
kSPI_Data8Bits	8 bits data width (7)
kSPI_Data16Bits	16 bits data width (15)

enum spi_ssel_t

Enumerator
kSPI_Ssel0	Slave select 0.

anonymous enum

Enumerator
kStatus_SPI_Busy	SPI bus is busy.
kStatus_SPI_Idle	SPI is idle.
kStatus_SPI_Error	SPI error.
kStatus_SPI_BaudrateNotSupport	Baudrate is not support in current clock source.
kStatus_SPI_Timeout	SPI timeout polling status flags.

enum _spi_interrupt_enable

Enumerator
kSPI_RxErrIrq	Rx error interrupt.
kSPI_TxErrIrq	Tx error interrupt.
kSPI_RxLvlIrq	Rx level interrupt.
kSPI_TxLvlIrq	Tx level interrupt.
kSPI_SlaveSelectAssertIrq	Slave select assert.
kSPI_SlaveSelectDeassertIrq	Slave select deassert.
kSPI_MasterIdleIrq	Master idle.

enum _spi_statusflags

Enumerator
kSPI_TxEmptyFlag	txFifo is empty
kSPI_TxNotFullFlag	txFifo is not full
kSPI_RxNotEmptyFlag	rxFIFO is not empty
kSPI_RxFullFlag	rxFIFO is full

Function Documentation

uint32_t SPI_GetInstance ( SPI_Type * base )

void SPI_MasterGetDefaultConfig ( spi_master_config_t * config )

The purpose of this API is to get the configuration structure initialized for use in SPI_MasterInit(). User may use the initialized structure unchanged in SPI_MasterInit(), or modify some fields of the structure before calling SPI_MasterInit(). After calling this API, the master is ready to transfer. Example:

spi_master_config_t config;

SPI_MasterGetDefaultConfig(&config);

Parameters

config pointer to master config structure

status_t SPI_MasterInit	(	SPI_Type *	base,
		const spi_master_config_t *	config,
		uint32_t	srcClock_Hz
	)

The configuration structure can be filled by user from scratch, or be set with default values by SPI_MasterGetDefaultConfig(). After calling this API, the slave is ready to transfer. Example

spi_master_config_t config = {
.baudRate_Bps = 400000,
...
};
SPI_MasterInit(SPI0, &config);

Parameters

base	SPI base pointer
config	pointer to master configuration structure
srcClock_Hz	Source clock frequency.

void SPI_Deinit ( SPI_Type * base )

Calling this API resets the SPI module, gates the SPI clock. The SPI module can't work unless calling the SPI_MasterInit/SPI_SlaveInit to initialize module.

Parameters

base	SPI base pointer

static void SPI_Enable	(	SPI_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	SPI base pointer
enable	or disable ( true = enable, false = disable)

static uint32_t SPI_GetStatusFlags ( SPI_Type * base )

inlinestatic

Parameters

base	SPI base pointer

Returns: SPI Status, use status flag to AND _spi_statusflags could get the related status.

static void SPI_EnableInterrupts	(	SPI_Type *	base,
		uint32_t	irqs
	)

inlinestatic

Parameters

base	SPI base pointer
irqs	SPI interrupt source. The parameter can be any combination of the following values: kSPI_RxErrIrq kSPI_TxErrIrq kSPI_RxLvlIrq kSPI_TxLvlIrq kSPI_SlaveSelectAssertIrq kSPI_SlaveSelectDeassertIrq kSPI_MasterIdleIrq

static void SPI_DisableInterrupts	(	SPI_Type *	base,
		uint32_t	irqs
	)

inlinestatic

Parameters

base	SPI base pointer
irqs	SPI interrupt source. The parameter can be any combination of the following values: kSPI_RxErrIrq kSPI_TxErrIrq kSPI_RxLvlIrq kSPI_TxLvlIrq kSPI_SlaveSelectAssertIrq kSPI_SlaveSelectDeassertIrq kSPI_MasterIdleIrq

void SPI_EnableTxDMA	(	SPI_Type *	base,
		bool	enable
	)

Parameters

base	SPI base pointer
enable	True means enable DMA, false means disable DMA

void SPI_EnableRxDMA	(	SPI_Type *	base,
		bool	enable
	)

Parameters

base	SPI base pointer
enable	True means enable DMA, false means disable DMA

void* SPI_GetConfig ( SPI_Type * base )

Parameters

base	SPI peripheral address.

Returns: return configurations which contain datawidth and SSEL numbers. return data type is a pointer of spi_config_t.

status_t SPI_MasterSetBaud	(	SPI_Type *	base,
		uint32_t	baudrate_Bps,
		uint32_t	srcClock_Hz
	)

This is only used in master.

Parameters

base	SPI base pointer
baudrate_Bps	baud rate needed in Hz.
srcClock_Hz	SPI source clock frequency in Hz.

void SPI_WriteData	(	SPI_Type *	base,
		uint16_t	data,
		uint32_t	configFlags
	)

Parameters

base	SPI base pointer
data	needs to be write.
configFlags	transfer configuration options spi_xfer_option_t

static uint32_t SPI_ReadData ( SPI_Type * base )

inlinestatic

Parameters

base	SPI base pointer

Returns: Data in the register.

static void SPI_SetTransferDelay	(	SPI_Type *	base,
		const spi_delay_config_t *	config
	)

inlinestatic

   the delay uint is SPI clock time, maximum value is 0xF.

Parameters

base	SPI base pointer
config	configuration for delay option spi_delay_config_t.

void SPI_SetDummyData	(	SPI_Type *	base,
		uint8_t	dummyData
	)

Parameters

base	SPI peripheral address.
dummyData	Data to be transferred when tx buffer is NULL.

status_t SPI_MasterTransferCreateHandle	(	SPI_Type *	base,
		spi_master_handle_t *	handle,
		spi_master_callback_t	callback,
		void *	userData
	)

This function initializes the SPI master handle which can be used for other SPI master transactional APIs. Usually, for a specified SPI instance, call this API once to get the initialized handle.

Parameters

base	SPI peripheral base address.
handle	SPI handle pointer.
callback	Callback function.
userData	User data.

status_t SPI_MasterTransferBlocking	(	SPI_Type *	base,
		spi_transfer_t *	xfer
	)

Parameters

base	SPI base pointer
xfer	pointer to spi_xfer_config_t structure

Return values

kStatus_Success	Successfully start a transfer.
kStatus_InvalidArgument	Input argument is invalid.
kStatus_SPI_Timeout	The transfer timed out and was aborted.

status_t SPI_MasterTransferNonBlocking	(	SPI_Type *	base,
		spi_master_handle_t *	handle,
		spi_transfer_t *	xfer
	)

Parameters

base	SPI peripheral base address.
handle	pointer to spi_master_handle_t structure which stores the transfer state
xfer	pointer to spi_xfer_config_t structure

Return values

kStatus_Success	Successfully start a transfer.
kStatus_InvalidArgument	Input argument is invalid.
kStatus_SPI_Busy	SPI is not idle, is running another transfer.

status_t SPI_MasterTransferGetCount	(	SPI_Type *	base,
		spi_master_handle_t *	handle,
		size_t *	count
	)

This function gets the master transfer count.

Parameters

base	SPI peripheral base address.
handle	Pointer to the spi_master_handle_t structure which stores the transfer state.
count	The number of bytes transferred by using the non-blocking transaction.

Returns: status of status_t.

void SPI_MasterTransferAbort	(	SPI_Type *	base,
		spi_master_handle_t *	handle
	)

This function aborts a transfer using an interrupt.

Parameters

base	SPI peripheral base address.
handle	Pointer to the spi_master_handle_t structure which stores the transfer state.

void SPI_MasterTransferHandleIRQ	(	SPI_Type *	base,
		spi_master_handle_t *	handle
	)

Parameters

base	SPI peripheral base address.
handle	pointer to spi_master_handle_t structure which stores the transfer state.

Variable Documentation

volatile uint8_t s_dummyData[]

Overview

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Driver version

Initialization and deinitialization

Status

Interrupts

DMA Control

Bus Operations

Transactional

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation