Synergy Software Package User's Manual
Audio Record I2S Framework

Table of Contents

Audio Record I2S Framework Introduction

The Audio Record I2S Framework module provides a high-level API for audio recording applications and uses the I2S interface. The Audio Record I2S Framework module uses the SSI, GPT and DTC peripherals on the Synergy MCU. A user-defined callback can be created to indicate that new samples are stored in the user buffer.

Audio Record I2S Framework Module Features

  • Thread safe
  • Records data in 8 or 16-bit PCM
  • Periodic callback function when new samples are available
  • Configurable number of samples (sample count) per callback
Audio_Record_I2S_BD.png
Audio Record I2S Framework Module Block Diagram

Audio Record I2S Framework Module APIs Overview

The Audio Record I2S Framework module defines APIs to open, start, stop and close the recording module. 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 Record I2S Framework Module API Summary

Function Name Example API Call and Description
open g_sf_audio_record_i2s0.p_api->open (g_sf_audio_record_i2s0.p_ctrl, g_sf_audio_record_i2s0.p_cfg);
Initializes audio recording framework.
start g_sf_audio_record_i2s0.p_api->start (g_sf_audio_record_i2s0.p_ctrl);
Starts audio recording.
stop g_ sf_audio_record_i2s0.p_api->stop (g_sf_audio_record_i2s0.p_ctrl);
Stops audio recording.
infoGet g_sf_audio_record_i2s0.p_api->infoGet (g_sf_audio_record_i2s0.p_ctrl, p_info);
Gets channel information (Mono/Stereo).
close g_sf_audio_record_i2s0.p_api->close (g_sf_audio_record_i2s0.p_ctrl);
Releases channel mutex and closes channel at HAL layer.
versionGet g_ sf_audio_record_i2s0.p_api->versionGet(&version);
Gets version and stores it in provided 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 API Call Successful.
SSP_ERR_INVALID_ARGUMENT Parameter has invalid value.
SSP_ERR_INTERNAL An internal TheadX error has occurred.
SSP_ERR_NOT_OPEN Unit is not open.
SSP_ERR_ASSERTION The parameter p_ctrl or p_sample is NULL.
SSP_ERR_IN_USE Peripheral is still running in another mode; perform Close first.
SSP_ERR_UNSUPPORTED Command not supported.
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 Record I2S Framework Module Operational Overview

The Audio Record I2S Framework Module uses the I2S HAL layer as the underlying interface for the audio data transfer and the data captured is stored in the user buffer. The data is made available for further processing as needed by the application.

The captured data is stored in a user defined buffer and this is done in the callback function as illustrated below:

Assuming the name of the callback has been configured to be  sf_audio_record_user_callback.

uint16_t * audio_buffer;
void audio_record_user_callback (sf_audio_record_callback_args_t * p_args)
{
    audio_buffer = ((uint16_t *)sf_audio_record_i2s.p_cfg->p_capture_data_buffer
                   + (p_args->buffer_index));
}

Audio Record I2S Framework Module Important Operational Notes and Limitations

Audio Record I2S Framework Module Operational Notes

The Audio Record I2S Framework Module configuration data can specify the name of the data buffer, length of the data buffer, data size (8-bit or 16-bit samples), sampling iterations and the name of the callback.

Audio Record I2S Framework Module Limitations

  • The framework currently supports recording 8-bit or 16-bit PCM data.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the Audio Record I2S Framework Module in an Application

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

Audio Record I2S Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sf_audio_record_i2s0 Audio Record I2S Framework on sf_audio_record_i2s Threads New Stack> Framework> Audio> Audio Record I2S Framework on sf_audio_record_i2s

When the Audio Record I2S Framework module on sf_audio_record_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_Record_I2S_MS.png
Audio Record I2S Framework Module Stack

Configuring the Audio Record I2S Framework Module

The Audio Record 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 Record I2S Framework Module on sf_audio_record_i2s

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enables or disables the parameter checking.
Name g_sf_audio_record_i2s0 Module name.
Name of the data-buffer to store samples p_capture_data_buffer Data-buffer name.
Length of the data buffer 2048 Length of the data buffer.
Audio Record Data Size 8-Bit, 16-Bit

Default: 16-Bit 		Audio record data size selection.
Number of sampling iterations 256 Number of sampling iterations.
Callback g_audio_record_framework_user_callback Callback name.
Name of generated initialization function sf_audio_record_i2s_init0 Name of generated initialization function.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization 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.

In some cases, settings other than the defaults for lower level modules can be desirable. 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 can usually be determined by inspection of the associated Properties window from the SSP configurator.

Configuring the Audio Record 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 Frequency (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.
Audio Clock Frequency (Hertz) External, GTIOC1A

Default: External 		Select External for external signal to AUDIO_CLK input pin or GTIOCA1.
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 DTC HAL Module 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 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)

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 DTC HAL Module 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)

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 AGT HAL Module 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.
Underflow 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.

Configuration Settings for the GPT HAL Module 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 Record I2S Framework Module Clock Configuration

The Audio Record I2S Framework module uses the PCLKB as its clock source.

To change the clock frequency at run-time, use the CGC Interface.

Audio Record I2S Framework Module Pin Configuration

To use the Audio Record I2S Framework module, the port pins for the peripheral inputs and outputs must be set in the pin configurator in the ISDE. The following table illustrates the method for selecting the pins within the ISDE configuration window:

Pin Selection Sequence for the Audio Record I2S Framework Module

Resource ISDE Tab Pin selection Sequence
SSI Pins Select  Peripherals> Connectivity:SSI> SSI/SSI0/SSI1

Using the Audio Record I2S Framework Module in an Application

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

  1. Initialize the module using the sf_audio_record_api_t::open API.
  2. Start the recording using the sf_audio_record_api_t::start API.
  3. Operate on data from the periodic callback function as needed.
  4. Close the module using the sf_audio_record_api_t::close API.

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

Audio_Record_I2S_TA.png
Flow Diagram of a Typical Audio Record I2S Framework Module Application