SPI Driver

Table of Contents

• RSPI HAL Module Introduction
  • RSPI HAL Module Features
  • RSPI Hardware Support Details
• RSPI HAL Module APIs Overview
• RSPI HAL Module Operational Overview
  • RSPI HAL Module Important Operational Notes and Limitations
    • RSPI HAL Module Operational Notes
    • RSPI HAL Module Limitations
• Including the RSPI HAL Module in an Application
• Configuring the RSPI HAL Module
  • Configuration Settings for the SPI HAL Module Lower Level Modules
  • RSPI HAL Module Clock Configuration
  • RSPI HAL Module Pin Configuration
• Using the SPI HAL Module in an Application

RSPI HAL Module Introduction

The RSPI HAL module provides a high-level API for serial communication using the SPI protocol. The module supports the SPI (formerly known as RSPI) peripheral available on the Synergy microcontroller hardware. The RSPI HAL module supports standard SPI master and Slave mode communications functions. Callbacks are provided for transfer events. The RSPI HAL module is enabled with data transfer support by incorporating the data transfer controller module of the MCU; this performs SPI transfers through the DTC without requiring interrupt processing for each frame.

RSPI HAL Module Features

• Initialization of the driver
• SPI transfer functions:
  •  Allows serial communication through the SPI operation using the four-wire method
  • Capable of serial communication in master and slave modes
  • Switching the polarity of the serial transfer clock
  • Switching the phase of the serial transfer clock
• Data Format
  • MSB-first/LSB-first selectable
  • Transfer bit length is selectable as 8, 16 and 32 bits
  • 16-bit and 32-bit byte swapping for both received and transmitted data register
• Error Detection
  • Mode fault detection
  • Overrun error detection
  • Parity error detection
• SSL control functions
  • External hardware slave select can be used in master mode
• Interrupts
  • RSPI receive interrupt (receive buffer full)
  • RSPI transmit interrupt (transmit buffer empty)
  • RSPI error interrupt (mode fault, overrun and parity error)
• Delays
  • Add SPI clock delay
  • Add slave select negation delay
  • Add next-access delay

RSPI HAL Module Block Diagram

RSPI Hardware Support Details

The following hardware features are, or are not, supported by SSP for the RSPI.

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	SPI Operation mode	Clock Syn mode	Full-duplex or transmit-only can be selected	Switching of the polarity and phase	Master and Slave mode	MSB first/LSB first selectable
S124	✓	✓	✓	✓	✓	✓
S128	✓	✓	✓	✓	✓	✓
S1JA	✓	✓	✓	✓	✓	✓
S3A1	✓	✓	✓	✓	✓	✓
S3A3	✓	✓	✓	✓	✓	✓
S3A6	✓	✓	✓	✓	✓	✓
S3A7	✓	✓	✓	✓	✓	✓
S5D3	✓	✓	✓	✓	✓	✓
S5D5	✓	✓	✓	✓	✓	✓
S5D9	✓	✓	✓	✓	✓	✓
S7G2	✓	✓	✓	✓	✓	✓

MCU Group	Transfer length - 8/16/32	Up to four frames can be transferred in one round	Bit rate configuration	Double buffer configuration	Error detection	SSL control function
S124	✓	⌧	✓	⌧	✓	✓
S128	✓	⌧	✓	⌧	✓	✓
S1JA	✓	⌧	✓	⌧	✓	✓
S3A1	✓	⌧	✓	⌧	✓	✓
S3A3	✓	⌧	✓	⌧	✓	✓
S3A6	✓	⌧	✓	⌧	✓	✓
S3A7	✓	⌧	✓	⌧	✓	✓
S5D3	✓	⌧	✓	⌧	✓	✓
S5D5	✓	⌧	✓	⌧	✓	✓
S5D9	✓	⌧	✓	⌧	✓	✓
S7G2	✓	⌧	✓	⌧	✓	✓

