CMSIS Driver  Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SPI Interface

Driver API for SPI Bus Master Peripheral in 8-bit mode (Driver_SPI.h) More...

Data Structures

struct  ARM_DRIVER_SPI
 Access structure of the SPI Driver. More...
 
struct  ARM_SPI_CAPABILITIES
 SPI Driver Capabilities. More...
 

Typedefs

typedef void(* ARM_SPI_SignalEvent_t )(ARM_SPI_EVENT event)
 Pointer to ARM_SPI_SignalEvent : Signal SPI Event.
 

Enumerations

enum  ARM_SPI_STATUS {
  ARM_SPI_OK = 0,
  ARM_SPI_ERROR = 1,
  ARM_SPI_ERROR_UNSUPPORTED = 2
}
 SPI Status of executed operation. More...
 
enum  ARM_SPI_FRAME_FORMAT {
  ARM_SPI_CPOL0_CPHA0,
  ARM_SPI_CPOL0_CPHA1,
  ARM_SPI_CPOL1_CPHA0,
  ARM_SPI_CPOL1_CPHA1
}
 SPI Frame Format. More...
 
enum  ARM_SPI_BIT_ORDER {
  ARM_SPI_MSB_LSB,
  ARM_SPI_LSB_MSB
}
 SPI Bit Order. More...
 
enum  ARM_SPI_SS_SIGNAL {
  ARM_SPI_SS_INACTIVE,
  ARM_SPI_SS_ACTIVE
}
 SPI Slave Select Signal. More...
 
enum  ARM_SPI_EVENT { ARM_SPI_EVENT_SEND_DONE }
 SPI Event. More...
 

Functions

ARM_DRV_VERSION ARM_SPI_GetVersion (void)
 Get driver version.
 
ARM_SPI_CAPABILITIES ARM_SPI_GetCapabilities (void)
 Get driver capabilities.
 
ARM_SPI_STATUS ARM_SPI_Initialize (ARM_SPI_SignalEvent_t cb_event)
 Initialize SPI Interface.
 
ARM_SPI_STATUS ARM_SPI_Uninitialize (void)
 De-initialize SPI Interface.
 
ARM_SPI_STATUS ARM_SPI_PowerControl (ARM_POWER_STATE state)
 Control SPI Interface Power.
 
ARM_SPI_STATUS ARM_SPI_Configure (ARM_SPI_FRAME_FORMAT frame_format, ARM_SPI_BIT_ORDER bit_order)
 Configure SPI Interface.
 
uint32_t ARM_SPI_BusSpeed (uint32_t bps)
 Set bus speed for SPI transfers.
 
ARM_SPI_STATUS ARM_SPI_SlaveSelect (ARM_SPI_SS_SIGNAL ss)
 Control Slave Select (SS) signal.
 
uint8_t ARM_SPI_TransferByte (uint8_t out)
 Send and receive one byte via SPI Interface.
 
ARM_SPI_STATUS ARM_SPI_SendData (const uint8_t *buf, uint32_t len)
 Send data block to SPI Slave.
 
ARM_SPI_STATUS ARM_SPI_ReceiveData (uint8_t *buf, uint32_t len, uint8_t out)
 Receive data block from SPI Slave.
 
ARM_SPI_STATUS ARM_SPI_AbortTransfer (void)
 Abort current SPI transfer.
 
void ARM_SPI_SignalEvent (ARM_SPI_EVENT event)
 Signal SPI Event.
 

Description

Driver API for SPI Bus Master Peripheral in 8-bit mode (Driver_SPI.h)

The Serial Peripheral Interface Bus (SPI) implements a synchronous serial bus for data exchange. In microcontroller (MCU) applications, the interface is often used to connect peripheral components at board (PCB) level. SPI devices can operate as Master (SCLK and SS are outputs) or Slave (SCLK and SS are inputs). Wikipedia offers more information about the Serial Peripheral Interface Bus.

SPI Structure

The SPI Driver API defines an SPI Master interface for middleware components. The SPI Driver supports multiple slaves, but if only one slave is connected, then the Slave Select signal can be omitted.

SPI_Master1Slaves.png
SPI Master connected to a single slave

 

SPI_Master3Slaves.png
SPI Master connected to 3 slaves

The SPI Driver functions control the following SPI signal lines.

