Synergy Software Package User's Manual
SDADC Driver

Table of Contents

SDADC HAL Module Introduction

The SDADC HAL module provides a high level API for analog-to-digital conversions and supports the SDADC24 24-bit analog-to-digital converter peripheral available on the Synergy microcontroller hardware. A user-defined callback can be created to process the data each time a new sample is available.

SDADC HAL Module Features

  • 24-bit sigma delta A/D Converter
  • Single scan or continuous scan operation mode
  • Single-ended or differential input
  • Gain of up to 32 on differential inputs
  • Oversampling ratio configurable on differential inputs
SDADC_BD.png
SDADC HAL Module Block Diagram

SDADC Hardware Support Details

The following hardware features are, or are not, supported by SSP for SDADC:

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU Group Support for all Analog Channels 24-Bit Single-scan Mode Continuous-scan mode
S124 N/A N/A N/A N/A
S128 N/A N/A N/A N/A
S1JA ✓ ✓ ✓ ✓
S3A1 N/A N/A N/A N/A
S3A3 N/A N/A N/A N/A
S3A6 N/A N/A N/A N/A
S3A7 N/A N/A N/A N/A
S5D3 N/A N/A N/A N/A
S5D5 N/A N/A N/A N/A
S5D9 N/A N/A N/A N/A
S7G2 N/A N/A N/A N/A
MCU Group Single-ended input Differential input Programmable Gain Amplifier Configurable oversampling ratio
S124 N/A N/A N/A N/A
S128 N/A N/A N/A N/A
S1JA ✓ ✓ ✓ ✓
S3A1 N/A N/A N/A N/A
S3A3 N/A N/A N/A N/A
S3A6 N/A N/A N/A N/A
S3A7 N/A N/A N/A N/A
S5D3 N/A N/A N/A N/A
S5D5 N/A N/A N/A N/A
S5D9 N/A N/A N/A N/A
S7G2 N/A N/A N/A N/A

SDADC HAL Module APIs Overview

The SDADC HAL module defines API functions to open, configure scans, start scans, stop scans, read the conversion results the ADC scans and close the ADC unit. 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.

SDADC HAL Module API Summary

Function Name Example API Call and Description
open g_adc.p_api->open(g_adc.p_ctrl, g_adc.p_cfg);
Initialize ADC unit; apply power, set the operational mode, trigger sources, interrupt priority, and configurations common to all channels and sensors.
scanCfg g_adc.p_api->scanCfg(g_adc.p_ctrl, g_adc.p_channel_cfg);
Configure the scan including the channels, groups and scan triggers to be used for the unit that was initialized in the open call.
scanStart g_adc.p_api->scanStart(g_adc.p_ctrl);
Start the scan (in case of a software trigger), or enable the hardware trigger.
scanStop g_adc.p_api->scanStop(g_adc.p_ctrl);
Stop the ADC scan (in case of a software trigger), or disable the hardware trigger.
scanStatusGet g_adc.p_api->scanStatusGet(g_adc.p_ctrl);
Check scan status.
read g_adc.p_api->read(g_adc.p_ctrl, ADC_REG_CHANNEL_13, &adc_data);
Read ADC conversion result.
read32 g_adc.p_api->read32(g_adc.p_ctrl, ADC_REG_CHANNEL_13, &adc_data);
Read ADC conversion result into a 32-bit word.
sampleStateCountSet g_adc.p_api-> sampleStateCountSet(g_adc.p_ctrl,&adc_sample);
Set the sample state count for the specified channel.
calibrate g_adc.p_api-> calibrate(g_adc.p_ctrl, reg_id, offset);
Calibrate ADC or associated PGA (programmable gain amplifier).  The driver may require implementation specific arguments to the p_extend input.
offsetSet g_adc.p_api-> offsetSet(g_adc.p_ctrl, p_extend);
Set offset for input PGA configured for differential input.
close g_adc.p_api->close(g_adc.p_ctrl);
Close the specified ADC unit by ending any scan in progress, disabling interrupts, and removing power to the specified A/D unit.
infoGet g_adc.p_api->infoGet(g_adc.p_ctrl, &adc_info);
Return the ADC data register address of the first (lowest number) channel and the total number of bytes to be read for the DTC/DMAC to read the conversion results of all configured channels.
versionGet g_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_ARGUMENT Parameter has invalid value.
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 R_ADC_Close first.
SSP_ERR_INVALID_POINTER The parameter p_data is NULL.
SSP_ERR_CALIBRATION_FAILED Calibration failed.
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.

