I2S Driver

Table of Contents

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

I2S HAL Module Introduction

The I2S HAL module provides a high-level API for the standard I2S audio serial communication protocol used to send or receive uncompressed audio data in master/slave mode.

I2S HAL Module Features

The I2S HAL module used with the SSI peripheral in I2S master/slave mode supports the following features (in addition to the standard I2S protocol):

• Full-duplex I2S communication (SSI channel 0 only)
• Interrupt driven data transmission and reception
• Integration with the DTC transfer module
• A user-defined callback created to respond to the need for additional data

I2S HAL Module Block Diagram

I2S Hardware Support Details

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

Legend:

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

 

MCU Group	Supports 2 Channels	SSI Format Support	MSB first Format Support	Serial bit clock configurable {16, 32, 48, and 64 sampling rates}	Master clock input from the master clock pin for audio (AUDIO_CLK)	Master clock input from the master clock pin for GPT output (GTIOC1A)
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	⌧	⌧	⌧	✓	✓	⌧
S3A3	⌧	⌧	⌧	✓	✓	⌧
S3A6	⌧	⌧	⌧	✓	✓	⌧
S3A7	✓	⌧	⌧	✓	✓	⌧
S5D3	✓	⌧	⌧	✓	✓	⌧
S5D5	⌧	⌧	⌧	✓	✓	⌧
S5D9	✓	⌧	⌧	✓	✓	⌧
S7G2	✓	⌧	⌧	✓	✓	⌧

MCU Group	Ability to select Stop Word SSIWS	Accepts Interrupts from Communication Errors	Accepts Interrupts from Receive Data Full	Accepts Interrupts from Transmit Data Empty	Internal Connection to GPT output GTIOC1A
S124	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A
S3A1	⌧	✓	✓	✓	✓
S3A3	⌧	✓	✓	✓	✓
S3A6	⌧	✓	✓	✓	✓
S3A7	✓	✓	✓	✓	✓
S5D3	⌧	✓	✓	✓	✓
S5D5	⌧	✓	✓	✓	✓
S5D9	⌧	✓	✓	✓	✓
S7G2	✓	✓	✓	✓	✓

I2S HAL Module APIs Overview

The I2S HAL module defines APIs for operations such as opening, muting, writing and reading. 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.

I2S HAL Module API Summary

Function Name	Example API Call and Description
open	g_i2s0.p_api->open(g_i2s0.p_ctrl, g_i2s0.p_cfg); Initial configuration.
stop	g_i2s0.p_api->stop(g_i2s0.p_ctrl, direction_to_stop); Stop communication. Transmission is stopped when callback is called with I2S_EVENT_IDLE. Reception is stopped when callback is called with I2S_EVENT_RX_EMPTY.
mute	g_i2s0.p_api->mute(g_i2s0.p_ctrl, mute_enable); Enable or disable mute.
write	g_i2s0.p_api->write(g_i2s0.p_ctrl, &data, bytes); Write I2S data. All transmit data is queued when callback is called with I2S_EVENT_TX_EMPTY. Transmission is complete when callback is called with I2S_EVENT_IDLE.
read	g_i2s0.p_api->read(g_i2s0.p_ctrl, &data, bytes); Read I2S data. Reception is complete when callback is called with I2S_EVENT_RX_EMPTY.
writeRead	g_i2s0.p_api->writeRead(g_i2s0.p_ctrl, &source, &destination, bytes); Simultaneously write and read I2S data. Transmission and reception are complete when callback is called with I2S_EVENT_IDLE.
infoGet	g_i2s0.p_api->infoGet(g_i2s0.p_ctrl, &info); Get instance specific information and store it in provided pointer info.
close	g_i2s0.p_api->close(g_i2s0.p_ctrl); Allows driver to be reconfigured and may reduce power consumption.
versionGet	g_i2s0.p_api->versionGet(&version); Get version and store it in provided pointer version.

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 successful.
SSP_ERR_OUT_OF_MEMORY	The number of streams open at once is limited to SF_AUDIO_PLAYBACK_CFG_MAX_STREAMS. If this number is exceeded, an out of memory error occurs.
SSP_ERR_TIMEOUT	Timeout occurred before playback finished.
SSP_ERR_ASSERTION	A critical assertion has failed.
SSP_ERR_IN_USE	Channel is running/busy.
SSP_NOT_OPEN	Requested channel is not configured or API not open.

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.

I2S HAL Module Operational Overview

