SPI Framework Introduction
- SPI Framework Module Features
SPI Framework Module APIs Overview
SPI Framework Module Operational Overview
- SPI Framework Module Important Operational Notes and Limitations
  - SPI Framework Module Operational Notes
  - SPI Framework Module Limitations
Including the SPI Framework Module in an Application
Configuring the SPI Framework Module
Using the SPI Framework Module in an Application

SPI Framework Introduction

The SPI Framework module provides a ThreadX-aware framework API and handles the integration and synchronization of multiple SPI peripherals on an SPI bus (including chip-select handling and its level activation). With the SPI Framework, one or more SPI buses can be created and multiple SPI peripherals can be connected to the SPI bus. The SPI Framework module uses a single interface to access both SCI SPI and RSPI drivers. The SPI Framework module uses the SCI and RSPI peripherals on the Synergy MCU.

SPI Framework Module Features

The SPI Framework module uses either the SCI in SPI mode (together with the SCI common lower-level modules) or the RSPI lower-level driver module to communicate with the SPI peripherals on the Synergy microcontroller.

Supports multiple devices on a bus
Provides high-level APIs for initialization, transfers and closing the module
Supports synchronized transfers
Supports chip-select operations
Supports bus-locking

SPI Framework Module Block Diagram

SPI Framework Module APIs Overview

The SPI Framework module defines APIs 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.

SPI Framework Module API Summary

