SCI SPI HAL Module Introduction
- SCI SPI HAL Module Features
- SCI SPI Hardware Support Details
SCI SPI HAL Module APIs Overview
SCI SPI HAL Module Operational Overview
- SCI SPI HAL Module Important Operational Notes and Limitations
  - SCI SPI HAL Module Operational Notes
  - SCI SPI HAL Module Limitations
Including the SCI SPI HAL Module in an Application
Configuring the SCI SPI HAL Module
Using the SCI SPI HAL Module in an Application

SCI SPI HAL Module Introduction

The SCI SPI HAL module provides a high-level API for master/slave-based industry standard SPI serial communications and configures and uses the SCI (Serial Communications Interface) peripheral on a Synergy MCU. A user-defined callback can be created to signal when the SPI has transmitted data, aborted a data transfer or detected an error condition.

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

SCI SPI HAL Module Features

The SCI SPI HAL module supports the configuration and control of the SPI functions on the Synergy MCU. Key features include the following:

Driver initialization
Serial communication through SPI operation using 8-bit data transfers
Configurable among four clock phase and clock polarity settings
Support for callbacks. The callback functions are called with the following events:
- Transfer aborted
- Transfer complete
- Over run error
- SPI communication in master and slave mode.

SCI SPI HAL Module Block Diagram

SCI SPI Hardware Support Details

The following hardware features are, or are not, supported by SSP for the SCI_SPI:

Legend:

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

MCU Group	Master Out/Slave In (MOSI)	Master In/Slave Out (MISO)	SSL Slave Select	SPI Operation (4-wire method)	Clock Synchronous Operation (3-wire method)	Full Duplex or Transmit Only selectable
S124	✓	✓	GPIO	N/A	✓	✓
S128	✓	✓	GPIO	N/A	✓	✓
S1JA	✓	✓	GPIO	N/A	✓	✓
S3A1	✓	✓	GPIO	N/A	✓	✓
S3A3	✓	✓	GPIO	N/A	✓	✓
S3A6	✓	✓	GPIO	N/A	✓	✓
S3A7	✓	✓	GPIO	N/A	✓	✓
S5D3	✓	✓	GPIO	N/A	✓	✓
S5D5	✓	✓	GPIO	N/A	✓	✓
S5D9	✓	✓	GPIO	N/A	✓	✓
S7G2	✓	✓	GPIO	N/A	✓	✓

MCU Group	Overrun error detection	Data format transfer bit length	Master or Slave	Clock source Internal/external	Configurable phase and polarity	Interrupt sources support
S124	✓	8-bit	✓	Internal	✓	✓
S128	✓	8-bit	✓	Internal	✓	✓
S1JA	✓	8-bit	✓	Internal	✓	✓
S3A1	✓	8-bit	✓	Internal	✓	✓
S3A3	✓	8-bit	✓	Internal	✓	✓
S3A6	✓	8-bit	✓	Internal	✓	✓
S3A7	✓	8-bit	✓	Internal	✓	✓
S5D3	✓	8-bit	✓	Internal	✓	✓
S5D5	✓	8-bit	✓	Internal	✓	✓
S5D9	✓	8-bit	✓	Internal	✓	✓
S7G2	✓	8-bit	✓	Internal	✓	✓

SCI SPI HAL Module APIs Overview

The SPI defines APIs for opening and closing the SCI peripheral and transmitting and receiving data. 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.

SCI SPI 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	API Call Successful.
SSP_ERR_IN_USE	Attempted to open an already open device instance OR Another transfer was in progress.
SSP_ERR_INVALID_POINTER	p_version is NULL.
SSP_INVALID_ARGUMENT	Channel number invalid.
SSP_ERR_HW_LOCKED	The lock could not be acquired. The channel is busy.
SSP_ERR_CH_NOT_OPEN	The channel has not been opened. Open channel first.

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.

SCI SPI HAL Module Operational Overview

The SCI SPI HAL module provides the ability to configure and use the SPI capabilities of the Synergy MCU. The SCI SPI HAL module enables communication with a peripheral device using the SPI communications protocol. After opening the SCI SPI HAL module instance, the SCI SPI module handle is used to perform various transfer operations. The device control handle will be used within the API calls to indicate the specific SCI SPI device to communicate with.

The SCI SPI HAL module allows the user to:

Initialize the module.
Serial Communication through SPI operation. Read from and write to (and simultaneous read/write – full duplex) a SPI device – performed by calling the spi_api_t::read, spi_api_t::write and spi_api_t::writeRead APIs.

The Driver also provides support for callbacks. The callback functions are called with the following events:

Transfer aborted
Transfer complete
Overrun error

