Renesas Synergy User Manual

Application Note
Renesas Synergy™ Platform

Audio Record ADC Framework Module Guide

Introduction

This module guide will enable you to effectively use a module in your own design. Upon completion of this
guide you will be able to add this module to your own design, configure it correctly for the target application,
and write code using the included application project code as a reference and efficient starting point.
References to more detailed API descriptions and suggestions of other application projects that illustrate
more advanced uses of the module are available in the Renesas Synergy Knowledge Base (as described in
the References section in this document) and should be valuable resources for creating more complex
designs.

The Audio Record ADC Framework module is a high-level API for audio recording applications and is
implemented on sf_adc_periodic. The Audio Record ADC Framework module uses the 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.

Contents

1. Audio Record ADC Framework Module Features .................................................................... 2

2. Audio Record ADC Framework Module APIs Overview ........................................................... 2

3. Audio Record ADC Framework Module Operational Overview ................................................ 3

3.1 Audio Record ADC Framework Module Operational Notes .................................................................... 3

3.2 Audio Record ADC Framework Module Limitations ................................................................................ 3

4. Including the Audio Record ADC Framework Module in an Application ................................... 4

5. Configuring the Audio Record ADC Framework Module .......................................................... 4

5.1 Configuration Settings for the Audio Record ADC Framework Module Low Level Drivers .................... 5

5.2 Audio Record ADC Framework Module Clock Configuration.................................................................. 9

5.3 Audio Record ADC Framework Module Pin Configuration ..................................................................... 9

6. Using the Audio Record ADC Framework Module in an Application ...................................... 10

7. Audio Record ADC Framework Module Application Project ................................................... 11

8. Customizing the Audio Record ADC Framework Module for a Target Application ................. 14

9. Running the Audio Record ADC Framework Module Application Project ............................... 14

10. Audio Record ADC Framework Module Conclusion ............................................................... 16

11. Audio Record ADC Module Next Steps .................................................................................. 16

12. Audio Record ADC Module Reference Information ................................................................ 16

Revision History ............................................................................................................................ 18

R30AN0312EU0120 Rev.1.20 Page 1 of 18
Apr.29.19

Renesas Synergy™ Platform Audio Record ADC Framework Module Guide

Function Name

Example API Call and Description

.open

g_sf_audio_record_adc.p_api->open(g_sf_audio_record_adc.p_ctrl,

Initialize the module.

.start

g_sf_audio_record_adc.p_api-

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-

Get the channel information (mono or Stereo).

.close

g_sf_audio_record_adc.p_api-

Close the module.

1. Audio Record ADC Framework Module Features

• Records data in 8-bit or 12-bit PCM

• Uses ADC Periodic Framework to simplify configuration and integration

• Uses ThreadX

• APIs for high-level functions simplify coding:
 Open, start
 Stop, infoGet
 Close

®

object, like mutex, to protect hardware from improper access

Figure 1. Audio Record ADC Framework Module Organiza tion, Options and Stack Implementations

2. 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.

Table 1

. Audio Record ADC Framework Module API Summary

g_sf_audio_record_adc.p_cfg);

>start(g_sf_audio_record_adc.p_ctrl);

>infoGet(g_sf_audio_record_adc.p_api.p_ctrl);

>close(g_sf_audio_record_adc.p_ctrl);

R30AN0312EU0120 Rev.1.20 Page 2 of 18
Apr.29.19

Renesas Synergy™ Platform Audio Record ADC Framework Module Guide

.versionGet

g_sf_audio_record_adc.p_api->versionGet(&version);

Name

Description

SSP_SUCCESS

API Call Successful

SSP_ERR_INVALID_ARGUMENT

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

Retrieve the API version with the version point er .

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 Manuals API
References for the associated module.

Table 2. Status Return Values

create/use a mutex or to create an internal thread.

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.

3. 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 Module has a configuration
parameter that is initialized during the framework initialization, which also initializes the underlying ADC
periodic framework for data capture.

The data is captured in a user defined buffer and this is done in the callback function as illustrated as follows,
assuming that 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));

3.1 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.

3.2 Audio Record ADC Framework Module Limitations

• Currently the Audio Record ADC only supports the ADC Periodic Framework as the lower level and thus

recording via I2S is not supported with the framework.

• The framework currently supports recording 8-bit or 12-bit PCM data.

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

R30AN0312EU0120 Rev.1.20 Page 3 of 18
Apr.29.19

Renesas Synergy™ Platform Audio Record ADC Framework Module Guide

Resource

ISDE Tab

Stacks Selection Sequence

g_audio_record_adc0 Au di o
sf_audio_record_adc

Threads

New Stack> Framework> Audio> Audio
sf_audio_record_adc

4. 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 that 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 Module to an application, simply add it to a thread using the
Stacks Selection Sequence given in the following table. (The default name for the Audio Record ADC
Framework Module is g_audio_record_adc0.) This name can be changed in the associated Properties
window.

Table 3. Audio Record ADC Framework Module Selection Sequence