Function Name	Example API Call and Description
open	`g_sf_spi_device.p_api->open(g_sf_spi_device.p_ctrl, g_sf_spi_device.p_cfg);` Open a designated SPI device on a bus.
read	`g_sf_spi_device.p_api->read(g_sf_spi_device.p_ctrl, &destination, length, SPI_BIT_WIDTH_8_BITS, timeout);` Receive data from SPI device.
write	`g_sf_spi_device.p_api->write(g_sf_spi_device.p_ctrl, &source, length, SPI_BIT_WIDTH_8_BITS, timeout);` Transmit data to SPI device.
writeRead	`g_sf_spi_device.p_api->writeRead (g_sf_spi_device.p_ctrl, &source, &destination, length, SPI_BIT_WIDTH_8_BITS, timeout);` Simultaneously transmits data to an SPI device while receiving data from an SPI device (full duplex). The writeread API gets a mutex object, handles the 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 completion of data transfer.
close	`g_sf_spi_device.p_api->close(g_sf_spi_device.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.
lock	`g_sf_spi_device.p_api->lock(g_sf_spi_device.p_ctrl);` Lock the bus for a device. The locking allows devices to reserve a bus to themselves for a given period of time (such as between lock and unlock). This allows devices to complete several reads and writes on the bus without an interrupt.
unlock	`g_sf_spi_device.p_api->unlock(g_sf_spi_device.p_ctrl);` Unlock the bus for a particular device and make the bus usable for other devices.
version	`g_sf_spi_device.p_api->version (&version);` Retrieve the API version with the version pointer.
lockWait	`g_sf_spi_device.p_api->lockWait(g_sf_spi_device.p_ctrl, timeout);` Lock the bus for a device. The locking allows devices to reserve a bus to themselves for a given period of time (i.e. between lock and unlock). This allows devices to complete several reads and writes on the bus without interrupt. The wait option allows thread to wait for the specified timeout when acquiring the bus mutex.

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.
SSP_ERR_ALREADY_OPEN	Requested channel is already open in a different configuration.

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.

SPI Framework Module Operational Overview

The SPI Framework module complies with the layered-driver architecture of the SSP. It uses either the SCI on SPI module or the RSPI module to communicate with the SPI peripherals on the Synergy microcontroller.

Multiple Slave Devices on the Same Bus

The SPI framework module uses a bus and device on bus architecture. Only one device is configured to the lower level driver at a time, and the other devices are reconfigured upon a read or write operation as required. The lower level driver can only be reconfigured when the bus is not locked. Every slave device is linked to the bus to which it will be connected and shares the bus with all other slave devices.

The user must configure the SPI framework shared-bus and the lower-level SPI HAL layer for each SPI framework module connecting to the bus. The user can add the existing framework shared-bus module when configuring multiple devices on the same bus. Each SPI framework module must be configured with a unique name in the ISDE configurator.

A common start and stop procedure is used for all SPI data-transfer operations (spi_api_t::read, spi_api_t::write and spi_api_t::writeRead). During the start process, the SPI framework module checks whether reconfiguration is required. Chip select is asserted during the transfer-start process and de-asserted during the transfer-end process if the bus is not locked. The user must configure the chip-select IO pin and the chip-select active level.

Bus Locking

The SPI Framework module supports bus-locking functionality, meaning that the bus can be locked for a given slave peripheral. The locking allows slave devices to reserve a bus to themselves for the period between the lock and unlock commands. This allows devices to complete several reads and writes on the bus without interruption (which can be required in some situations). The chip select becomes active during lock and becomes inactive when unlocked. Writes and reads in between the lock and unlock do not alter the chip-select line.

SPI Framework Module Important Operational Notes and Limitations

SPI Framework Module Operational Notes

Multiple SPI devices can be configured to share a common bus. Once the SPI Framework bus module is configured, different SPI peripherals (devices) can be connected to that bus.
For each SPI device connected to the bus, one SPI HAL module (new or shared) and one SPI Framework device module must be added.
User defined Callback is not required as it has been internally taken care by framework.
Setting the interrupts to different priority levels could result in improper operation.
In the SPI Framework configuration, the channel number given to this bus overrides the channel number given in the HAL module.
Shared bus can be used by multiple slave devices with the respective configuration. The framework also handles mutual exclusion in lock and unlock APIs when multiple devices are using the same SPI channel.
Lock functionality will be effective for devices from different threads. If multiple devices connected to the bus are from the same thread, the SPI bus will be locked for all devices from that thread. In such cases, even if the bus is locked, all devices from the same thread can access the bus.
In case a device used from multiple threads, and the device locks the SPI bus from one thread, the same device cannot access the SPI bus from other threads.
The behavior of chip-select pin depends on the slave device. Chip-select pin can be utilized through framework or user can handle Chip-select pin in their application code based on the hardware specification of particular slave device.

SPI Framework Module Limitations

Refer to the MCU specification manual for identifying SPI bus compatibility. Device compatibility with the SPI bus is not checked in the framework hence incompatible SPI device may result in improper operation.
Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the SPI Framework Module in an Application

This section describes how to include the SPI Framework 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 Framework module to an application, simply add it to a HAL /Common thread using the stacks selection sequence given in the following table. (The default name for the SPI Framework module is g_sf_spi_device0. This name can be changed in the associated Properties window.)

SPI Framework Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_sf_spi_device0 on sf_spi	Threads	New Stack> Framework> Connectivity> SPI Framework Device on sf_spi

When the SPI Framework module on sf_spi 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 Framework Module Stack

Configuring the SPI Framework Module

The SPI Framework module must be configured by the user for the desired operation. The SSP configuration window will automatically identify (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules in order to ensure successful operation. Furthermore, only those properties that can be changed without causing conflicts are available for modification. Other properties are 'locked' and are 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 the SSP.

Configuration Settings for the SPI Framework Device Module on sf_ spi

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if code for parameter checking is to be included in the build.
Name	g_sf_spi_device0	Module name.
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	Select the clock phase.
Clock Polarity	Low when idle, High when idle Default: Low when idle	Select the clock polarity.
Chip Select Port	00 thru 11 Default: 00	Select GPIO port used for the chip select.
Chip Select Pin	00 thru 15 Default: 00	Select GPIO pin used for the chip select.
Chip Select Active Level	Low, High Default: Low	Polarity of the Chip Select signal, active High or Low.

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

In some cases, settings other than the defaults can be desirable. For example, it might be useful to select different chip-select GPIOs or levels. The configurable properties for the lower-level stack modules are given in the following sections for completeness and as a reference.

Note: Most of the property settings for lower level modules are fairly intuitive and can usually be determined by inspection of the associated Properties window from the SSP configurator.

Configuring the SPI Framework Lower-Level Modules

Typically, only a small number of settings must be modified from the default for lower-level drivers as indicated with 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 lower-level modules:

Configuration Settings for the SPI Framework Shared Bus on sf_spi

ISDE Property	Value	Description
Name	g_sf_spi_bus0	Module name.

Note: The example values 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 RSPI HAL Driver on r_rspi

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	If selected code for parameter checking is included in the build.
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. Note: Current version of SSP supports only SPI Master mode.
Clock Phase	Data sampling on odd edge, data variation on even edge	Data sampling on odd or even clock edge.
Clock Polarity	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.
Slave Select Polarity(SSL0)	Active Low, Active High Default: Active Low	Select SSL0 signal polarity.
Slave Select Polarity(SSL1)	Active Low, Active High Default: Active Low	Select SSL1 signal polarity.
Slave Select Polarity(SSL2)	Active Low, Active High Default: Active Low	Select SSL2 signal polarity.
Slave Select Polarity(SSL3)	Active Low, Active High Default: Active Low	Select SSL3 signal polarity.
Select Loopback1	Normal, Inverted Default: Normal	Select the data mode for loopback 1.
Select Loopback2	Normal, Inverted Default: Normal	Select the data mode for loopback 2.
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(Slave Select)	SSL0, SSL1, SSL2, SSL3 Default: SSL0	Select which slave to use; 0-SSL0; 1-SSL1; 2-SSL2; 3-SSL3.
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.
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:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Receive interrupt priority selection.
Transmit Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Transmit interrupt priority selection.
Transmit End Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Transmit interrupt priority selection.
Error Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Error interrupt priority selection.

Note: The example values 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 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	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	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 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:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	ELC Software Event interrupt priority selection.

Note: The example values 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.
Name	g_transfer1	Module name.
Mode	Normal	Mode selection.
Transfer Size	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:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	ELC Software Event interrupt priority selection.

Note: The example values 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 SPI Driver on r_sci_spi

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. Note: Current version of SSP supports only SPI Master mode.
Clock Phase	Data sampling on odd edge, data variation on even edge	Data sampling on odd or even clock edge.
Clock Polarity	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	100000	Transmission or reception rate. Bits per second.
Bit Rate Modulation Enable	Enable, Disable Default: Enable	Bitrate Modulation Function enable or disable.
Callback	NULL	Optional Call back function pointer.
Receive Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Bitrate Modulation Function enable or disable. Note: This is applicable only for SCI SPI.
Transmit Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Transmit interrupt priority selection.
Transmit End Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Transmit end interrupt priority selection.
Error Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Error interrupt priority selection.

Note: The example values 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 SCI0 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	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	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 SCI0 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:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	ELC Software Event interrupt priority selection.

Note: The example values 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 SCI0 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	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 SCI0 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:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	ELC Software Event interrupt priority selection.

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

SPI Framework Module Clock Configuration

The SCI peripheral module uses the PCLKB as its clock source. The PCLKB frequency is set by using the SSP configurator Clock tab prior to a build or by using the CGC Interface at run-time.

SPI Framework 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 selection for the pins.

Note: For some peripherals, the operation-mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection Sequence for the SPI Framework Module

Resource	ISDE Tab	Pin selection Sequence
SCI	Pins	Select Peripherals> Connectivity: SCI> SCI1
RSPI	Pins	Select Peripherals> Connectivity: SPI> SPI0

Note: The selection sequences assume SCI1 and SPI0 are the desired hardware targets of the drivers.

Pin Configuration Settings for the SPI Framework Module

Pin Configuration Property	Value	Description
Operation Mode	Disabled, Asynchronous UART, Synchronous UART, Simple I2C, Simple SPI, SmartCard Default: Disabled	Select Simple SPI as the Operation Mode for SPI on SCI.
CTS0_RTS0_SS0	None, P103, P413 Default: None	SS0 pin selection.
RXD0_SCL0_MISO0	None, P100, P410 Default: None	MISO0 pin selection.
SCK0	None, P102, P412 Default: None	SCK0 pin selection.
TXD1_SDA1_MOSI0	None, P213, P709 Default: None	MOSI0 pin selection.

Note: The example values 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.

SPI Framework Module Additional Settings

If external chip selects are being used, configure the chip select pins as GPIO outputs.

Using the SPI Framework Module in an Application

A common application for the SPI framework module requires multiple slave devices on a single bus. The implementation for this common application is described below. A second implementation shows two buses each with two slave devices attached.

Implementation Steps for Two Slave Devices on a Single Shared Bus

When using the SPI framework module to create a single bus with multiple slave devices create two thread stacks each with an SPI framework instance. These instances will use the same shared bus instance. Follow the steps below to see how this is done within the SSP Configurator.

Note: The following steps assume some familiarity with the use of the SSP development environment. If any of the following steps are confusing, read over the first few chapters of the SSP User's Manual to become familiar with the SSP development environment.

Step 1: Add the first SPI framework device module to a new or existing thread. This creates the SPI master stack. A shared bus on sf_spi is added along with the SPI driver. The SPI driver can be selected for implementation on r_rspi or r_sci_spi. The DTC transfer driver is also added by default. This can be removed if the CPU transfer mode is needed instead.

The resulting module stack is shown in the following figure. Example configuration settings are given in the tables that follow the figure.

SPI Framework Module Stack 1

Example configuration settings for the key first thread stack modules for Slave Device #1 are as follows:

Configuration Settings for the SPI Framework Module on sf_spi

Property	Value	Description
Parameter Checking	Disabled	Enable or Disable Parameter Checking.
Name	g_sf_spi_device1	Give a name to identify the SPI Framework device. API, Config and Control instances will be created based on this name.
Clock Phase	Data sampling on odd edge	Specify the clock phase for data variation and data sampling
Clock Polarity	Low when idle	Select the clock polarity when clock is idle.
Clock Select Port	01	Select GPIO port used for the chip select.
Chip Select Pin	04	Select GPIO pin used for the chip select.
Chip Select Active Level	Low	Select Polarity of the chip select signal.

Configuration Settings for the SPI Framework Shared Bus on sf_spi

Property	Value	Description
Name	g_sf_spi_bus0	Give a name to identify the SPI Framework shared bus. This shared bus will be shared by multiple SPI Framework Devices.

Configuration Settings for the SPI Driver on r_rspi

Property	Value	Description
Parameter Checking	BSP	Enable or Disable Parameter Checking.
Name	g_spi0	Give a name to identify the SPI Driver device. This will be used by Framework internally.
Channel	0	Channel number.
Operating Mode	Master	Operating mode selection.
Clock Phase	Data sampling on odd edge/ data variation on edge	Clock phase selection. This field will be locked as these is already set in the SPI Framework Device on sf_spi module.
Clock Polarity	Low when idle	Clock polarity selection. This field will be locked as these is already set in the SPI Framework Device on sf_spi module.
Mode Fault Error	Enable	Mode fault error selection.
Bit Order	MSB First	Bit order selection.
Bitrate	500000	Bit rate selection.
Callback	NULL	Callback function name.
SPI Mode	SPI Operation	SPI mode selection.
SPI Communication Mode	Full Duplex	SPI communication mode selection.
Slave Select Polarity (SSL0)	Active Low	Slave select polarity selection 0.
Slave Select Polarity (SSL1)	Active Low	Slave select polarity selection 1.
Slave Select Polarity (SSL2)	Active Low	Slave select polarity selection 2.
Slave Select Polarity (SSL3)	Active Low	Slave select polarity selection 3.
Select Loopback 1	Normal	Loopback 1 selection.
Select Loopback 2	Normal	Loopback 2 selection.
Enable MOSI Idle	Disable	Enable MOSI idle selection.
MOSI Idle State	MOSI Low	Enable MOSI idle state selection.
Enable Parity	Disable	Enable parity selection.
Parity Mode	Parity Odd	Enable parity mode selection.
Select SSL (Slave Select)	SSL0	Select SSL selection.
Select SSL Level After Transfer	SSL Level Keep	Select SSL level after transfer selection.
Clock Delay Enable	Disable	Clock delay enable selection.
Clock Delay Count	Clock Delay 1 RSPCK	Clock delay count selection.
SSL Negation Delay Enable	Disable	SSL Negation Delay Enable selection.
Negation Delay Count	Clock Delay 1 RSPCK	Negation Delay Count selection.
Next Access Delay Enable	Disable	Next Access Delay Enable selection.
Next Access Delay Count	Clock Delay 1 RSPCK	Next Access Delay Count selection.
Receive Interrupt Priority	Priority 2	Receive interrupt priority selection.
Transmit Interrupt Priority	Priority 2	Transmit interrupt priority selection.
Transmit End Interrupt Priority	Priority 2	Transmit end interrupt priority selection.

Configuration Settings for the SPI Driver on r_sci_spi

Property	Value	Description
Parameter Checking	BSP	Enable or Disable Parameter Checking.
Name	g_spi0	Give a name to identify the SPI Driver device. This will be used by Framework internally.
Channel	0	Channel number.
Operating Mode	Master	Operating mode selection.
Clock Phase	Data sampling on odd edge/ data variation on even edge	Clock phase selection. This field will be locked as these is already set in the SPI Framework Device on sf_spi module.
Clock Polarity	Standard	Clock polarity selection. This field will be locked as these is already set in the SPI Framework Device on sf_spi module.
Mode Fault Error	Disable	Mode fault error selection.
Bit Order	MSB First	Bit order selection.
Bitrate	500000	Bit rate selection.
Bit Rate Modulation Enable	Enable	Enables/Disable the bit rate modulation.
Callback	NULL	Callback function name. This field will be locked as callback is handled internally in the framework.
Receive Interrupt Priority	Priority 2	Receive interrupt priority selection.
Transmit Interrupt Priority	Priority 2	Transmit interrupt priority selection.
Transmit End Interrupt Priority	Priority 2	Transmit end interrupt priority selection.
Error Interrupt Priority	Priority 2	Error interrupt priority selection.

Note: DTC configuration settings are not shown as a simplification.

Step 2: Add the second SPI Framework Device to a different thread. The SPI Framework Shared Bus on sf_spi is not added automatically. To add it, select the option to use the existing shared bus. The configurator will then automatically add the SPI Framework Shared Bus on sf_spi and the remaining modules. The lower level modules will automatically be configured to be consistent with the previously defined settings from the first SPI framework instance. This ensures that the SPI driver configurations are the same for both devices except for the Clock Phase, Clock Polarity, Chip Select Pin and Port, and Chip Select Active Level properties, as these are defined under the SPI Framework Device module and can be different for each slave device.

The resulting module stack is shown in the following figure:

SPI Framework Module Stack 2

The only differences in the configuration parameters for the second stack are the name for the second SPI framework device module, and any differences in the non-shared slave settings (Clock Phase, Clock Polarity, Clock Select Port, Chip Select Pin and Chip Select Active Level). Example settings are shown in the following table:

Configuration Settings for the SPI Framework Device on sf_spi (Slave #2)

Property	Value	Description
Parameter Checking	BSP	Enable or Disable Parameter Checking.
Name	g_sf_spi_device2	Give a name to identify the SPI Framework device. API, Config and Control instances will be created based on this name.
Clock Phase	Data sampling on odd edge/ data variation on even edge	Specify the clock phase for data variation and data sampling
Clock Polarity	High when idle	Select the clock polarity when clock is idle.
Clock Select Port	05	Select GPIO port used for the chip select.
Chip Select Pin	01	Select GPIO pin used for the chip select.
Chip Select Active Level	Low	Select Polarity of the chip select signal.

Implementation Steps for Two Slave Devices on Two Shared Buses

When using the SPI framework module to create a single bus with multiple slave devices create two thread stacks each with an SPI framework instance. These instances will use the same shared bus instance. Follow the steps below to see how this is done within the SSP Configurator.

Note: The following steps assume some familiarity with the use of the SSP development environment. If any of the following steps are confusing, read over the first few chapters of the SSP User's Manual to become familiar with the SSP development environment.

Adding Another Shared Bus

To add another shared bus, just follow the below steps. The previous example is used as the starting point.

Step 3: The SPI framework module which will use a second shared bus can be added to any thread. Starting with the previous example, if it is added to the SPI_Device1 thread, then the module stack would appear as shown below. Available options for the shared bus are New or Use.

SPI Framework Module Stack 3

Step 4: Select New to and add another SPI Framework Shared Bus on sf_spi module. Configure the shared bus properties as needed for the application. Select the desired low-level SPI driver. The channel number for the g_spi1 SPI driver module, must be different from the channel number for the g_spi0 SPI driver module. The resulting thread stack is shown below:

SPI Framework Module Stack 4

Step 5: A second device can be added in the SPI_Device2 thread using the same steps described above. The resulting thread stack is shown below:

SPI Framework Module Stack 5

The typical steps in using the SPI Framework module in an application are:

Initialize the SPI Framework device module using the sf_spi_api_t::open API function. Each SPI framework device module needs to call the spi_api_t::open API function at least once before performing any operations on the bus.
Lock the bus for continuous transfer using the sf_spi_api_t::lock or sf_spi_api_t::lockWait API function for a particular SPI Framework device module. Once the bus is locked by a particular SPI Framework device module, it cannot be used by any other SPI Framework device module on the bus. This ensures that ownership of the bus remains with the locked module until it explicitly unlocks it. Any kind of operation from other SPI Framework device modules on the bus will return a fail status during this period. It is not mandatory to lock the bus before any read/write operations on the bus. It is optional.
Read data using the sf_spi_api_t::read API function. The read operation will not be successful if the bus is already locked by any other SPI Framework device module.
Write data using the sf_spi_api_t::write API function. The write operation will not be successful if the bus is already locked by any other SPI Framework device module.
Write and read data simultaneously using the sf_spi_api_t::writeRead API function. The simultaneous read and write operation will not be successful if the bus is already locked by any other SPI Framework device module.
Unlock the bus from continuous transfer using the sf_spi_api_t::unlock API function if it is already locked by the same device. Once the bus is unlocked, other SPI Framework device modules can use it. It is necessary to unlock the locked bus after the intended read/write operation is completed.
Close the SPI Framework device module using the sf_spi_api_t::close API function. Each SPI Framework device module can call the sf_spi_api_t::close API function after all read/write operations on the bus are over.

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

Flow Diagram of a Typical SPI Framework Module Application

Table of Contents