Synergy Software Package User's Manual
OPAMP Driver

Table of Contents

OPAMP HAL Module Introduction

The OPAMP HAL module provides a high level API for signal amplification applications and supports the OPAMP peripheral available on Synergy MCUs.

OPAMP HAL Module Features

  • Low power or high-speed mode
  • Start by software or AGT compare match
  • Stop by software or ADC conversion end (stop by ADC conversion end only supported on op-amp channels configured to start by AGT compare match)
  • Trimming available on some MCUs (see hardware manual)
OPAMP_BD.png
OPAMP HAL Module Block Diagram

OPAMP Hardware Support Details

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

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 

 

MCU Group Low power mode High speed mode Start by SW AGT compare match Stop by SW ADC conversion end
S124 N/A N/A N/A N/A N/A N/A
S128 ✓ ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓ ✓
S5D3 N/A N/A N/A N/A N/A N/A
S5D5 N/A N/A N/A N/A N/A N/A
S5D9 N/A N/A N/A N/A N/A N/A
S7G2 N/A N/A N/A N/A N/A N/A

OPAMP HAL Module APIs Overview

The OPAMP HAL module defines API functions to open, start, stop, read status, trim and close the 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.

OPAMP HAL Module API Summary

Function Name Example API Call and Description
open g_opamp0.p_api->open(g_opamp0.p_ctrl, g_opamp0.p_cfg);
Applies power to the OPAMP and initializes the hardware based on the user configuration.
start g_opamp0.p_api->start(g_opamp0.p_ctrl, channel_mask);
If the OPAMP is configured for hardware triggers, enables hardware triggers.  Otherwise, starts the op-amp.
stop g_opamp0.p_api->stop(g_opamp0.p_ctrl, channel_mask);
Stops the op-amp. If the OPAMP is configured for hardware triggers, disables hardware triggers.
trim g_opamp0.p_api->trim(g_opamp0.p_ctrl, cmd, p_args);
On MCUs that support trimming, the op-amp trim register is set to the factory default after open(). This function allows the application to trim the operational amplifier to a user setting, which overwrites the factory default factory trim values. See Operational Notes for important details.
infoGet g_opamp0.p_api->infoGet(g_opamp0.p_ctrl, p_info);
Provides the minimum stabilization wait time in microseconds.
statusGet g_opamp0.p_api->statusGet(g_opamp0.p_ctrl, p_status);
Provides the operating status for each op-amp in a bitmask. This bit is set when operation begins, before the stabilization wait time has elapsed.
close g_opamp0.p_api-> close(g_opamp0.p_ctrl);
Stops the op-amps.
versionGet g_opamp0.p_api->versionGet(&version);
Retrieve the module version using 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 An input pointer is NULL.
SSP_ERR_IN_USE Peripheral is in use or hardware lock is taken.
SSP_ERR_INVALID_POINTER The parameter p_data is NULL.
SSP_ERR_INVALID_STATE The command is not valid for the current state of the trim function.
SSP_ERR_INVALID_MODE Trim is not allowed in low power mode.
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.

OPAMP HAL Module Operational Overview

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

OPAMP HAL Module Important Operational Notes and Limitations

OPAMP HAL Module Operational Notes

Trimming the OPAMP

On MCUs that support trimming, the op-amp trim register is set to the factory default after the opamp_api_t::open API is called).

This function allows the application to trim the operational amplifier to a user setting, which overwrites the factory default factory trim values.

Not supported on all MCUs. See hardware manual for details. Not supported if configured for low power mode (OPAMP_MODE_LOW_POWER).

This function is not reentrant.  Only one side of one op-amp can be trimmed at a time. Complete the procedure for one side of one channel before calling the opamp_api_t::trim API with the command OPAMP_TRIM_CMD_START again.

The trim procedure works as follows:

  • Call the opamp_api_t::trim API for the Pch (+) side input with command OPAMP_TRIM_CMD_START.
  • Connect a fixed voltage to the Pch (+) input.
  • Connect the Nch (-) input to the op-amp output to create a voltage follower.
  • Ensure the op-amp is operating and stabilized.
  • Call the opamp_api_t::trim API for the Pch (+) side input with command OPAMP_TRIM_CMD_START.
  • Measure the fixed voltage connected to the Pch (+) input using the SAR ADC and save the value (referred to as A later in this procedure).
  • Iterate over the following loop 5 times:
    • Call the opamp_api_t::trim API for the Pch (+) side input with command OPAMP_TRIM_CMD_NEXT_STEP.
    • Measure the op-amp output using the SAR ADC (referred to as B in the next step).
    • If A <= B, call the opamp_api_t::trim API for the Pch (+) side input with command OPAMP_TRIM_CMD_CLEAR_BIT.
  • Call the opamp_api_t::trim API for the Nch (-) side input with command OPAMP_TRIM_CMD_START.
  • Measure the fixed voltage connected to the Pch (+) input using the SAR ADC and save the value (referred to as A later in this procedure).
  • Iterate over the following loop 5 times:
    • Call the opamp_api_t::trim API for the Nch (-) side input with command OPAMP_TRIM_CMD_NEXT_STEP.
    • Measure the op-amp output using the SAR ADC (referred to as B in the next step).
    • If A <= B, call the opamp_api_t::trim API for the Nch (-) side input with command OPAMP_TRIM_CMD_CLEAR_BIT.