MCU Group	Transfer of up to eight commands	All Interrupt sources	DTC Support	Event link function through ELC HAL driver	Function for switching between CMOS output and open drain output	Loopback mode
S124	⌧	✓	✓32-bit transfer	⌧	✓	✓
S128	⌧	✓	✓32-bit transfer	⌧	✓	✓
S1JA	⌧	✓	✓32-bit transfer	⌧	✓	✓
S3A1	⌧	✓	✓32-bit transfer	⌧	✓	✓
S3A3	⌧	✓	✓32-bit transfer	⌧	✓	✓
S3A6	⌧	✓	✓32-bit transfer	⌧	✓	✓
S3A7	⌧	✓	✓32-bit transfer	⌧	✓	✓
S5D3	⌧	✓	✓32-bit transfer	⌧	✓	✓
S5D5	⌧	✓	✓32-bit transfer	⌧	✓	✓
S5D9	⌧	✓	✓32-bit transfer	⌧	✓	✓
S7G2	⌧	✓	✓32-bit transfer	⌧	✓	✓

MCU Group	Module Stop Function	Multi-master mode
S124	⌧	⌧
S128	⌧	⌧
S1JA	⌧	⌧
S3A1	⌧	⌧
S3A3	⌧	⌧
S3A6	⌧	⌧
S3A7	⌧	⌧
S5D3	⌧	⌧
S5D5	⌧	⌧
S5D9	⌧	⌧
S7G2	⌧	⌧

RSPI HAL Module APIs Overview

The RSPI HAL module defines API functions for opening, closing, reading, writing and other useful functions.  A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

RSPI HAL Module API Summary

Function Name	Example API Call and Description
.open	g_spi.p_api ->open(g_spi.p_cntl, g_spi.p_cfg); Open a designated SPI device.
.read	g_spi.p_api->read(g_spi.p_ctrl, dst16, length, SPI_BIT_WIDTH_16_BITS); Receive data from SPI device.
.write	g_spi.p_api->write (g_spi.p_ctrl, source, length, SPI_BIT_WIDTH_8_BITS); Transmit data to SPI device
.writeRead	g_spi.p_api ->writeRead (g_spi.p_cntl, &source, &destination, length, SPI_BIT_WIDTH_8_BITS, TX_WAIT_FOREVER); Simultaneously transmits data to an SPI device, while receiving data from an SPI device (full duplex). The writeRead API fetches the mutex object, handles SPI data transmission at SPI HAL layer, and receives data from the SPI HAL layer. The API uses the event flag wait to synchronize to complete the data transfer.
.close	g_spi.p_api->close(g_spi,p_ctrl) Disable the SPI device designated by the control handle and close the RTOS services used by the bus if no devices are connected to the bus. This function removes power to the SPI channel designated by the handle and disables the associated interrupts.
.versionGet	g_spi.p_api ->versionGet (&version); Get the version information of the underlying driver.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	Function completed successfully
SSP_ERR_INVALID_MODE	Invalid mode
SSP_ERR_INVALID_CHANNEL	Invalid channel
SSP_ERR_IN_USE	In-use error
SSP_ERR_INVALID_ARGUMENT	Invalid argument
SSP_ERR_QUEUE_UNAVAILABLE	Queue unavailable
SSP_ERR_INVALID_POINTER	Invalid pointer
SSP_ERR_INTERNAL	Internal error
SSP_ERR_TRANSFER_ABORTED	Transfer aborted
SSP_ERR_MODE_FAULT	Mode fault
SSP_ERR_READ_OVF	Read overflow
SSP_ERR_PARITY	Parity error
SSP_ERR_OVERRUN	Overrun error
SSP_ERR_UNDEF	Unknown error
SSP_ERR_TIMEOUT	Timeout error
SSP_ERR_NOT_OPEN	Device not opened

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

RSPI HAL Module Operational Overview

The RSPI HAL module enables communication with a peripheral device using the SPI communications protocol. After opening the module instance, the module handle is used to perform various transfer operations. The device control handle will be used within the API calls to indicate the specific SPI device with which to communicate.

The Driver allows the application program to:

• Initialize the driver.
• Implement serial communication through SPI operation.

The module also provides support for callbacks. The callback functions are called with the following events spi_event_t

• Transfer aborted
• Transfer complete
• Mode fault
• Error events

