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#

SPIDRV_Init_t

SPIDRV_HandleData_t

SPIDRV_Init

Error Codes

Init Configuration Data

Enumerations#

enum
spidrvMaster = 0
spidrvSlave = 1
}

SPI driver instance type.

enum
spidrvBitOrderLsbFirst = 0
spidrvBitOrderMsbFirst = 1
}

SPI bus bit order.

enum
spidrvClockMode0 = 0
spidrvClockMode1 = 1
spidrvClockMode2 = 2
spidrvClockMode3 = 3
}

SPI clock mode (clock polarity and phase).

enum
spidrvCsControlAuto = 0
spidrvCsControlApplication = 1
}

SPI master chip select (CS) control scheme.

enum
spidrvSlaveStartImmediate = 0
spidrvSlaveStartDelayed = 1
}

SPI slave transfer start scheme.

Typedefs#

typedef void(*
SPIDRV_Callback_t)(struct SPIDRV_HandleData *handle, Ecode_t transferStatus, int itemsTransferred)

SPIDRV transfer completion callback function.

An SPI driver instance handle.

Functions#

SPIDRV_AbortTransfer(SPIDRV_Handle_t handle)

Abort an ongoing SPI transfer.

SPIDRV_DeInit(SPIDRV_Handle_t handle)

Deinitialize an SPI driver instance.

SPIDRV_GetBitrate(SPIDRV_Handle_t handle, uint32_t *bitRate)

Get current SPI bus bitrate.

SPIDRV_GetFramelength(SPIDRV_Handle_t handle, uint32_t *frameLength)

Get current SPI framelength.

SPIDRV_GetTransferStatus(SPIDRV_Handle_t handle, int *itemsTransferred, int *itemsRemaining)

Get the status of an SPI transfer.

SPIDRV_Init(SPIDRV_Handle_t handle, SPIDRV_Init_t *initData)

Initialize an SPI driver instance.

SPIDRV_MReceive(SPIDRV_Handle_t handle, void *buffer, int count, SPIDRV_Callback_t callback)

Start an SPI master receive transfer.

SPIDRV_MReceiveB(SPIDRV_Handle_t handle, void *buffer, int count)

Start an SPI master blocking receive transfer.

SPIDRV_MTransfer(SPIDRV_Handle_t handle, const void *txBuffer, void *rxBuffer, int count, SPIDRV_Callback_t callback)

Start an SPI master transfer.

SPIDRV_MTransferB(SPIDRV_Handle_t handle, const void *txBuffer, void *rxBuffer, int count)

Start an SPI master blocking transfer.

SPIDRV_MTransferSingleItemB(SPIDRV_Handle_t handle, uint32_t txValue, void *rxValue)

Start an SPI master blocking single item (frame) transfer.

SPIDRV_MTransmit(SPIDRV_Handle_t handle, const void *buffer, int count, SPIDRV_Callback_t callback)

Start an SPI master transmit transfer.

SPIDRV_MTransmitB(SPIDRV_Handle_t handle, const void *buffer, int count)

Start an SPI master blocking transmit transfer.

SPIDRV_SetBitrate(SPIDRV_Handle_t handle, uint32_t bitRate)

Set SPI bus bitrate.

SPIDRV_SetFramelength(SPIDRV_Handle_t handle, uint32_t frameLength)

Set SPI framelength.

SPIDRV_SReceive(SPIDRV_Handle_t handle, void *buffer, int count, SPIDRV_Callback_t callback, int timeoutMs)

Start an SPI slave receive transfer.

SPIDRV_SReceiveB(SPIDRV_Handle_t handle, void *buffer, int count, int timeoutMs)

Start an SPI slave blocking receive transfer.

SPIDRV_STransfer(SPIDRV_Handle_t handle, const void *txBuffer, void *rxBuffer, int count, SPIDRV_Callback_t callback, int timeoutMs)

Start an SPI slave transfer.

SPIDRV_STransferB(SPIDRV_Handle_t handle, const void *txBuffer, void *rxBuffer, int count, int timeoutMs)

Start an SPI slave blocking transfer.

SPIDRV_STransmit(SPIDRV_Handle_t handle, const void *buffer, int count, SPIDRV_Callback_t callback, int timeoutMs)

Start an SPI slave transmit transfer.

SPIDRV_STransmitB(SPIDRV_Handle_t handle, const void *buffer, int count, int timeoutMs)

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.


Definition at line 73 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.


Definition at line 79 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.


Definition at line 85 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.


Definition at line 93 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).


Definition at line 99 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.

Parameters
[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


Definition at line 141 of file platform/emdrv/spidrv/inc/spidrv.h

SPIDRV_Handle_t#

typedef SPIDRV_HandleData_t* SPIDRV_Handle_t

An SPI driver instance handle.


Definition at line 221 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.

Parameters
[in]handle

Pointer to an SPI driver handle.

Returns


Definition at line 1017 of file platform/emdrv/spidrv/inc/spidrv.h

SPIDRV_DeInit#

Ecode_t SPIDRV_DeInit (SPIDRV_Handle_t handle)

Deinitialize an SPI driver instance.

Parameters
[in]handle

Pointer to an SPI driver handle.

Warnings

  • This function should only be called with an initialized spidrv instance handle.

Returns


Definition at line 1019 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.

Parameters
[in]handle

Pointer to an SPI driver handle.

[out]bitRate

Current SPI bus bitrate.

Returns


Definition at line 1021 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.

Parameters
[in]handle

Pointer to an SPI driver handle.

[out]frameLength

Current SPI bus framelength.

Returns


Definition at line 1024 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.

Parameters
[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


Definition at line 1027 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.

Parameters
[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


Definition at line 1031 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.

Parameters
[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


Definition at line 1034 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.

Parameters
[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


Definition at line 1039 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.

Parameters
[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


Definition at line 1043 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.

Parameters
[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

Returns


Definition at line 1049 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.

Parameters
[in]handle

Pointer to an SPI driver handle.

[in]txValue

Value to transmit.

[out]rxValue

Value received.

Note

Returns


Definition at line 1054 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.

Parameters
[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


Definition at line 1058 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.

Parameters
[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


Definition at line 1063 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.

Parameters
[in]handle

Pointer to an SPI driver handle.

[in]bitRate

New SPI bus bitrate.

Returns


Definition at line 1067 of file platform/emdrv/spidrv/inc/spidrv.h

SPIDRV_SetFramelength#

Ecode_t SPIDRV_SetFramelength (SPIDRV_Handle_t handle, uint32_t frameLength)

Set SPI framelength.

Parameters
[in]handle

Pointer to an SPI driver handle.

[in]frameLength

New SPI bus framelength.

Returns


Definition at line 1070 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.

Parameters
[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


Definition at line 1073 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.

Parameters
[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


Definition at line 1079 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.

Parameters
[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


Definition at line 1084 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.

Parameters
[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


Definition at line 1091 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.

Parameters
[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


Definition at line 1097 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.

Parameters
[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


Definition at line 1103 of file platform/emdrv/spidrv/inc/spidrv.h