Record ADC Framework on

When the Audio Record ADC 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 drivers.

Record ADC Framework on

Figure 2. Audio Record ADC Framework Module Stack

5. Configuring the Audio Record ADC Framework Module

The Audio Record ADC Framework Module must be configured by you 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, for
successful operation. Only those 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 Property window in the ISDE. This approach simplifies the configuration
process and makes it much less error prone than previous manual approaches to configuration. The

R30AN0312EU0120 Rev.1.20 Page 4 of 18
Apr.29.19

Renesas Synergy™ Platform Audio Record ADC Framework Module Guide

ISDE Property

Value

Description

Parameter Checking

Enabled, Disabled, BSP
Default: BSP

Selects if code for parameter checking is to
Name

g_sf_audio_record_adc0

Module name

Name of the data-buffer to

P_capture_data_buffer

Name of the 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

Data width
Sampling Rate in HZ

8000

Sampling rate

Number of sampling

Default: 256

Number of samples captured per iteration

Callback

g_audio_redord_framework_

User function that will be called once the
been buffered.

ISDE Property

Value

Description

Parameter Checking

Enabled, Disabled, BSP
Default: BSP

Selects if code for parameter checking is to
Name

g_sf_adc_periodic0

Module name

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.

One of the properties most often identified as requiring a change is the Interrupt Priority. This configuration
setting is available with the Properties window of the associated module. Simply select the indicated module
and then view the properties window. The Interrupt settings are often toward the bottom of the properties list,
so scroll down until they become available. Also note that the Interrupt Priorities listed in the properties
window in the ISDE will include an indication as to the validity of the setting based on the MCU targeted
(CM4 or CM0+). This level of detail is not included in the following configuration properties tables, but is
easily visible with the ISDE when configur i ng Interr up t Pr iori t y levels.

Note: You may want to open your ISDE and 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 hand-on approach to learning the ins and outs of developing with SSP.

Table 4. Configuration Settings for Audio Record ADC Framework Module on sf_audio_record_adc

be included in the build

store samples

Default: 8-bit

iterations

user_callback

Note: The above setting examples and defaults are for a project using the S7G2 Synergy MCU Group.

Other MCUs may have different default values and available configuration settings.

In some cases, settings other than the defaults for stack modules can be desirable. For example, it might be
useful to select different buffer sizes or sample rates. 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 modules are fairly intuitive and usually can be determined by

inspection of the associated properties window from the SSP Configurator.

number of sampling iterations of data has

5.1 Configuration Settings for the Audio Record ADC Framework Module Low

Level Drivers

Typically, only a small number of settings must be modified from the default for lower level drivers and these
are 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 tables identify all the settings within the properties section for the module.

Table 5. Configuration Settings for ADC Periodic Framework on sf_adc_periodic

R30AN0312EU0120 Rev.1.20 Page 5 of 18
Apr.29.19

be included in the build

Renesas Synergy™ Platform Audio Record ADC Framework Module Guide

ISDE Property

Value

Description

Name of the data-buffer
to store samples

g_user_buffer

Name of the data buffer to store samples

Length of the data-buffer

2048

Length of the buffer to which data is to be

Number of sampling
iterations

256

Number of samples captured per iteration

GPT Timer channel used

Channel 0-12

Channel number

Callback

NULL

User function that will be called once the
been buffered

ISDE Property

Value

Description

Parameter Checking

BSP, Enabled, Disabled

If selected code for parameter checking is
Name

g_adc0

Module name

Unit

0, 1 (S7G2 Only)
Default: 0

Specify the ADC Unit to be used. The S7G2

Resolution

14-Bit (S3A7/S124 Only),

Default: 8-Bit (S7G2 Only)

Specify the conversion resolution for this unit.
Alignment

Right, Left

Specify the conversion result alignment.

Clear after read

Off, On

Specify if the result register must be

results in a 0.

Mode

Single Scan

The ADC Framework preconfigures and locks
this field.

Channels 0-6

Unused, Use in

In Normal mode of operation, this bitmask

specify which channels belong to group A.

Channels 7-10

Unused, Use in

In Normal mode of operation, this bitmask

specify which channels belong to group A.

Channels 11-15

Unused, Use in

In Normal mode of operation, this bitmask

specify which channels belong to group A.

stored

to trigger scan

number of sampling iterations of data has

Table 6. Configuration Settings for the ADC HAL Module on r_adc

Default: Enabled

12-Bit, 10-Bit (S7G2 Only),
8-Bit (S7G2 Only)

Default: Right

Default: On

Normal/Group A, Use in
Group B
Default: Unused

included in the build

has two units; 0 and 1.

automatically cleared after the conversion
result is read.

Note: If this is enabled, then watching the

result register using a debugger always

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

(S3A7/S124 Only)

(S3A7 Only)

R30AN0312EU0120 Rev.1.20 Page 6 of 18
Apr.29.19

Normal/Group A, Use in
Group B
Default: Unused

Normal/Group A, Use in
Group B
Default: Unused

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

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