The RSPI HAL module supports 8, 16 and 32-bit data transfers. The module supports GPIO pins configured as chip selects. In addition, the SPI peripheral supports dedicated chip select signal, SSL. When the SSL pin is enabled in the SPI peripheral, chip select handling is performed by the hardware.

Clock settings:

The SPI peripheral uses the PCLKA as its clock source. You can set the PCLKA frequency using the clock configurator in e² studio or the CGC Interface at run-time.

Note

For S1 devices the SPI peripheral clock source is PCLKB.

IO Port settings:

To use with the SPI peripheral, the I/O port pin(s) used as output pins must be configured as SPI peripheral pins in the pin configurator. If you are using an external chip select, configure Chip select pin as GPIO output.

Extended configuration:

A number of extended hardware specific configurations are present for SPI Driver.

Note

  All extended hardware specific configuration parameters are set in the extended driver configuration structure spi_on_rspi_cfg_t.

RSPI HAL Module Important Operational Notes and Limitations

RSPI HAL Module Operational Notes

While configuring the RSPI HAL drivers, setting the interrupts to different priority levels could result in improper operation.

The module is enabled with a data transfer support by incorporating the Data Transfer Controller module of the MCU. This performs SPI transfers through the DTC without the intervention of the CPU.

In the application, data transfers over the DTC are used in the same way as normal SPI transfers. To enable DTC transfers, add the DTC module under the RSPI HAL module.

The RSPI HAL module supports 8-, 16-, and 32-bit data transfers in both CPU and DTC-based transfer modes. 16- and 32-bit transfers will be endian swapped.

The RSPI HAL drivers also provide supports swapping oftransmit/receive data in byte units for both 16-bit and 32-bit data transfer (big endian to little endian).This feature is applicable only for S5 series MCUs.

The RSPI HAL module supports run time configuration of 8-, 16- and 32-bit data transfers for both CPU and DTC data transfer modes. The DTC transfer size can be any irrespective of user API bit-width.

Performance Notes

The RSPI HAL module can be configured for several different modes, each with different performance characteristics. DTC transfers take slightly longer to setup than CPU-based transfers due to resetting the DTC, but DTC transfers offer greater performance for transfers larger than 1 frame because no intervention is required from the CPU.

Write operations will configure the module for transmit-only mode, disabling the receive interrupt and ignoring incoming data. CPU-based write operations at high bitrates can result in the transmit ISR being constantly called, blocking other code from running. spi_api_t::writeRead and spi_api_t::read operations will configure the module for full duplex mode.

There is a lower limit of 3 SPI clock cycles between transfers resulting in an effective bitrate slower than configured. At high bitrates, the time between transfers can be longer, especially for CPU-based transfers.

The module will wait for the hardware to enter an idle state when in master mode, or all data to be transmitted or received when in slave mode, before invoking the callback.

RSPI HAL Module Limitations

• When the RSPI HAL module is used in slave mode, either the data must be sampled on the even clock edge (that is, CPHA=1) or the master must de-assert the slave select line between the frames when data is sampled on the odd clock edge (that is, CPHA=0). This is a hardware limitation.
• The S124, S128, and S3A6 do not support SSL Level Keep.
• Once the driver has been opened using the DTC or CPU, all transfers must use the bit width configured by the user.
• 16- and 32-bit transfers will be endian swapped.
• The R_RSPI bit rate value must be a positive integer less than 30 MHz or PCLK/2, whichever is smaller.
• r_rspi data transfers will be incomplete when DMAC is used simultaneously by another module. User callback will occur before the data is completely transferred.
• Refer to the most recent SSP Release Notes for any additional operational limitations for this module. 

Including the RSPI HAL Module in an Application

This section describes how to include the SPI HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the SPI Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the SPI Driver is g_spi0. This name can be changed in the associated Properties window.)

RSPI HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_spi0 SPI Driver on r_rspi	Threads	New Stack> Driver> Connectivity> SPI Driver on r_rspi

When the SPI Driver on r_rspi is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

SPI HAL Module Stack

Configuring the RSPI HAL Module

