Synergy Software Package User's Manual
Audio Playback Hardware Framework Shared on sf_audio_playback_hw_i2s

Table of Contents

Audio Playback I2S Framework Introduction

The I2S Audio Playback Framework module provides a high-level API for Audio Playback applications and handles the synchronization needed to play 8-bit or 16-bit pulse-code modulation (PCM) samples. The Audio Playback Framework uses the I2S, Timer (AGT or GPT) and Data Transfer (DMA or DTC) peripherals on a Synergy MCU. A user defined callback can be created to respond to the need for additional data.

Audio Playback I2S Framework Module Features

  • Plays long buffers by splitting the data into manageable chunks.
  • Repeats playback until ThreadX timeout (for repeated audio like sine wave tones or looped background music).
  • Requests next data using callback after last buffer playback begins.
  • Software volume control.
  • Pauses and resumes functions.
  • Basic mixing for multiple streams.
audio_playback_i2s_BD.png
Audio Playback I2S Framework Module Block Diagram

Audio Playback I2S Framework Module APIs Overview

The Audio Playback I2S Framework module defines APIs for operations such as opening, starting, playing and stopping. 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.

Audio Playback I2S Framework Module API Summary

Function Name Example API Call and Description
open g_sf_audio_playback_hw0.p_api->open( g_sf_audio_playback_hw0.p_ctrl, g_sf_audio_playback_hw0.p_cfg);
Open a device channel for read/write and control.
start g_sf_audio_playback_hw0.p_api->start( g_sf_audio_playback_hw0.p_ctrl, &p_data, Timeout);
Start Audio Playback Hardware.
stop g_sf_audio_playback_hw0.p_api->stop( g_sf_audio_playback_hw0.p_ctrl);
Stop Audio Playback Hardware.
play g_sf_audio_playback_hw0.p_api->play (g_sf_audio_playback_hw0.p_ctrl, p_buffer, length);
Play audio buffer.
dataTypeGet g_sf_audio_playback_hw0.p_api->dataTypeGet( g_sf_audio_playback_hw0.p_ctrl, p_data_type);
Stores expected data type in provided pointer p_data_type.
close g_sf_audio_playback_hw0.p_api->close( g_sf_audio_playback_hw0.p_ctrl);
Close the audio module.
versionGet g_sf_audio_playback_hw0.p_api->versionGet(&version);
Return the version of the module with the version pointer.
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 thisnumber is exceeded, an out of memory error occurs.
SSP_ERR_TIMEOUT Timeout occurred before playback finished.
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.

Audio Playback I2S Framework Module Operational Overview

The I2S Audio Playback Framework module creates a thread internally to support audio playback. The figure below shows a flowchart of the audio playback framework thread and its interactions with public Audio Playback Framework APIs.

audio_playback_i2s_FC.png
Audio Playback DAC Framework Module Flow Chart

Suggested use of the audio playback framework:

  • Create a semaphore (for example g_sf_audio_playback_semaphore). This can be done on the Threads tab. Set the initial value to 2 (the audio playback framework can store up to two data messages per stream).
  • Create a callback function (for example sf_audio_playback_callback). Enter the name of your callback function in the Audio Playback Framework instance. The callback function will be called when the audio playback framework is done with the data. In the callback, put the semaphore created above.
  • In your main loop, get the semaphore before playing data. To play data, first acquire a buffer from the messaging framework, then create your audio playback data structure inside the buffer.

The Audio Playback Framework supports multiple audio streams on a single hardware port. A block diagram of the modules required if two streams are used is shown in following figure:

audio_playback_i2s_AS.png
Audio Playback DAC Framework Implementing Multiple Audio Streams

Audio Playback I2S Framework Module Important Operational Notes and Limitations

Audio Playback I2S Framework Module Operational Notes

  • The queue used must match the name specified in Properties for Audio Playback Framework Shared on sf_audio_playback (default is g_sf_audio_playback_queue).
  • The audio framework I2S hardware port has dependencies on the I2S driver module. The I2S driver module can be accelerated with DTC (recommended).
  • I2S driver module.
    • Set the Audio Clock Frequency (Hertz) to the frequency of the input audio clock used.
    • Set the Sampling Frequency (Hertz) to the sampling frequency of your audio data.
    • Set the Data Bits and Word Length to 16 bits (audio framework accepts 16 bit samples only).
    • Enable the SSIn TXI and SSIn INT interrupts.
  • Transfer module on r_dtc (recommended).
  • Set the activation source to the SSIn TXI interrupt.
  • The Audio Playback I2S Framework is designed to support the following MCU families with no changes to the API:
    • S7G2
    • S3A7
    • S5D9
    • S3A3
    • S3A6
    • S5D5
    • S3A1
    • S5D3