SDADC HAL Module Operational Overview

The SDADC HAL module controls the SDADC peripheral on a Synergy microcontroller. It directly controls the SDADC hardware without using any RTOS elements and provides convenient APIs to simplify development.

In this document, the term 'scan' refers to the AUTOSCAN feature of the SDADC, which works as follows:

  1. Conversions are performed on enabled channels in ascending order of channel number.  All conversions required for a single channel are completed before the sequencer moves to the next channel.
  2. Conversions are performed at the rate (in Hz) of the SDADC oversampling clock frequency / oversampling ratio (configured per channel).  The SSP uses the normal mode SDADC oversampling clock frequency.
  3. If averaging is enabled for the channel, the number of conversions to average are performed before each conversion end interrupt occurs.
  4. If the number of conversions for the channel is more than 1, performs the number of conversions requested.  If averaging is enabled for the channel, each averaged result counts as a single conversion.
  5. Continues to the next enabled channel only after completing all conversions requested.
  6. After all enabled channels are scanned, a scan end interrupt occurs.

The driver supports single-scan and continuous scan operation modes. 

  • Single-scan mode performs one scan per trigger (hardware trigger or software start using adc_api_t::scanStart).
  • In continuous scan mode, the scan is restarted after each scan completes.  A single trigger is required to start continuous operation of the SDADC.

Interrupts and Callbacks

When a conversion is complete and a callback is provided by the user, the SDADC HAL module calls the callback (adc_cfg_t::p_callback) with the argument adc_callback_args_t, indicating the unit and the event adc_cb_event_t.

The SDADC driver supports the following callback events:

  • ADC_EVENT_CONVERSION_COMPLETE to notify the application that new conversion data is available.
  • ADC_EVENT_SCAN_COMPLETE to notify the application when a scan is complete.
  • ADC_EVENT_CALIBRATION_COMPLETE to notify the application that the calibration process is complete.

SDADC HAL Module Important Operational Notes and Limitations

SDADC HAL Module Operational Notes

Triggering a Data Transfer with the SDADC

To trigger a transfer of data when the SDADC scan completes, configure the data transfer with transfer_cfg_t::activation_source set to ELC_EVENT_SDADCn_SCAN_END. The ELC events are listed under elc_event_t. To retrieve the SDADC specific information to use with the Transfer Interface API, use the adc_api_t::infoGet function call.

Triggering ELC Events with the SDADC

The SDADC unit can trigger the start of other peripherals listed in elc_peripheral_t. Refer to the "ELC Interface" in the SSP User's Manual for more information.

SDADC HAL Module Limitations

This module only works for selected Synergy MCUs. Consult the release notes for your current SSP release to see which MCUs are supported by this module. Additionally, the MCU Hardware Manual shows which peripherals are available.

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

Including the SDADC HAL Module in an Application

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

SDADC HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sdadc0 SDADC Driver on r_adc Threads New Stack> Driver> Analog> SDADC Driver on r_sdadc

When the SDADC Driver on r_sdadc 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.

SDADC_MS.png
SDADC HAL Module Stack

Configuring the SDADC HAL Module