The SPI HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the RSPI HAL Module on r_rspi

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter error checking.
Name	g_spi0	Module name.
Channel	0	SCI or SPI Channel number to which the device has been connected.
Operating Mode	Master, Slave Default: Master	Configure as a Master or Slave device.
Clock Phase	Data sampling on odd edge, data variation on even edge/Data sampling on even edge, data variation on odd edge Default: Data sampling on odd edge, data variation on even edge	Data sampling on odd or even clock edge. Note: If CPHA is set to 0 in slave mode, slave select should not be fixed at active state and burst transfer should not be performed.
Clock Polarity	Low when idle, High when idle Default: Low when idle	Clock level when idle.
Mode Fault Error	Enable, Disable Default: Disable	Indicates Mode fault error (master/slave conflict) flag.
Bit Order	MSB First, LSB First Default: MSB First	Select transmit order MSB/LSB first
Bitrate	500000	Transmission or reception rate. Bits per second.
Callback	NULL	Optional Callback function pointer.
SPI Mode	SPI Operation, Clock synchronous operation Default: SPI Operation	Select spi or clock syn mode operation.
SPI Communication Mode	Full Duplex, Transmit Only Default: Full Duplex	Select full-duplex or transmit-only communication.
Slave Select Polarity(SSL)	Active Low, Active High Default: Active Low	Select SSL signal polarity.
Select Loopback1	Normal, Inverted Default: Normal	Select loopback1.
Select Loopback2	Normal, Inverted Default: Normal	Select loopback2.
Enable MOSI Idle State	Enable, Disable Default: Disable	Select MOSI idle fixed value and selection.
MOSI Ildle State	MOSI Low, MOSI High Default: MOSI Low	Select mosi idle fixed value and selection.
Enable Parity	Enable, Disable Default: Disable	Enable/disable parity.
Parity Mode	Parity Odd, Parity Even Default: Parity Odd	Select parity.
Select SSL Level After Transfer	SSL Level Keep, SSL Level Do Not Keep Default: SSL Level Do Not Keep	Select SSL level after transfer completion; 0-negate; 1-keep. Note: If CPHA = 0 in slave mode, slave select level after transfer should not be set to SSL level Keep.
Clock Delay Enable	Clock Delay Enable, Clock Delay Disable Default: Clock Delay Disable	Clock delay enable selection.
Clock Delay Count	Clock Delay 1 thru 8 RSPCK Default: Clock Delay 1 RSPCK	Clock delay count selection.
SSL Negation Delay Enable	Negation Delay Enable, Negation Delay Disable Default: Negation Delay Disable	SSL negation delay enable selection.
Negation Delay Count	Negation Delay 1 thru 8 RSPCK Default: Negation Delay 1 RSPCK	Negation delay count selection.
Next Access Delay Enable	Next Access Delay Enable, Next Access Delay Disable Default: Next Access Delay Disable	Next access delay enable selection.
Next Access Delay Count	Next Access Delay 1 thru 8 RSPCK Default: Next Access Delay 1 RSPCK	Next access delay count selection.
Receive Interrupt Priority	Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX) Default: Priority 2	Receive interrupt priority selection.
Transmit Interrupt Priority	Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX) Default: Priority 2	Transmit interrupt priority selection.
Transmit End Interrupt Priority	Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX) Default: Priority 2	Transmit end interrupt priority selection.
Error Interrupt Priority	Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX) Default: Priority 2	Error interrupt priority selection.
Byte Swap(Only for S5 series MCUs)Disable	Enable, Disable Default: Disable	Enable byte swapping (applicable only for S5 series MCUs).

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

  RSPI driven slave select currently supports SSL0 only.

Configuration Settings for the SPI HAL Module Lower Level Modules

Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module:

