SPIDRV - SPI Driver#
Serial Peripheral Interface Driver.
The spidrv.c and spidrv.h source files for the SPI driver library are in the emdrv/spidrv folder.
Introduction#
The SPI driver supports the SPI capabilities of EFM32/EZR32/EFR32 USARTs. The driver is fully reentrant, supports several driver instances, and does not buffer or queue data. Both synchronous and asynchronous transfer functions are included for both master and slave SPI mode. Synchronous transfer functions are blocking and do not return before the transfer is complete. Asynchronous transfer functions report transfer completion with callback functions. Transfers are handled using DMA.
Note
Transfer completion callback functions are called from within the DMA interrupt handler with interrupts disabled.
Configuration Options#
Some properties of the SPIDRV driver are compile-time configurable. These properties are stored in a file named spidrv_config.h. A template for this file, containing default values, is in the emdrv/config folder. Currently the configuration options are as follows:
Inclusion of slave API transfer functions.
To configure SPIDRV, provide a custom configuration file. This is a sample spidrv_config.h file:
#ifndef __SILICON_LABS_SPIDRV_CONFIG_H__
#define __SILICON_LABS_SPIDRV_CONFIG_H__
// SPIDRV configuration option. Use this define to include the
// slave part of the SPIDRV API.
#define EMDRV_SPIDRV_INCLUDE_SLAVE
#endif
The properties of each SPI driver instance are set at run-time using the SPIDRV_Init data structure input parameter to the SPIDRV_Init() function.
The API#
This section contains brief descriptions of the API functions. For detailed information on input and output parameters and return values, click on the hyperlinked function names. Most functions return an error code, ECODE_EMDRV_SPIDRV_OK is returned on success, see ecode.h and spidrv.h for other error codes.
The application code must include spidrv.h.
SPIDRV_Init(), SPIDRV_DeInit()
These functions initialize or deinitializes the SPIDRV driver. Typically, SPIDRV_Init() is called once in the startup code.
SPIDRV_GetTransferStatus()
Query the status of a transfer. Reports number of items (frames) transmitted and remaining.
SPIDRV_AbortTransfer()
Stop an ongoing transfer.
SPIDRV_SetBitrate(), SPIDRV_GetBitrate()
Set or query the SPI bus bitrate.
SPIDRV_SetFramelength(), SPIDRV_GetFramelength()
Set or query SPI the bus frame length.
SPIDRV_MReceive(), SPIDRV_MReceiveB()
SPIDRV_MTransfer(), SPIDRV_MTransferB(), SPIDRV_MTransferSingleItemB()
SPIDRV_MTransmit(), SPIDRV_MTransmitB()
SPIDRV_SReceive(), SPIDRV_SReceiveB()
SPIDRV_STransfer(), SPIDRV_STransferB()
SPIDRV_STransmit(), SPIDRV_STransmitB()
SPI transfer functions for SPI masters have an uppercase M in their name, the slave counterparts have an S.
As previously mentioned, transfer functions are synchronous and asynchronous. The synchronous versions have an uppercase B (for Blocking) at the end of their function name.
Transmit functions discard received data, receive functions transmit a fixed data pattern set when the driver is initialized (SPIDRV_Init.dummyTxValue). Transfer functions both receive and transmit data.
All slave transfer functions have a millisecond timeout parameter. Use 0 for no (infinite) timeout.
Example#
#include "spidrv.h"
SPIDRV_HandleData_t handleData;
SPIDRV_Handle_t handle = &handleData;
void TransferComplete(SPIDRV_Handle_t handle,
Ecode_t transferStatus,
int itemsTransferred)
{
if (transferStatus == ECODE_EMDRV_SPIDRV_OK) {
// Success !
}
}
int main(void)
{
uint8_t buffer[10];
SPIDRV_Init_t initData = SPIDRV_MASTER_USART2;
// Initialize an SPI driver instance.
SPIDRV_Init(handle, &initData);
// Transmit data using a blocking transmit function.
SPIDRV_MTransmitB(handle, buffer, 10);
// Transmit data using a callback to catch transfer completion.
SPIDRV_MTransmit(handle, buffer, 10, TransferComplete);
}
Modules#
Enumerations#
SPI clock mode (clock polarity and phase).
SPI master chip select (CS) control scheme.
SPI slave transfer start scheme.
Typedefs#
SPIDRV transfer completion callback function.
An SPI driver instance handle.
Functions#
Abort an ongoing SPI transfer.
Deinitialize an SPI driver instance.
Get current SPI bus bitrate.
Get current SPI framelength.
Get the status of an SPI transfer.
Initialize an SPI driver instance.
Start an SPI master receive transfer.
Start an SPI master blocking receive transfer.
Start an SPI master transfer.
Start an SPI master blocking transfer.
Start an SPI master blocking single item (frame) transfer.
Start an SPI master transmit transfer.
Start an SPI master blocking transmit transfer.
Set SPI bus bitrate.
Set SPI framelength.
Start an SPI slave receive transfer.
Start an SPI slave blocking receive transfer.
Start an SPI slave transfer.
Start an SPI slave blocking transfer.
Start an SPI slave transmit transfer.
Start an SPI slave blocking transmit transfer.
Enumeration Documentation#
SPIDRV_Type_t#
SPIDRV_Type_t
SPI driver instance type.
Enumerator | |
---|---|
spidrvMaster | Act as an SPI master. |
spidrvSlave | Act as an SPI slave. |
80
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_BitOrder_t#
SPIDRV_BitOrder_t
SPI bus bit order.
Enumerator | |
---|---|
spidrvBitOrderLsbFirst | LSB bit is transmitted first. |
spidrvBitOrderMsbFirst | MSB bit is transmitted first. |
86
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_ClockMode_t#
SPIDRV_ClockMode_t
SPI clock mode (clock polarity and phase).
Enumerator | |
---|---|
spidrvClockMode0 | SPI mode 0: CLKPOL=0, CLKPHA=0. |
spidrvClockMode1 | SPI mode 1: CLKPOL=0, CLKPHA=1. |
spidrvClockMode2 | SPI mode 2: CLKPOL=1, CLKPHA=0. |
spidrvClockMode3 | SPI mode 3: CLKPOL=1, CLKPHA=1. |
92
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_CsControl_t#
SPIDRV_CsControl_t
SPI master chip select (CS) control scheme.
Enumerator | |
---|---|
spidrvCsControlAuto | CS controlled by the SPI driver. |
spidrvCsControlApplication | CS controlled by the application. |
100
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_SlaveStart_t#
SPIDRV_SlaveStart_t
SPI slave transfer start scheme.
Enumerator | |
---|---|
spidrvSlaveStartImmediate | Transfer starts immediately. |
spidrvSlaveStartDelayed | Transfer starts when the bus is idle (CS deasserted). |
106
of file platform/emdrv/spidrv/inc/spidrv.h
Typedef Documentation#
SPIDRV_Callback_t#
typedef void(* SPIDRV_Callback_t) (struct SPIDRV_HandleData *handle, Ecode_t transferStatus, int itemsTransferred) )(struct SPIDRV_HandleData *handle, Ecode_t transferStatus, int itemsTransferred)
SPIDRV transfer completion callback function.
[in] | handle | The SPIDRV device handle used to start the transfer. |
[in] | transferStatus | A number of bytes actually transferred. |
[in] | itemsTransferred | A number of bytes transferred. |
Called when a transfer is complete. An application should check the transferStatus and itemsTransferred values.
Returns
ECODE_EMDRV_SPIDRV_OK on success, ECODE_EMDRV_SPIDRV_TIMEOUT on timeout. Timeouts are only relevant for slave mode transfers.
146
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_Handle_t#
typedef SPIDRV_HandleData_t* SPIDRV_Handle_t
An SPI driver instance handle.
228
of file platform/emdrv/spidrv/inc/spidrv.h
Function Documentation#
SPIDRV_AbortTransfer#
Ecode_t SPIDRV_AbortTransfer (SPIDRV_Handle_t handle)
Abort an ongoing SPI transfer.
[in] | handle | Pointer to an SPI driver handle. |
Returns
ECODE_EMDRV_SPIDRV_OK on success, ECODE_EMDRV_SPIDRV_IDLE if SPI is idle. On failure, an appropriate SPIDRV Ecode_t is returned.
725
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_DeInit#
Ecode_t SPIDRV_DeInit (SPIDRV_Handle_t handle)
Deinitialize an SPI driver instance.
[in] | handle | Pointer to an SPI driver handle. |
Warnings
This function should only be called with an initialized spidrv instance handle.
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
727
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_GetBitrate#
Ecode_t SPIDRV_GetBitrate (SPIDRV_Handle_t handle, uint32_t * bitRate)
Get current SPI bus bitrate.
[in] | handle | Pointer to an SPI driver handle. |
[out] | bitRate | Current SPI bus bitrate. |
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
729
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_GetFramelength#
Ecode_t SPIDRV_GetFramelength (SPIDRV_Handle_t handle, uint32_t * frameLength)
Get current SPI framelength.
[in] | handle | Pointer to an SPI driver handle. |
[out] | frameLength | Current SPI bus framelength. |
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
732
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_GetTransferStatus#
Ecode_t SPIDRV_GetTransferStatus (SPIDRV_Handle_t handle, int * itemsTransferred, int * itemsRemaining)
Get the status of an SPI transfer.
[in] | handle | Pointer to an SPI driver handle. |
[out] | itemsTransferred | Number of items (frames) transferred. |
[out] | itemsRemaining | Number of items (frames) remaining. |
Returns status of an ongoing transfer. If no transfer is in progress, the status of the last transfer is reported.
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
735
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_Init#
Ecode_t SPIDRV_Init (SPIDRV_Handle_t handle, SPIDRV_Init_t * initData)
Initialize an SPI driver instance.
[out] | handle | Pointer to an SPI driver handle; refer to SPIDRV_Handle_t. |
[in] | initData | Pointer to an initialization data structure; refer to SPIDRV_Init. |
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
739
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_MReceive#
Ecode_t SPIDRV_MReceive (SPIDRV_Handle_t handle, void * buffer, int count, SPIDRV_Callback_t callback)
Start an SPI master receive transfer.
[in] | handle | Pointer to an SPI driver handle. |
[out] | buffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | callback | Transfer completion callback. |
Note
The MOSI wire will transmit SPIDRV_Init.dummyTxValue.
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
742
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_MReceiveB#
Ecode_t SPIDRV_MReceiveB (SPIDRV_Handle_t handle, void * buffer, int count)
Start an SPI master blocking receive transfer.
[in] | handle | Pointer to an SPI driver handle. |
[out] | buffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
Note
The MOSI wire will transmit SPIDRV_Init.dummyTxValue.
This function is blocking and returns when the transfer is complete or when SPIDRV_AbortTransfer() is called.
Returns
ECODE_EMDRV_SPIDRV_OK on success or ECODE_EMDRV_SPIDRV_ABORTED if SPIDRV_AbortTransfer() has been called. On failure, an appropriate SPIDRV Ecode_t is returned.
747
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_MTransfer#
Ecode_t SPIDRV_MTransfer (SPIDRV_Handle_t handle, const void * txBuffer, void * rxBuffer, int count, SPIDRV_Callback_t callback)
Start an SPI master transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | txBuffer | Transmit data buffer. |
[out] | rxBuffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | callback | Transfer completion callback. |
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
751
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_MTransferB#
Ecode_t SPIDRV_MTransferB (SPIDRV_Handle_t handle, const void * txBuffer, void * rxBuffer, int count)
Start an SPI master blocking transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | txBuffer | Transmit data buffer. |
[out] | rxBuffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
Note
This function is blocking and returns when the transfer is complete or when SPIDRV_AbortTransfer() is called.
Returns
ECODE_EMDRV_SPIDRV_OK on success or ECODE_EMDRV_SPIDRV_ABORTED if SPIDRV_AbortTransfer() has been called. On failure, an appropriate SPIDRV Ecode_t is returned.
757
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_MTransferSingleItemB#
Ecode_t SPIDRV_MTransferSingleItemB (SPIDRV_Handle_t handle, uint32_t txValue, void * rxValue)
Start an SPI master blocking single item (frame) transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | txValue | Value to transmit. |
[out] | rxValue | Value received. |
Note
This function is blocking and returns when the transfer is complete or when SPIDRV_AbortTransfer() is called.
Returns
ECODE_EMDRV_SPIDRV_OK on success or ECODE_EMDRV_SPIDRV_ABORTED if SPIDRV_AbortTransfer() has been called. On failure, an appropriate SPIDRV Ecode_t is returned.
762
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_MTransmit#
Ecode_t SPIDRV_MTransmit (SPIDRV_Handle_t handle, const void * buffer, int count, SPIDRV_Callback_t callback)
Start an SPI master transmit transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | buffer | Transmit data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | callback | Transfer completion callback. |
Note
The data received on the MISO wire is discarded.
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
766
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_MTransmitB#
Ecode_t SPIDRV_MTransmitB (SPIDRV_Handle_t handle, const void * buffer, int count)
Start an SPI master blocking transmit transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | buffer | Transmit data buffer. |
[in] | count | Number of bytes in transfer. |
Note
The data received on the MISO wire is discarded.
This function is blocking and returns when the transfer is complete.
Returns
ECODE_EMDRV_SPIDRV_OK on success or ECODE_EMDRV_SPIDRV_ABORTED if SPIDRV_AbortTransfer() has been called. On failure, an appropriate SPIDRV Ecode_t is returned.
771
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_SetBitrate#
Ecode_t SPIDRV_SetBitrate (SPIDRV_Handle_t handle, uint32_t bitRate)
Set SPI bus bitrate.
[in] | handle | Pointer to an SPI driver handle. |
[in] | bitRate | New SPI bus bitrate. |
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
775
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_SetFramelength#
Ecode_t SPIDRV_SetFramelength (SPIDRV_Handle_t handle, uint32_t frameLength)
Set SPI framelength.
[in] | handle | Pointer to an SPI driver handle. |
[in] | frameLength | New SPI bus framelength. |
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
778
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_SReceive#
Ecode_t SPIDRV_SReceive (SPIDRV_Handle_t handle, void * buffer, int count, SPIDRV_Callback_t callback, int timeoutMs)
Start an SPI slave receive transfer.
[in] | handle | Pointer to an SPI driver handle. |
[out] | buffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | callback | Transfer completion callback. |
[in] | timeoutMs | Transfer timeout in milliseconds. |
Note
The MISO wire will transmit SPIDRV_Init.dummyTxValue.
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
781
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_SReceiveB#
Ecode_t SPIDRV_SReceiveB (SPIDRV_Handle_t handle, void * buffer, int count, int timeoutMs)
Start an SPI slave blocking receive transfer.
[in] | handle | Pointer to an SPI driver handle. |
[out] | buffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | timeoutMs | Transfer timeout in milliseconds. |
Note
The MISO wire will transmit SPIDRV_Init.dummyTxValue.
This function is blocking and returns when the transfer is complete, on timeout, or when SPIDRV_AbortTransfer() is called.
Returns
ECODE_EMDRV_SPIDRV_OK on success, ECODE_EMDRV_SPIDRV_TIMEOUT on timeout or ECODE_EMDRV_SPIDRV_ABORTED if SPIDRV_AbortTransfer() has been called. On failure, an appropriate SPIDRV Ecode_t is returned.
787
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_STransfer#
Ecode_t SPIDRV_STransfer (SPIDRV_Handle_t handle, const void * txBuffer, void * rxBuffer, int count, SPIDRV_Callback_t callback, int timeoutMs)
Start an SPI slave transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | txBuffer | Transmit data buffer. |
[out] | rxBuffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | callback | Transfer completion callback. |
[in] | timeoutMs | Transfer timeout in milliseconds. |
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
792
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_STransferB#
Ecode_t SPIDRV_STransferB (SPIDRV_Handle_t handle, const void * txBuffer, void * rxBuffer, int count, int timeoutMs)
Start an SPI slave blocking transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | txBuffer | Transmit data buffer. |
[out] | rxBuffer | Receive data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | timeoutMs | Transfer timeout in milliseconds. |
Note
This function is blocking and returns when the transfer is complete, on timeout, or when SPIDRV_AbortTransfer() is called.
Returns
ECODE_EMDRV_SPIDRV_OK on success, ECODE_EMDRV_SPIDRV_TIMEOUT on timeout or ECODE_EMDRV_SPIDRV_ABORTED if SPIDRV_AbortTransfer() has been called. On failure, an appropriate SPIDRV Ecode_t is returned.
799
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_STransmit#
Ecode_t SPIDRV_STransmit (SPIDRV_Handle_t handle, const void * buffer, int count, SPIDRV_Callback_t callback, int timeoutMs)
Start an SPI slave transmit transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | buffer | Transmit data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | callback | Transfer completion callback. |
[in] | timeoutMs | Transfer timeout in milliseconds. |
Note
The data received on the MOSI wire is discarded.
Returns
ECODE_EMDRV_SPIDRV_OK on success. On failure, an appropriate SPIDRV Ecode_t is returned.
805
of file platform/emdrv/spidrv/inc/spidrv.h
SPIDRV_STransmitB#
Ecode_t SPIDRV_STransmitB (SPIDRV_Handle_t handle, const void * buffer, int count, int timeoutMs)
Start an SPI slave blocking transmit transfer.
[in] | handle | Pointer to an SPI driver handle. |
[in] | buffer | Transmit data buffer. |
[in] | count | Number of bytes in transfer. |
[in] | timeoutMs | Transfer timeout in milliseconds. |
Note
The data received on the MOSI wire is discarded.
This function is blocking and returns when the transfer is complete, on timeout, or when SPIDRV_AbortTransfer() is called.
Returns
ECODE_EMDRV_SPIDRV_OK on success, ECODE_EMDRV_SPIDRV_TIMEOUT on timeout or ECODE_EMDRV_SPIDRV_ABORTED if SPIDRV_AbortTransfer() has been called. On failure, an appropriate SPIDRV Ecode_t is returned.
811
of file platform/emdrv/spidrv/inc/spidrv.h