The I2S HAL module supports audio communications using the I2S protocol. The driver supports the SSI Peripheral on a Synergy MCU in I2S master/slave mode. It can send and receive uncompressed audio data. It provides full-duplex I2S communication (SSI channel 0 only), interrupt-driven data transmission, reception, and integration with the DTC transfer module.

I2S HAL Module Important Operational Notes and Limitations

I2S HAL Module Operational Notes

To enable audio data reception on channel 0, enable the SSI0 RXI interrupt. To enable audio data transmission on channel 0, enable the SSI0 TXI interrupt. To enable both transmission and reception on channel 0, enable both the SSI0 TXI and SSI0 RXI interrupts. To enable transmission or reception on channel 1, enable the SSIn TXI RXI interrupt. In all cases, enable the SSIn INT interrupt.

When the interrupts are enabled in the BSP, the corresponding ISRs will be defined in the I2S driver. The ISR will call the user-callback function registered in open.

I2S HAL Module Limitations

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

Including the I2S HAL Module in an Application

This section describes how to include the I2S 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 I2S 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 I2S Driver is g_i2s0. This name can be changed in the associated Properties window.)

I2S HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_i2s0 I2S Driver on r_ssi	Threads> HAL/Common Stacks	New Stack> Driver> Connectivity> I2S Driver on r_ssi

When the I2S Driver on r_ssi 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.

I2S HAL Module Stack

Configuring the I2S HAL Module

The I2S 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 I2S HAL Module on r_ssi

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enables or disables the parameter checking.
Name	g_i2s0	Module name.
Channel	0	Physical hardware channel.
Audio Clock Frequency (Hertz)	2822400	Input audio clock frequency, used to generate the I2S clock. Must be a multiple between 1 and 128 of: (sampling_freq_hz * word_length_in_bits)
Sampling Frequency (Hertz)	44100	Sampling frequency of audio data.
Operating Mode	Master Mode, Slave Mode Default: Master Mode	Operating mode of communication (Master/Slave).
Data Bits	8 bits, 16, 18, 20, 22, 24 Default: 16 bits	Bit depth of audio data, which is the size in bits of one sample of audio data.
Word Length	8 bits, 16, 24, 32 Default: 16 bits	Word length of audio data, must be at least the same size as the bit depth (Data Bits field).
WS Continue Mode	Enabled, Disabled Default: Disabled	Enable WS continue mode to continue to output the word select line when the peripheral is idle. Disable to stop outputting the word select line when the peripheral is idle.
Name of I2S callback function to be defined by user	NULL	A user callback function must be registered in open. The callback will be called from the interrupt service routine (ISR) when the transmission FIFO reaches the high watermark point after all data for transmission is transmitted or when reception is complete (the requested number of bytes have been received). Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system
Transmit Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Transmit interrupt priority selection
Receive Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Receive interrupt priority selection
Idle/Error Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Priority 12	Idle/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.

In some cases, settings other than the defaults for lower level modules can be desirable. For example, it might be useful to select the DAC or I2S Channel based on the target hardware implementation. The configurable properties for the lower level stack modules are given in the below sections for completeness and as a reference. 

Note

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

Configuration Settings for the I2S 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.

Configurable Settings for the Transfer Driver on r_dtc Software Activation

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Parameter selection.
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.
Name	g_transfer0	Driver name.
Mode	Normal	Mode selection.
Transfer Size	4 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)	Software Activation 1, Software Activation 2, Peripheral Events Default: Software Activation 1	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 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 Software Activation 1

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Parameter selection.
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.
Name	g_transfer1	Driver name.
Mode	Normal	Mode selection.
Transfer Size	4 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)	Software Activation 1, Software Activation 2, Peripheral Events Default: Software Activation 1	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 settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configurable Settings for the Timer Driver on r_agt

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Parameter selection.
Name	g_timer0	Module name.
Channel	0	Channel selection.
Mode	Periodic	Mode selection.
Period Value	2822400 *2	Period value selection.
Period Unit	Hertz	Period unit selection.
Auto Start	FALSE	Auto start selection.
Count Source	PCLKB, PCLKB/8, PCLKB/2, LOCO, AGT0 Underflow, AGT0 fSub Default: PCLKB	Count source selection.
AGTO Output Enabled	True, False Default: False	AGTO output selection.
AGTIO Output Enabled	True, False Default: False	AGTIO output selection.
Output Inverted	True, False Default: False	Output inverted selection.
Enable comparator A output pin	True, False Default: False	Enable comparator A output pin selection.
Enable comparator B output pin	True, False Default: False	Enable comparator B output pin selection.
Callback	NULL	Callback selection.
Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	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.