Configuration Settings for the Transfer Driver on r_dtc Event SPI0 TXI

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if code for parameter checking is to be included in the build.
Software Start	Enabled, Disabled Default: Disabled	Software start selection.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Linker section to keep DTC vector table selection.
Name	g_transfer0	Module name.
Mode	Normal	Mode selection.
Transfer Size	1 Byte, 2 Bytes, 4 Bytes Default: 2 Bytes	Transfer size selection.
Destination Address Mode	Fixed	Destination address mode selection.
Source Address Mode	Incremented	Source address mode selection.
Repeat Area (Unused in Normal Mode	Source	Repeat area selection.
Interrupt Frequency	After all transfers have completed
Destination Pointer	NULL	Destination pointer selection.
Source Pointer	NULL	Source pointer selection.
Number of Transfers	0	Number of transfers selection.
Number of Blocks (Valid only in Block Mode)	0	Number of blocks selection.
Activation Source (Must enable IRQ)	Event SPI0 TXI	Activation source selection.
Auto Enable	False	Auto enable selection.
Callback (Only valid with Software start)	NULL	Callback selection.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX) Default: Disabled	ELC Software Event interrupt priority selection.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Transfer Driver on r_dtc Event SPI0 RXI

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if code for parameter checking is to be included in the build.
Software Start	Enabled, Disabled Default: Disabled	Software start selection.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Linker section to keep DTC vector table selection.
Name	g_transfer1	Module name.
Mode	Normal	Mode selection.
Transfer Size	1 Byte, 2 Bytes, 4 Bytes Default: 2 Bytes	Transfer size selection.
Destination Address Mode	Incremented	Destination address mode selection.
Source Address Mode	Fixed	Source address mode selection.
Repeat Area (Unused in Normal Mode	Destination	Repeat area selection.
Interrupt Frequency	After all transfers have completed	Interrupt frequency selection.
Destination Pointer	NULL	Destination pointer selection.
Source Pointer	NULL	Source pointer selection.
Number of Transfers	0	Number of transfers selection.
Number of Blocks (Valid only in Block Mode)	0	Number of blocks selection.
Activation Source (Must enable IRQ)	Event SPI0 RXI	Activation source selection.
Auto Enable	FALSE	Auto enable selection.
Callback (Only valid with Software start)	NULL	Callback selection.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX) Default: Disabled	ELC Software Event interrupt priority selection.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

RSPI HAL Module Clock Configuration

The SPI peripheral is clocked via Peripheral Clock A (PCLKA). The clock frequencies are configurable in the ISDE by using the Clocks Tab in the configurator. Invalid selections are indicated in red when selected. Ensure that desired SPI bitrate can be achieved with the stated value of PCLKA. The ISDE will not be indicated if the specified bitrate is not achievable.  At run time, the SPI driver will attempt to configure the SPI peripheral to the correct bitrate and will return an error if the desired bitrate cannot be set.  The bitrate is calculated via the equations in the table below. If the result of the equation (n) is in the range of 0 to 255, then the bit rate can be achieved.

Baud Rate Calculation Equations

SPI HAL	Bitrate calculation	Description
SPI on SPI		n = Peripheral register value.         This has to be in the range of 0 to 255 PLCKA = value of PLCKA in MHz N = 0, 1, 2 or 3 B = Desired Bit Rate

RSPI HAL Module Pin Configuration

The SPI peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example listing a selection for SPI pins:

Note

The operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection Sequence for SPI HAL Module on r_riic

Resource	ISDE Tab	Pin selection Sequence
RSPI	Pins	Select Peripherals> RSPI> SPI0_Pin_Option_A/B.

Note

The selection sequence assumes SPI0 is the desired hardware target for the driver.

Pin Configuration Settings for the SPI HAL Module on r_sci_uart

Pin Configuration Property	Value	Description
Operation Mode	Disabled, Custom, Enabled Default: Disabled	Select Enabled for SPI Operation.
MISO	None, P100, P410 Default: None	MISO Pin selection.
MOSI	None, P101, P411 Default: None	MOSI Pin selection.
RSPCLK	None, P102, P412 Default: None	RSPCLK Pin selection.
SSL0:3	None, P103:106, P413:415 Default: None	SSL0:3 Pin selections.

Note

The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy Kits and other Synergy MCUs may have different available pin configuration settings.

Using the SPI HAL Module in an Application

The steps in using the SPI HAL module in a typical application are:

Note

The spi_api_t::open API must be called first, but the rest of the calls may be used in any order depending on the application requirements.

1. Initialize the module using the spi_api_t::open API.
2. Write to a slave device by using the spi_api_t::write API.
3. Read from a slave device using the spi_api_t::read API.
4. Close the module by calling the spi_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical SPI HAL Module Application