The SDADC HAL 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 SDADC HAL Module on r_sdadc

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable parameter error checking.
Name g_adc0 Module name.
Mode Single Scan, Continuous Scan
Default: Continuous Scan 		In single scan mode, all channels are converted once per start trigger, and conversion stops after all enabled channels are scanned. In continuous scan mode, conversion starts after a start trigger, then continues until stopped in software.
Resolution 16 Bit, 24 Bit
Default: 24 Bit 		Select 24-bit or 16-bit resolution.
Alignment Right, Left
Default: Right 		Select left or right alignment.
Trigger ELC Hardware Event, Software
Default: Software 		Select conversion start trigger. Conversion can be started in software, or conversion can be started when a hardware event occurs if the hardware event is linked to the SDADC peripheral using the ELC API.
Vref Source Internal, External
Default: Internal 		Vref can be sourced internally and output on the SBIAS pin, or Vref can be input from VREFI.
Vref Voltage 0.8V, 1.0V, 1.2V, 1.4V, 1.6V, 1.8V, 2.0V, 2.2V, 2.4V
Default: 1.0V 		Select Vref voltage. If Vref is input externally, the voltage on VREFI must match the voltage selected within 3%.
Internal Calibration During Open() Enabled, Disabled
Default: Enabled 		Calibration is required for all channels configured for differential input. Internal calibration is performed automatically during open for these channels unless it is disabled here.
Callback NULL Enter the name of the callback function to be called when conversion completes or a scan ends.
Conversion End Interrupt Priority Priority 0 (highest), Priority 1, Priority 2, Priority 3 (lowest - not valid if using ThreadX)
Default: Priority 2 		Select the interrupt priority for the conversion end interrupt. [Required]
Scan End Interrupt Priority Priority 0 (highest), Priority 1, Priority 2, Priority 3 (lowest - not valid if using ThreadX), Disabled
Default: Disabled 		Select the interrupt priority for the scan end interrupt. [Required]
Calibration End Interrupt Priority Priority 0 (highest), Priority 1, Priority 2, Priority 3 (lowest - not valid if using ThreadX), Disabled
Default: Disabled 		Select the interrupt priority for the calibration end interrupt. [Required]
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.

SDADC HAL Module Clock Configuration

The SDADC HAL module uses the SDADCCLK as its clock source and it must be set to 4 MHz.

SDADC HAL Module Pin Configuration

To use the SDADC HAL module, the port pins for the channels receiving the analog input must be set as input pins in the pin configurator in the ISDE. The following table illustrates the method for selecting the pins within the ISDE configuration window:

Pin Selection for the SDADC HAL Module on r_sdadc

Resource ISDE Tab Pin selection Sequence
SDADC Pins Select Peripherals> Analog:SDADC> SDADCn, where n is the channel number.

Using the SDADC HAL Module in an Application

The typical steps in using the SDADC HAL module in an application are:

  1. Initialize the SDADC using adc_api_t::open. Calibration is performed on all channels configured for differential input during this function unless calibration during open is disabled in the configuration.
  2. If calibration during open is disabled in the configuration, calibrate each channel configured for differential input using adc_api_t::calibrate. Wait for a calibration complete interrupt after calibrating each channel.  See R_SDADC_Calibrate for details regarding the calibration procedure.
  3. Configure active channels using adc_api_t::scanCfg. (Optional)
  4. Start a conversion using the desired trigger with adc_api_t::scanStart.
    1. If a hardware trigger is used, this call enables the ADC unit to be triggered by the hardware trigger. If a software trigger is used, then this call starts the ADC scan.
  5. The callback will be called after each conversion, and when the entire scan is complete.
  6. Read the results of the conversion using adc_api_t::read.
  7. Stop the ADC scan by calling adc_api_t::scanStop. (Optional)
    1. This prevents the ADC from being triggered by an external trigger or a hardware trigger; it also forces a stop of a software-triggered scan if one is ongoing.
  8. Operate on the received data as needed by the application.
  9. Close the module and power down the peripheral using the adc_api_t::close API.

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

SDADC_TA.png
Flow Diagram of a Typical SDADC HAL Module Application