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#

Init Configuration Data

Enumerations#

enum

SPIDRV_Type_t {

spidrvMaster = 0

spidrvSlave = 1

}

SPI driver instance type.

enum

SPIDRV_BitOrder_t {

spidrvBitOrderLsbFirst = 0

spidrvBitOrderMsbFirst = 1

}

SPI bus bit order.

enum

SPIDRV_ClockMode_t {

spidrvClockMode0 = 0

spidrvClockMode1 = 1

spidrvClockMode2 = 2

spidrvClockMode3 = 3

}

SPI clock mode (clock polarity and phase).

enum

SPIDRV_CsControl_t {

spidrvCsControlAuto = 0

spidrvCsControlApplication = 1

}

SPI master chip select (CS) control scheme.

enum

SPIDRV_SlaveStart_t {

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.

typedef SPIDRV_HandleData_t *

SPIDRV_Handle_t

An SPI driver instance handle.

Enumerator
spidrvMaster	Act as an SPI master.
spidrvSlave	Act as an SPI slave.

Enumerator
spidrvBitOrderLsbFirst	LSB bit is transmitted first.
spidrvBitOrderMsbFirst	MSB bit is transmitted first.

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.

Enumerator
spidrvCsControlAuto	CS controlled by the SPI driver.
spidrvCsControlApplication	CS controlled by the application.

Enumerator
spidrvSlaveStartImmediate	Transfer starts immediately.
spidrvSlaveStartDelayed	Transfer starts when the bus is idle (CS deasserted).

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

[in]	handle	Pointer to an SPI driver handle.
[out]	bitRate	Current SPI bus bitrate.

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

SPIDRV - SPI Driver#

Introduction#

Configuration Options#

The API#

Example#

Modules#

Enumerations#

Typedefs#

Functions#

Enumeration Documentation#

SPIDRV_Type_t#

SPIDRV_BitOrder_t#

SPIDRV_ClockMode_t#

SPIDRV_CsControl_t#

SPIDRV_SlaveStart_t#

Typedef Documentation#

SPIDRV_Callback_t#

SPIDRV_Handle_t#

Function Documentation#

SPIDRV_AbortTransfer#

SPIDRV_DeInit#

SPIDRV_GetBitrate#

SPIDRV_GetFramelength#

SPIDRV_GetTransferStatus#

SPIDRV_Init#

SPIDRV_MReceive#

SPIDRV_MReceiveB#

SPIDRV_MTransfer#

SPIDRV_MTransferB#

SPIDRV_MTransferSingleItemB#

SPIDRV_MTransmit#

SPIDRV_MTransmitB#

SPIDRV_SetBitrate#

SPIDRV_SetFramelength#

SPIDRV_SReceive#

SPIDRV_SReceiveB#

SPIDRV_STransfer#

SPIDRV_STransferB#

SPIDRV_STransmit#

SPIDRV_STransmitB#