Signal Name Description
SS Slave Select (active low) ARM_SPI_SlaveSelect controls this signal, which can be part of the SPI peripheral or implemented using a GPIO pin.
MOSI Master Out, Slave In MOSI output of the Master connects to MOSI input of the Slave.
SCLK System Clock Serial clock output from Master. Controls the transfer speed and when data are sent and read.
MISO Master In, Slave Out MISO input of the Master connects to MISO input of the Slave.

SPI API

The following header files define the Application Programming Interface (API) for the SPI interface:

The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.

Driver Functions

The driver functions are published in the access struct as explained in Driver Functions

A typical setup sequence for the driver is shown below:

Example Code:


Data Structure Documentation

struct ARM_DRIVER_SPI

Access structure of the SPI Driver.

The functions of the SPI driver are accessed by function pointers exposed by this structure. Refer to Driver Functions for overview information.

Each instance of an SPI interface provides such an access structure. The instance is identified by a postfix number in the symbol name of the access structure, for example:

  • ARM_DRIVER_SPI0 is the name of the access struct of the first instance (no. 0).
  • ARM_DRIVER_SPI1 is the name of the access struct of the second instance (no. 1).

A middleware configuration setting allows connecting the middleware to a specific driver instance ARM_DRIVER_SPIn. The default is 0, which connects a middleware to the first instance of a driver.

Data Fields

ARM_DRV_VERSION(* GetVersion )(void)
 Pointer to ARM_SPI_GetVersion : Get driver version.
 
ARM_SPI_CAPABILITIES(* GetCapabilities )(void)
 Pointer to ARM_SPI_GetCapabilities : Get driver capabilities.
 
ARM_SPI_STATUS(* Initialize )(ARM_SPI_SignalEvent_t cb_event)
 Pointer to ARM_SPI_Initialize : Initialize SPI Interface.
 
ARM_SPI_STATUS(* Uninitialize )(void)
 Pointer to ARM_SPI_Uninitialize : De-initialize SPI Interface.
 
