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

Table of Contents

Audio Playback DAC Framework Introduction

The Audio Playback Framework DAC 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 DAC Framework uses the DAC/DAC8, 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 DAC Framework Module Features

  • Plays long buffers by splitting the data into manageable chunks.
  • Repeats playback until a 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.
  • Scaling, for example, to move signed 16-bit PCM data into range of the unsigned 12-bit or 8-bit DAC.
  • Basic mixing for multiple streams.
audio_playback_dac_BD.png
Audio Playback DAC Framework Module Block Diagram
Note
Selection options of DAC or DAC8 Driver is MCU specific.

Audio Playback DAC Framework Module APIs Overview

The Audio Playback DAC 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 DAC 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);
Store 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_ASSERTION A pointer is NULL or a parameter is invalid.
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_NOT_OPEN The stream control block p_ctrl is not initialized.
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 DAC Framework Module Operational Overview

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

audio_playback_dac_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 DAC 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 the following figure:

audio_playback_dac_AS.png
Audio Playback DAC Framework Implementing Multiple Audio Streams

Audio Playback DAC Framework Module Important Operational Notes and Limitations

Audio Playback DAC Framework Module Operational Notes

  • The Audio Framework DAC hardware port uses the transfer API to transfer audio data from a playback buffer to DAC at a sampling frequency defined by an internal timer.
  • The Audio Framework DAC hardware port has dependencies on the Timer, DAC/DAC8, and Transfer API modules.
  • Add a Timer module.
    • Set the Frequency in Hz to the sampling frequency of your audio data.
    • Enable the interrupt if using DTC as the transfer module (recommended).
  • Add a Transfer module: select either the DTC or DMAC.
  • For DTC:
    • Set Destination pointer to &R_DAC->DADRn[0] if using DAC channel 0 or &R_DAC->DADRn[1] if using DAC channel 1.
    • Set Destination pointer to &R_DAC8->DADRn[2] if using DAC8 channel 2 (S128) or &R_DAC8->DADRn[0] if using DAC8 channel 0 (S1JA).
    • Set the activation source to the timer interrupt chosen above.
  • For DMAC:
    • Enable the DMAC support
    • Set Destination pointer to &R_DAC->DADRn[0] if using DAC channel 0 or &R_DAC->DADRn[1] if using DAC channel 1.
    • Set Destination pointer to &R_DAC8->DADRn[2] if using DAC8 channel 2 (S128) or &R_DAC8->DADRn[0] if using DAC8 channel 0 (S1JA).
    • Set the activation source to the timer interrupt chosen above.
  • The Audio Playback DAC Framework is designed to support the following MCU families with no changes to the API:
    • S7G2
    • S3A3
    • S5D9
    • S3A7
    • S124
    • S3A6
    • S5D5
    • S3A1
    • S128
    • S1JA
    • S5D3

Audio Playback DAC Framework Module Limitations

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

Including the Audio Playback DAC Framework Module in an Application

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

Audio Playback DAC Framework Module Selection Sequence

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

When the Audio Playback DAC Framework module on sf_audio_playback_hw_dac 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_dac_MS.png
Audio Playback DAC Framework Module Stack
Note
Selection options of DAC or DAC8 Driver is MCU specific

Configuring the Audio Playback DAC Framework Module

The Audio Playback DAC 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 DAC Framework Module on sf_audio_playback_hw_dac

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
DMAC Support Disabled, Enabled

Default: Disabled 		DMAC support selection.
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 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 DAC 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 Transfer Driver on r_dmac 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.
Name g_transfer0 Module name.
Channel 0 Channel selection.
Mode Normal Mode selection.
Transfer Size 2 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.
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 Software Activation, Peripheral Events

Default: Software Activation 		Activation source selection.
Auto Enable False Auto enable selection.
Callback NULL Callback selection.
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 Transfer Driver on r_dmac Software Activation 1

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 selection.
Name g_transfer0 Module name.
Mode Normal Mode selection.
Transfer Size 2 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 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.
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 		Enables or disables the parameter checking.
Name g_timer0 Module name.
Channel 0 Channel selection.
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.
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 Set to true to start the timer after configuring or false to leave the timer stopped until timer_api_t::start is called.
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 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 		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 DAC HAL Module on r_dac

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enable or disable the parameter error checking.
Name g_dac0 Module name.
Channel 0 Set to 0 for output DA0 or 1 for output DA1.
Synchronize with ADC Enabled, Disabled

Default: Disabled 		Set to true for anti-interference synchronization with the Analog-to-Digital Converter (ADC) Module. Set to false if power supply interference between the analog modules is not a problem, or if asynchronous conversion by the DAC Module is desired.
Data Format Right Justified Set to zero, if 12-bit data values are loaded in bits 11 through 0, or right justified. Set to one, if 12-bit data values are loaded in bits 15 through 4, or left justified.
Output Amplifier Enable, Disable

Default: Disable 		Set to true, if output amplifier hardware function is desired. Set to false to bypass output amplifier hardware function.
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 DAC8 HAL Module r_dac8

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable the parameter error checking.
Name g_dac8_0 Module name.
Channel 0 Channel selection.
Synchronize with ADC Enabled, Disabled
Default: Disabled 		Choose whether to sync with the ADC module.
Data Format Right Justified Data format selection.
DAC Mode Normal Mode, Real-time (Event Link) Mode
Default: Normal Mode 		DAC mode selection.
Charge Pump Enabled (Requires MOCO active) Enabled, Disabled
Default: Enabled 		Enable or disable the charge pump.
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 DAC Framework Module Clock Configuration

The Audio Playback DAC Framework hardware modules use the peripheral clocks available in the Clocks configuration window.

Audio Playback DAC Framework Module Pin Configuration

The DAC or 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 show an example selection for the associated pins.

Note
For some peripherals, the operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection Sequence for the Audio Playback DAC Framework Module

Resource ISDE Tab Pin selection Sequence
DAC Pins Select Peripherals > Analog:DAC12 > DAC120/121
SSI Pins Select Peripherals > Connectivity:SSI > SSI/0/1
Note
The selection sequence assumes the DAC0/DAC1 or the SSI0/SSI1 is the desired hardware target of the driver.

Pin Configuration Settings for the DAC HAL Module on r_dac

Pin Configuration Property Value Description
Operation Mode Enabled, Disabled Operation selection.
DAC None, P014

Default: P014 		DAC 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 DAC Framework Module in an Application

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

  1. Initialize the Audio Playback DAC Framework using the sf_audio_playback_hw_api_t::open API
  2. Start the low level hardware of the Audio Playback DAC 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 DAC Framework using sf_audio_playback_hw_api_t::stop API.
  6. Close the Audio Playback DAC 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_dac_TA.png
Flow Diagram of a Typical Audio Playback DAC Framework Module Application