The following status return values are associated with the opamp_api_t::trim API:

SSP_SUCCESS Conversion result in p_data
SSP_ERR_UNSUPPORTED Trimming is not supported on this MCU.
SSP_ERR_INVALID_STATE The command is not valid in the current state of the trim state machine.
SSP_ERR_INVALID_ARGUMENT The requested channel is not operating or the trim procedure is not in progress for this channel/input combination.
SSP_ERR_INVALID_MODE Trim is not allowed in low power mode.
SSP_ERR_ASSERTION An input pointer was NULL.
SSP_ERR_NOT_OPEN Instance control block is not open. Trimming is not supported on all MCUs.

OPAMP HAL Module Limitations

This module only works for selected Synergy MCUs. Refer to 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 OPAMP HAL Module in an Application

This section describes how to include the OPAMP 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 OPAMP 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 OPAMP Driver is g_opamp0. This name can be changed in the associated Properties window.)

OPAMP HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_opamp0 OPAMP Driver on r_opamp Threads New Stack> Driver> Analog> OPAMP Driver on r_opamp

When the OPAMP Driver on r_opamp 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.

OPAMP_MS.png
OPAMP HAL Module Stack

Configuring the OPAMP HAL Module

The OPAMP 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 OPAMP HAL Module on r_opamp

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable the parameter error checking.
Name g_opamp Module name.
AGT Start Trigger Configuration (N/A unless AGT Start Trigger is Selected for the Channel) AGT1 Compare Match Starts OPAMPs 0 and 2 if configured for AGT Start/AGT0 Compare Match Starts OMPAMPs 1 and 3 if configured for AGT Start, AGT1 Compare Match Starts OPAMPs 0 and 1 if configured for AGT Start/AGT0 Compare Match Starts OPAMPs 2 and 3 if configured for AGT Start, AGT1 Compare Match Starts all OPAMPs configured for AGT Start
Default: AGT1 Compare Match Starts all OPAMPs configured for AGT Start 		Configure which AGT channel event triggers op-amp channel. The AGT compare match event only starts the op-amp channel if the AGT Start trigger is selected in the Trigger configuration for the channel.
Power Mode Low Power, Middle Speed, High Speed
Default: High Speed 		Configure the op-amp based on power or speed requirements. This setting affects the minimum required stabilization time. Middle speed is not available for all MCUs.
Trigger Channel 0 Software Start Software Stop, AGT Start Software Stop, AGT Start ADC Stop
Default: Software Start Software Stop 		Select the event triggers to start or stop op-amp channel 0. If the event trigger is selected for start, the opamp_api_t::start API enables the event trigger for this channel. If the event trigger is selected for stop, the opamp_api_t::stop API disables the event trigger for this channel.
Trigger Channel 1 Software Start Software Stop, AGT Start Software Stop, AGT Start ADC Stop
Default: Software Start Software Stop 		Select the event triggers to start or stop op-amp channel 1. If the event trigger is selected for start, the opamp_api_t::start API enables the event trigger for this channel. If the event trigger is selected for stop, the opamp_api_t::stop API disables the event trigger for this channel.
Trigger Channel 2 Software Start Software Stop, AGT Start Software Stop, AGT Start ADC Stop
Default: Software Start Software Stop 		Select the event triggers to start or stop op-amp channel 2. If the event trigger is selected for start, the opamp_api_t::start API enables the event trigger for this channel. If the event trigger is selected for stop, the opamp_api_t::stop API disables the event trigger for this channel.
Trigger Channel 3 Software Start Software Stop, AGT Start Software Stop, AGT Start ADC Stop
Default: Software Start Software Stop 		Select the event triggers to start or stop op-amp channel 3. If the event trigger is selected for start, the opamp_api_t::start API enables the event trigger for this channel. If the event trigger is selected for stop, the opamp_api_t::stop API disables the event trigger for this channel.
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.

OPAMP HAL Module Clock Configuration

The OPAMP HAL module does not require a specific clock configuration.

OPAMP HAL Module Pin Configuration

To use the OPAMP 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 OPAMP HAL Module on r_opamp

Resource ISDE Tab Pin selection Sequence
OPAMP Pins Select Peripherals> Analog: OPAMP 0/1/2

Using the OPAMP HAL Module in an Application

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

  1. Initialize the OPAMP module using the opamp_api_t::open API.
    Note
    Before starting any op-amp, consult the hardware manual to determine if the MCU used has internal connections switches in the OPAMP peripheral.  If the OPAMP peripheral does have internal connection switches, configure the internal connections by setting the AMPnMS, AMPnPS, and AMP0OS registers directly.
  2. Start the OPAMP channel(s) using the desired trigger with the opamp_api_t::start API.
    Note
    If the AGT compare match start is used, this call enables the OPAMP to be triggered by the AGT compare match. If a software trigger is used, then this call starts the OPAMP channel(s).
  3. Wait for the OPAMP to stabilize.  The stabilization time can be found in the hardware manual or by using the opamp_api_t::infoGet API.
  4. Stop the OPAMP channel(s) by calling the opamp_api_t::stop API. (Optional)
    Note
    This stops the OPAMP regardless of if ADC conversion end triggers are enabled to stop the OPAMP.
  5. Close the module and power down the peripheral using the opamp_api_t::close API.

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

OPAMP_TA.png
Flow Diagram of a Typical OPAMP HAL Module Application