ARM_SPI_STATUS(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_SPI_PowerControl : Control SPI Interface Power.
 
ARM_SPI_STATUS(* Configure )(ARM_SPI_FRAME_FORMAT frame_format, ARM_SPI_BIT_ORDER bit_order)
 Pointer to ARM_SPI_Configure : Configure SPI Interface.
 
uint32_t(* BusSpeed )(uint32_t bps)
 Pointer to ARM_SPI_BusSpeed : Set bus speed for SPI transfers.
 
ARM_SPI_STATUS(* SlaveSelect )(ARM_SPI_SS_SIGNAL ss)
 Pointer to ARM_SPI_SlaveSelect : Control Slave Select signal.
 
uint8_t(* TransferByte )(uint8_t out)
 Pointer to ARM_SPI_TransferByte : Send and receive one byte via SPI Interface.
 
ARM_SPI_STATUS(* SendData )(const uint8_t *buf, uint32_t len)
 Pointer to ARM_SPI_SendData : Send data block to SPI Slave.
 
ARM_SPI_STATUS(* ReceiveData )(uint8_t *buf, uint32_t len, uint8_t out)
 Pointer to ARM_SPI_ReceiveData : Receive data block from SPI Slave.
 
ARM_SPI_STATUS(* AbortTransfer )(void)
 Pointer to ARM_SPI_AbortTransfer : Abort current SPI transfer.
 

Field Documentation

ARM_SPI_STATUS(* AbortTransfer)(void)

Pointer to ARM_SPI_AbortTransfer : Abort current SPI transfer.

uint32_t(* BusSpeed)(uint32_t bps)

Pointer to ARM_SPI_BusSpeed : Set bus speed for SPI transfers.

ARM_SPI_STATUS(* Configure)(ARM_SPI_FRAME_FORMAT frame_format, ARM_SPI_BIT_ORDER bit_order)

Pointer to ARM_SPI_Configure : Configure SPI Interface.

ARM_SPI_CAPABILITIES(* GetCapabilities)(void)

Pointer to ARM_SPI_GetCapabilities : Get driver capabilities.

ARM_DRV_VERSION(* GetVersion)(void)

Pointer to ARM_SPI_GetVersion : Get driver version.

ARM_SPI_STATUS(* Initialize)(ARM_SPI_SignalEvent_t cb_event)

Pointer to ARM_SPI_Initialize : Initialize SPI Interface.

ARM_SPI_STATUS(* PowerControl)(ARM_POWER_STATE state)

Pointer to ARM_SPI_PowerControl : Control SPI Interface Power.

ARM_SPI_STATUS(* ReceiveData)(uint8_t *buf, uint32_t len, uint8_t out)

Pointer to ARM_SPI_ReceiveData : Receive data block from SPI Slave.

ARM_SPI_STATUS(* SendData)(const uint8_t *buf, uint32_t len)

Pointer to ARM_SPI_SendData : Send data block to SPI Slave.

ARM_SPI_STATUS(* SlaveSelect)(ARM_SPI_SS_SIGNAL ss)

Pointer to ARM_SPI_SlaveSelect : Control Slave Select signal.

uint8_t(* TransferByte)(uint8_t out)

Pointer to ARM_SPI_TransferByte : Send and receive one byte via SPI Interface.

ARM_SPI_STATUS(* Uninitialize)(void)

Pointer to ARM_SPI_Uninitialize : De-initialize SPI Interface.

struct ARM_SPI_CAPABILITIES

SPI Driver Capabilities.

An SPI driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.

Returned by:

Data Fields
uint32_t reserved: 31 reserved for future use
uint32_t send_done_event: 1 Signal send data completed: ARM_SPI_EVENT_SEND_DONE.

Typedef Documentation

ARM_SPI_SignalEvent_t

Pointer to ARM_SPI_SignalEvent : Signal SPI Event.

Provides the typedef for the callback function ARM_SPI_SignalEvent.

Parameter for:

Enumeration Type Documentation

SPI Bit Order.

Specifies whether SPI data transmission starts with the LSB bit or MSB bit.

Parameter for:

Enumerator:
ARM_SPI_MSB_LSB 

SPI Bit order from MSB to LSB.

ARM_SPI_LSB_MSB 

SPI Bit order from LSB to MSB.

SPI Event.

Provides values for for the ARM_SPI_SignalEvent callback function (which is registered by the function ARM_SPI_Initialize). The function ARM_SPI_GetCapabilities returns information about the implemented callback events in a driver.

Enumerator:
ARM_SPI_EVENT_SEND_DONE 

send data completed

SPI Frame Format.

Specifies the clock polarity and the phase for SPI data transmissions.

Parameter for:

Enumerator:
ARM_SPI_CPOL0_CPHA0 

Clock Polarity 0, Clock Phase 0.

ARM_SPI_CPOL0_CPHA1 

Clock Polarity 0, Clock Phase 1.

ARM_SPI_CPOL1_CPHA0 

Clock Polarity 1, Clock Phase 0.

ARM_SPI_CPOL1_CPHA1 

Clock Polarity 1, Clock Phase 1.

SPI Slave Select Signal.

Lists values for controlling slave select signals.

Parameter for:

Enumerator:
ARM_SPI_SS_INACTIVE 

SPI Slave Select Signal Inactive.

ARM_SPI_SS_ACTIVE 

SPI Slave Select Signal Active.

SPI Status of executed operation.

Defines status and error codes returned by most of the MCI driver functions.

Returned by:

Enumerator:
ARM_SPI_OK 

SPI Status: Operation succeeded.

ARM_SPI_ERROR 

SPI Status: Unspecified error.

ARM_SPI_ERROR_UNSUPPORTED 

SPI Status: Operation not supported.

Function Documentation

ARM_SPI_STATUS ARM_SPI_AbortTransfer ( void  )

Abort current SPI transfer.

Returns
execution status ARM_SPI_STATUS

Stop an ongoing SPI data transfer operation that was initiated with the function ARM_SPI_ReceiveData or ARM_SPI_SendData.

uint32_t ARM_SPI_BusSpeed ( uint32_t  bps)

Set bus speed for SPI transfers.

Parameters
[in]bpsRequested speed in bits/s
Returns
Configured bus speed in bits/s

Set the data transfer speed of the SPI to the requested baud rate in bits per second.

ARM_SPI_STATUS ARM_SPI_Configure ( ARM_SPI_FRAME_FORMAT  frame_format,
ARM_SPI_BIT_ORDER  bit_order 
)

Configure SPI Interface.

Parameters
[in]frame_formatARM_SPI_FRAME_FORMAT
[in]bit_orderARM_SPI_BIT_ORDER
Returns
execution status ARM_SPI_STATUS

Configure the frame format and the bit order of the SPI data transfer.

ARM_SPI_CAPABILITIES ARM_SPI_GetCapabilities ( void  )

Get driver capabilities.

Returns
ARM_SPI_CAPABILITIES

Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_SPI_CAPABILITIES encode various capabilities, for example if a hardware is capable of signaling events using the ARM_SPI_SignalEvent callback function.

Example:

extern ARM_DRIVER_SPI ARM_Driver_SPI0;
ARM_DRIVER_SPI *drv_info;
void read_capabilities (void) {
ARM_SPI_CAPABILITIES drv_capabilities;
drv_info = &ARM_Driver_SPI0;
drv_capablilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
ARM_DRV_VERSION ARM_SPI_GetVersion ( void  )

Get driver version.

Returns
ARM_DRV_VERSION

Returns version information of the driver implementation in ARM_DRV_VERSION

  • API version is the version of the CMSIS-Driver specification used to implement this driver.
  • Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_SPI ARM_Driver_SPI0;
ARM_DRIVER_SPI *drv_info;
void setup_spi (void) {
ARM_DRV_VERSION version;
drv_info = &ARM_Driver_SPI0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
ARM_SPI_STATUS ARM_SPI_Initialize ( ARM_SPI_SignalEvent_t  cb_event)

Initialize SPI Interface.

Parameters
[in]cb_eventPointer to ARM_SPI_SignalEvent
Returns
execution status ARM_SPI_STATUS

The function initializes the SPI interface. It is called when the middleware component starts operation.

The function performs the following operations:

  • Initializes the resources needed for the SPI interface.
  • Registers the ARM_SPI_SignalEvent callback function.
  • Sets the peripheral to ARM_POWER_LOW power mode.

The parameter cb_event is a pointer to the ARM_SPI_SignalEvent callback function; use a NULL pointer when no callback signals are required.

Example:

ARM_SPI_STATUS ARM_SPI_PowerControl ( ARM_POWER_STATE  state)

Control SPI Interface Power.

Parameters
[in]statePower state
Returns
execution status ARM_SPI_STATUS

Allows to control the power modes of the SPI interface.

state can be:

  • ARM_POWER_OFF: SPI peripheral is turned off.
  • ARM_POWER_FULL: SPI peripheral is turned on and fully operational.
  • ARM_POWER_LOW: not available on an SPI interface.

If state specifies an unsupported mode, the function returns ARM_SPI_ERROR_UNSUPPORTED.

ARM_SPI_STATUS ARM_SPI_ReceiveData ( uint8_t *  buf,
uint32_t  len,
uint8_t  out 
)

Receive data block from SPI Slave.

Parameters
[out]bufPointer to the buffer for receiving data
[in]lenData buffer length in bytes
[in]outByte to be sent repeatedly during receive
Returns
execution status ARM_SPI_STATUS

Receive a data block from the SPI Slave and store the content in a data buffer.

ARM_SPI_STATUS ARM_SPI_SendData ( const uint8_t *  buf,
uint32_t  len 
)

Send data block to SPI Slave.

Parameters
[in]bufPointer to the buffer containing data to send
[in]lenData buffer length in bytes
Returns
execution status ARM_SPI_STATUS

Send the content of a data buffer to the SPI Slave.

The function may return even when not all data are transferred, but it is ensured that the content in the data buffer is fully consumed and transferred to internal buffers on function return.

void ARM_SPI_SignalEvent ( ARM_SPI_EVENT  event)

Signal SPI Event.

Parameters
[in]eventARM_SPI_EVENT
Returns
none

Signal that an ARM_SPI_SendData operation has been completed. This optional call back function is implemented in the middleware and published to the driver by the function ARM_SPI_Initialize.

ARM_SPI_STATUS ARM_SPI_SlaveSelect ( ARM_SPI_SS_SIGNAL  ss)

Control Slave Select (SS) signal.

Parameters
[in]ssSlave Select status ARM_SPI_SS_SIGNAL
Returns
execution status ARM_SPI_STATUS

Control the Slave Select (SS) output of the SPI interface. The function also sets the SPI to the active or inactive state. It is mandatory also when then SPI does not provide an SS output.

uint8_t ARM_SPI_TransferByte ( uint8_t  out)

Send and receive one byte via SPI Interface.

Parameters
[in]outByte to be sent to the SPI data output
Returns
Byte received from the SPI data input

Send and receive one byte via the SPI Interface.

ARM_SPI_STATUS ARM_SPI_Uninitialize ( void  )

De-initialize SPI Interface.

Returns
execution status ARM_SPI_STATUS

The function ARM_SPI_Uninitialize de-initializes the resources of SPI interface and sets the peripheral to ARM_POWER_LOW power mode.

It is called when the middleware component stops operation and releases the software resources used by the interface.