Audio Playback I2S Framework Module Limitations

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

Including the Audio Playback I2S Framework Module in an Application

This section describes how to include the Audio Playback I2S 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 Audio Playback I2S 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 Audio Playback I2S Framework module is g_sf_audio_playback_hw0. This name can be changed in the associated Properties window.)

Audio Playback I2S Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sf_audio_playback_hw0 Audio Playback Hardware Framework on sf_audio_playback_hw_i2s Threads New Stack> Framework> Audio> Audio Playback Hardware Framework on sf_audio_playback_hw_i2s

When the Audio Playback I2S Framework module on sf_audio_playback_hw_i2s 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.

audio_playback_i2s_MS.png
Audio Playback I2S Framework Module Stack

Configuring the Audio Playback I2S Framework Module

The Audio Playback I2S 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 Audio Playback I2S Framework Module on sf_audio_playback_hw_i2s

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enable or disable the parameter error checking.
Name g_sf_audio_playback_hw0 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.

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 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 Audio Playback I2S 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 table identifies all the settings within the properties section for the module.

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 Frequecy (Hertz) 44100 Sampling frequency of audio data.
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)

Default: Disabled 		Transmit interrupt priority selection.
Receive Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		Receive interrupt priority selection.
Idle/Error Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Idle/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 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_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 Activiation 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)

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 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 Activiation 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)

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 Timer Driver on r_agt

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables parameter checking.
Name g_timer0 Module name.
Channel 0 Physical hardware channel.
Mode Periodic Warning: One-shot functionality is not available in the GPT hardware, so it is implemented in software by stopping the timer in the ISR called when the period expires. For this reason, ISRs must be enabled for one-shot mode even if the callback is unused.
Period Value 10 See Timer Period Calculation.
Period Unit Hertz See Timer Period Calculation.
Auto Start False Set to true to start the timer after configuring or false to leave the timer stopped until timer_api_t::start is called.
Count Source PCLKB, PCLKB/8, PCLKB/2, LOCO, AGT0 Underflow, AGT0 fSub

Default: PCLKB 		The clock source for the AGT counter.
AGTO Output Enabled True, False

Default: False 		Set to true to output the timer signal on a port pin configured for AGT (AGTO pin). Set to false for no output of the timer signal.
AGTIO Output Enabled True, False

Default: False 		Set to true to output the timer signal on a port pin configured for AGT (AGTIO pin). Set to false for no output of the timer signal.
Output Inverted True, False

Default: False 		Set to false to start the output signal low. Set to true to start the output signal high.
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 A user callback function can be registered in timer_api_t::open. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time the timer period elapses.

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.
Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		Timer interrupt priority. 0 is the highest priority.
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables parameter checking.
Name g_timer0 Module name.
Channel 0 Physical hardware channel.
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 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.
Overflow Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		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.

Audio Playback I2S Framework Module Clock Configuration

The Audio Playback I2S Framework hardware modules use the peripheral clocks available in the clock configuration window.

Audio Playback I2S Framework 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. The following tables illustrate the method for selecting the pins within the SSP configuration window and shows an example selection for the associated pins.

Pin Selection Sequence for the Audio Playback I2S Framework Module

Resource ISDE Tab Pin selection Sequence
I2S Pins Select Peripherals > Connectivity:SSI > SSI0/SSI1.
Note
The selection sequence assumes the ADC0/ADC1 or the SSI0/SSI1 is the desired hardware target of the driver.

Pin Configuration Settings for the I2S Driver on r_ssi

Pin Configuration Property Value 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.
SSIWS None, P205

Default: None 		SSI Stereo pin selection.
SSIDATA None, P206

Default: None 		SSI Data 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.

Using the Audio Playback I2S Framework Module in an Application

The typical steps in using the Audio Playback I2S Framework module in an application are:

1. Initialize the Audio Playback I2S Framework using the sf_audio_playback_hw_api_t::open API.

2. Start the low level hardware of the Audio Playback I2S framework using the sf_audio_playback_hw_api_t::start API.

3. Play the PCM audio samples using the sf_audio_playback_hw_api_t::play API.

4. PCM audio samples supported by the hardware is provided by the sf_audio_playback_hw_api_t::dataTypeGet API.

5. Stop the low level hardware of the Audio Playback I2S Framework using sf_audio_playback_hw_api_t::stop API.

6. Close the Audio Playback I2S framework using the sf_audio_playback_hw_api_t::close API.

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

audio_playback_i2s_TA.png
Flow Diagram of a Typical Audio Playback I2S Framework Module Application