The SCI SPI module supports only 8-bit data transfer operations. The SCI SPI module uses GPIO pins configured as chip selects.

Clock Settings

The SCI SPI uses 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.

I/O Port Settings

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

SCI SPI Interrupts

To enable the interrupts of the SCI SPI, highlight the driver module and set the priority of the SCI RXI, TXI, TEI and ERI interrupts on the Threads tab of the Project Configurator in e² studio: Configuring Interrupts.

This sets the corresponding interrupts in ssp_cfg/bsp/bsp_irq_cfg.h to the priority level selected.

Note: Setting the interrupts to different priority levels could result in improper operation.

SCI SPI HAL Module Important Operational Notes and Limitations

SCI SPI HAL Module Operational Notes

Chip select outputs are supported using GPIOs
The SCI SPI HAL module uses only 8-bit data transfers.
Setting the interrupts to different priority levels could result in improper operation.
The SCI SPI HAL module is enabled with a data transfer support by incorporating the Data Transfer Controller module of the MCU. This performs an SPI transfer through the DTC without intervention of the CPU. The DTC transfer is enabled by default; the user has to remove it from the configurator for an IRQ mode transfer.

SCI SPI HAL Module Limitations

Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the SCI SPI 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.)

SCI SPI HAL Module Selection Sequence

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

When the SPI Driver on r_sci_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 HAL Module Stack

Configuring the SCI SPI 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 SCI SPI HAL Module 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.
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.
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	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: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.

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 SCI 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 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 seleciton.
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: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 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: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.

SCI SPI HAL Module Clock Configuration

The SCI peripheral is clocked via the 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 HAL module will attempt to configure the SCI peripherals 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 following table. 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 SCI		N = Peripheral register value. This must be in the range of 0 to 255 PLCKA = value of PLCKA in MHz n = 0, 1, 2 or 3 M = Bit Rate Modulation Index 128 < M < 256 If the Bit Rate Modulation is disabled, then M=256 B = Desired Bit Rate

SCI SPI HAL Module Pin Configuration

The SCI peripheral use 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 SPI pins:

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

Pin Selection Sequence for SCI SPI HAL Module on r_sci_spi

Resource	ISDE Tab	Pin Selection Sequence
SPI on SCI	Pins	Select Peripherals> Connectivity:SCI> SCIx, where x is the required SCI peripheral channel.

Note: The selection sequence assumes SCI0 is the desired hardware target for the driver.

Pin Configuration Settings for the SCI SPI HAL Module on r_sci_spi

Pin Configuration Property	Value	Description
Pin Group Selection	Mixed, _A only, _B only	Synergy devices support peripheral functionality via multiple pins location, identified by _A, _B. Selecting Mixed allows the user to select any combination of locations (_A and _B). Selecting _A allows the user to select only _A locations. Selecting _B allows the user to select only _B locations.
Operation Mode	Disabled Custom Asynchronous UART Simple SPI Simple I2C Synchronous UART Smart Card	Set the operating mode to: Simple SPI.
TXD_MOSI	None, P411, P101	Specify the port pin to be used as MOSI.
RXD_MISO	None, P410, P100	Specify the port pin to be used as MISO.
SCK	None, P412, P102	Specify the port pin to be used as CLK.
CTS_RTS_SS	None, P413, P103	Specify the port pin to be used as SS.

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 SCI SPI HAL Module in an Application

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

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

Initialize an SPI instance using the spi_api_t::open API function. (g_spi.p_api->open (g_spi.p_ctrl, g_spi.p_cfg) where p_ctrl and p_cfg are the instances of control and configuration structures autogenerated after the configuration step).
Initiate a write to a slave device using the spi_api_t::write API function. (g_spi.p_api->write (g_spi.p_ctrl, source, length, SPI_BIT_WIDTH_8_BITS); where g_spi.p_ctrl is the same control instance that was used in the spi_api_t::open call).
Initiate a read from a slave device using the spi_api_t::read API function. (g_spi.p_api->read(g_spi.p_ctrl, dst, length, SPI_BIT_WIDTH_8_BITS); where g_spi.p_ctrl is the same control instance that was used in the spi_api_t::open call).
Initiate a data transfer in both directions with a slave device using the spi_api_t::writeRead API function. (g_spi.p_api->writeRead(g_spi.p_ctrl, source, s_length, destination, d_length, SPI_BIT_WIDTH_8_BITS); where g_spi.p_ctrl is the same control instance that was used in the spi_api_t::open call).
Use the spi_api_t::close API function to close the instance. (g_spi.p_api->close(g_spi,p_ctrl) where g_spi.p_ctrl is the same control structure that was used in the spi_api_t::open call).

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

Flow Diagram of a Typical SPI HAL Module Application

Table of Contents