Synergy Software Package User's Manual
Audio Record ADC Framework

Table of Contents

Audio Record ADC Framework Module Introduction

The Audio Record ADC Framework module provides a high-level API for audio recording applications and uses the sf_adc_periodic and its lower layer ADC, GPT and DTC peripherals on the Synergy MCU. A user-defined callback can be created to indicate that the sample count has been completed.

Audio Record ADC Framework Module Features

audio_record_adc_BD.png
Audio Record ADC Framework Module Block Diagram

Audio Record ADC Framework Module APIs Overview

The Audio Record ADC Framework module defines APIs for opening, closing, starting and stopping the record process. 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 ADC Framework Module API Summary

Function Name Example API Call and Description
open g_sf_audio_record_adc.p_api->open(g_sf_audio_record_adc.p_ctrl, g_sf_audio_record_adc.p_cfg);
Initialize the module.
start g_sf_audio_record_adc.p_api->start(g_sf_audio_record_adc.p_ctrl);
Start audio recording.
stop g_sf_audio_record_adc.p_api->stop(g_sf_audio_record_adc.p_ctrl);
Stop audio recording.
infoGet g_sf_audio_record_adc.p_api->infoGet(g_sf_audio_record_adc.p_api.p_ctrl;
Get the channel information (mono or Stereo).
close g_sf_audio_record_adc.p_api->close(g_sf_audio_record_adc.p_ctrl);
Close the module.
versionGet g_sf_audio_record_adc.p_api->versionGet(&version);
Retrieve the API version 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 API Call Successful.
SSP_ERR_INVALID_ARGUME Parameter has invalid value.
SSP_ERR_IN_USE The adc periodic framework mutex may be unavailable for the unit requested. See HAL driver for other possible causes.
SSP_ERR_INTERNAL An internal ThreadX error has occurred. This is typically a failure to create/use a mutex or to create an internal thread.
SSP_ERR_NOT_OPEN Unit is not open.
SSP_ERR_ASSERTION The parameter p_ctrl or p_sample is NULL.
SSP_ERR_UNSUPPORTED This function is not supported by the HAL driver (p_ctrl->p_api->close is NULL).
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 ADC Framework Module Operational Overview

The Audio Record ADC Framework Module samples audio analog data using the ADC Periodic Framework and the data samples captured are stored in the user buffer. The data is made available for further processing as needed by the application. The Audio Record ADC Framework has a configuration parameter that is initialized during the framework initialization, which also initializes the underlying ADC periodic framework for data capture.

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_record_buffer;
void sf_audio_record_user_callback (sf_audio_record_callback_args_t *p_args)
{
audio_record_buffer = ((uint16_t *)g_sf_audio_record_adc.p_cfg->
p_capture_data_buffer + (p_args->buffer_index/2)); }

Audio Record ADC Framework Module Important Operational Notes and Limitations

Audio Record ADC Framework Module Operational Notes

  • The Audio Record ADC Framework Module configuration data can specify the length of the data buffer, data width, sampling rate and the number of sampling iterations.

Audio Record ADC Framework Module Limitations

  • Currently, the Audio Record ADC only supports the ADC Periodic Framework as the lower level; recording via the I2S is not supported.
  • The framework currently supports recording 8 bit or 12 bit PCM data.
  • Currently, the Audio Record ADC only supports mono channel.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the Audio Record ADC Framework Module in an Application

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

Audio Record ADC Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_audio_record_adc0 Audio Record ADC Framework on sf_audio_record_adc Threads New Stack> Driver> Audio> Audio Record ADC Framework on sf_audio_record_adc

When the Audio Record ADC Framework on sf_audio_record_adc 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_adc_MS.png
Audio Record ADC Framework Module Stack

Configuring the Audio Record ADC Framework Module

The Audio Record ADC Framework 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 Audio Record ADC Framework Module on sf_audio_record_adc

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
Name g_sf_audio_record_adc0 Module name.
Name of the data-buffer to store samples p_capture_data_buffer Name of the 16-bit data buffer to store samples.
Length of the data-buffer 2048 Length of the buffer to which data is to be stored.
Audio Record Data Size 8-Bit, 16-Bit

Default: 8-Bit 		The data width of captured data 8 bit or 16 bit.
Sampling Rate in HZ 8000 Sampling rate to be used to capture data.
Number of sampling iterations 256 Samples to be captured.
Callback g_audio_record_framework_user_callback Callback to user after capturing the sample count.
Name of generated initialization function sf_audio_record_adc_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization 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 Audio Record ADC Framework 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 ADC Periodic Framework on sf_adc_periodic

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
Name g_sf_adc_periodic0 Module name.
Name of the data-buffer to store samples g_user_buffer Name of the 16-bit data buffer to store samples.
Length of the data-buffer 2048 Length of the buffer to which data is to be stored.
Number of sampling iterations 256 Priority of ADC Periodic Framework internal thread.
Callback NULL User function that will be called once "sample_counts" number of data has been buffered.
Name of generated initialization function sf_adc_periodic_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization 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 ADC HAL Module on r_adc

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: Enabled 		If selected code for parameter checking is included in the build.
Name g_adc0 Module name.
Unit 0, 1 (S7G2 Only)

Default: 0 		Specify the ADC Unit to be used. The S7G2 has two units; 0 and 1.
Resolution 14-Bit (S3A7/S124 Only), 12-Bit, 10-Bit (S7G2)

Default: 8-Bit (S7G2 Only) 		Specify the conversion resolution for this unit.
Alignment Right, Left

Default: Right 		Specify the conversion result alignment.
Clear after read Off, On

Default: On 		Specify if the result register must be automatically cleared after the conversion result is read.

Note: If this is enabled, then watching the result register using a debugger always results in a 0.
Mode Single Scan The ADC Framework preconfigures and locks this field.
Channels 0-6 Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A.
Channels 7-10 (S3A7/S124 Only) Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A.
Channels 11-15 (S3A7 Only) Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A.
Channels 16-20 Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A.
Channel 21 (Unit 0 Only) Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A.
Channel 22 (S3A7/S124 Only) Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A.
Channels 23-27 (S3A7 Only) Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		In Normal mode of operation, this bitmask field is used to specify the channels that are enabled in that ADC unit. For example, if it is set to 0x101, then channels 0 and 2 are enabled. In group mode, this field is used to specify which channels belong to group A.
Temperature Sensor Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		Temperature sensor use selection for Channel Scan Mask.
Voltage Sensor Unused, Use in Normal/Group A, Use in Group B

Default: Unused 		Voltage sensor use selection for Channel Scan Mask.
Normal/Group A Trigger ELC Event The ADC Framework preconfigures and locks this field.
Group B Trigger (Valid Only in Group Scan Mode) ELC Event (The only valid trigger for either group in Group Scan Mode) The ADC Framework preconfigures and locks this field.
Group Priority (Valid only in Group Scan Mode) Group A cannot interrupt Group B, Group A can interrupt Group B; Group B scan restarts at next trigger, Group A can interrupt Group B; Group B scan restarts immediately, Group A can interrupt Group B; Group B scan restarts immediately and scans continuously 

Default: Group A cannot interrupt Group B 		Do not use with ADC Framework since the mode is locked to Single Scan Mode.
Add/Average Count Disabled, Add two samples, Add three samples, Add four samples, Add sixteen samples, Average two samples, Average four samples

Default: Disabled 		Specify if addition or averaging needs to be done for any of the channels in this unit. The actual channels are specified by using a channel mask adc_channel_cfg_t::add_mask.
Channels 0-27 Disabled, Enabled

Default: Disabled 		This field is valid only if adc_cfg_t::add_average_count is enabled. This field determines what channels results are to be averaged or summed.
Temperature Sensor Disabled, Enabled

Default: Disabled 		Temperature sensor use selection for Addition/Averaging Mask.
Voltage Sensor Disabled, Enabled

Default: Disabled 		Voltage sensor use selection for Addition/Averaging Mask.
Channels 0-2 Disabled, Enabled

Default: Disabled 		Determines which of channels 0, 1 and 2 are using the updated sample-and-hold states value specified in adc_channel_cfg_t::sample_hold_states. This field must only be set if it is desired to modify the default sample and hold count value for channels 0, 1 and 2.
Sample Hold States (Applies only to the 3 channels selected above) 24 Specifies the updated sample-and-hold count for the channel dedicated sample-and-hold circuit. This field is valid only if adc_channel_cfg_t::sample_hold_mask is not 0. Only channels 0, 1 and 2 have dedicated sample and hold circuits.

Note: Use this to modify the default number of states (24) for which the value is sampled. Each state is equal to 1/ADCLK time.
Callback NULL The ADC Framework uses the callback internally.
Scan End Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		Scan End Interrupt Priority selection.
Scan End Group B Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		Scan End Group B 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 AGT HAL Module 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 Raw Counts, Nanoseconds, Microseconds, Milliseconds, Seconds, Hertz, Kilohertz

Default: Microseconds 		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: True 		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.
Underflow 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.
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 GPT HAL Module on r_gpt

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
Name g_timer0 Module name.
Channel 0 The ADC Framework preconfigures and locks this field based on channel selected in the ADC Framework.
Mode Periodic The ADC Framework preconfigures and locks this field.
Period Value 10 Configure timer period to trigger ADC scans.
Period Unit Raw Counts, Nanoseconds, Microseconds, Milliseconds, Seconds, Hertz, Kilohertz

Default: Milliseconds 		Configure units of the timer period set above.
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 The ADC Framework preconfigures and locks this field.
GTIOCA Output Enabled True, False

Default: False 		Set to true to output the timer signal on a port pin configured for GPT. Set to false for no output of the timer signal.
GTIOCA Stop Level Pin Level Low, Pin Level High, Pin Level Retained

Default: Pin Level Low 		Controls output pin level when the timer is stopped.
GTIOCB Output Enabled True, False

Default: False 		Set to true to output the timer signal on a port pin configured for GPT. Set to false for no output of the timer signal.
GTIOCB Stop Level Pin Level Low, Pin Level High, Pin Level Retained

Default: Pin Level Low 		Controls output pin level when the timer is stopped.
Callback NULL The ADC Framework preconfigures and locks this field.
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 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 DTC HAL Module on r_dtc Software Activation

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 Block Mode selection.
Transfer Size 2 Bytes Transfer size selection.
Destination Address Mode Incremented 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 1 Number of transfers selection.
Number of Blocks (Valid only in Block Mode) 1 Number of blocks selection.
Activation Source (Must enable IRQ) 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 settings 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 ADC Framework Module Clock Configuration

The ADC peripheral module uses the PCLKC as its clock source.

Audio Record ADC Framework Module Pin Configuration

The ADC 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.  ADC pins must be configured as analog pins. 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 for the Audio Record ADC Framework Module on sf_audio_record_adc

Resource ISDE Tab Pin selection Sequence
ADC Pins Select Peripherals > Analog:ADC > ADC0
Note
The selection sequence assumes KINT0 is the desired hardware target for the driver.

Pin Configuration Settings for the Audio Record ADC Framework Module on sf_audio_record_adc

Property Value Description
Operation Mode Disabled, Custom
Default: Custom 		Select operating mode for ADC.
ADTRG None, P407, P102
Default: None) 		ADTRG pin.
AN00-19 None, Pnnn, Pmmm  
Default: None 		Analog input pins.
PGAVSS0 None, P003
Default: None 		PGAVSS pin.
Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and Synergy Kits may have different available pin configuration settings.

Using the Audio Record ADC Framework Module in an Application

The steps in using the Audio Record ADC Framework module on sf_audio_record_adc in a typical application are:

  1. Open 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. Store data in a user buffer with the callback.
  4. Operate on data as needed.
  5. Close the module using the sf_audio_record_api_t::close API.

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

audio_record_adc_TA.png
Flow Diagram of a Typical Audio Record ADC Framework Module Application