Configurable Settings for the Timer Driver on r_gpt

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Parameter selection.
Name	g_timer0	Module name.
Channel	0	Channel selection.
Mode	Periodic	Mode selection.
Period Value	2822400 *2	Period value selection.
Period Unit	Hertz	Period unit selection.
Duty Cycle Value	50	Duty cycle value selection.
Duty Cycle Unit	Unit Raw Counts, Unit Percent, Unit Percent x 1000 Default: Unit Raw Counts	Duty cycle unit selection.
Auto Start	FALSE	Auto start selection.
GTIOCA Output Enabled	True, False Default: False	GTIOCA output enabled selection.
GTIOCA Stop Level	Pin Level Low, Pin Level High, Pin Level Retained Default: Pin Level Low	GTIOCA stop level selection.
GTIOCB Output Enabled	True, False Default: False	GTIOCB output enabled selection.
GTIOCB Stop Level	Pin Level Low, Pin Level High, Pin Level Retained Default: Pin Level Low	GTIOCB stop level selection.
Callback	NULL	Callback selection.
Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	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.

I2S HAL Module Clock Configuration

The SSI module uses the peripheral clock (PCLKB) available from the Clock configuration window. It also uses an external clock input to the AUDIO_CLK pin.

I2S HAL Module Pin Configuration

The SSI 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.

Configure the SSI RX and/or TX pins for the selected SSI channel (Pins tab > Peripherals > SSI > SSIn > SSITXD0/SSIRXD0). For channel 0, enable one or both of these pins. For channel 1, enable the SSIDATA1 pin.

Configure the word select and clock pins (Pins tab > Peripherals > SSI > SSIn > SSITWSn and SSISCKn). Both of these pins are required in most cases. Consult the datasheet of the I2S device used for the required pins.

Configure the audio clock pin (Pins tab > Peripherals > SSI > SSI0_SSI1_AUDIO_CLK) for SSI. Connect an external audio clock to this clock input pin. If a GPT timer is used to generate the audio clock, configure the GPT timer output pin (Pins tab > Peripherals > GPT1 > GPTn > GTIOCx) and connect the GPT output pin used to the audio clock input pin.

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 associated pins:

Pin Selection for the I2S HAL Module on r_ssi

Resource	ISDE Tab	Pin selection Sequence
ACMPLP	Pins	Select Peripherals> Analog:ACMP.

Note

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

Pin Configurable Settings for the I2S Driver on SSI

Pin Configuration Property	Settings	Description
Pin Group Selection	_A only, Mixed	Pin group for I2S port.
Operation Mode	Custom, Disabled	Operation selection.
SSISCK	None, P400 Default: None	AUDIO_CLK pin(P400), used in this application

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.

Pin Configuration Settings for I2S Driver on SSI0

Pin Configuration Property	Settings	Description
Pin Group Selection	_A only, _B only, Mixed	Pin group for I2S port.
Operation Mode	Enabled, Custom, Disabled	Operation selection.
SSISCK	None, P112 Default: None	SSISCK pin (P112), used in this application.
SSIWS	None, P113 Default: None	SSIWS pin (P113), used in this application.
SSITXD	None, P115 Default: None	SSITXD pin (P115), used in this application.
SSIRXD	None, P114 Default: None	SSIRXD pin (P114), used in this application.

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.

Pin Configuration Settings for I2S Driver on SSI1

Pin Configuration Property	Settings	Description
Pin Group Selection	_A only, _B only, Mixed	Pin group for I2S port.
Operation Mode	Enabled, Custom, Disabled	Operation selection.
SSISCK	None, P204 Default: None	SSI Serial Clock, not used in this application.
SSIWS	None, P205 Default: None	SSI Stereo pin selection, not used in this application.
SSIDATA	None, P206 Default: None	SSI Data pin selection, not used in this application.

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.

Using the I2S HAL Module in an Application

The typical steps in using the I2S HAL module in an application are:

1. Open the I2S HAL module using the i2s_api_t::open API.
2. Use the i2s_api_t::write API to write audio data to the I2S bus.
3. Wait for a callback with I2S_EVENT_TX_EMPTY and free the source buffer.
4. Use the i2s_api_t::read API to read data from the I2S bus.
5. Wait for a callback with I2S_EVENT_RX_FULL before accessing the destination buffer or reading the next buffer.
6. Use other APIs as needed by the application.
7. Close the module with the i2s_api_t::close API.

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

Flow Diagram of a Typical I2S HAL Module Application