Synergy Software Package User's Manual
Low Voltage Detection Driver

Table of Contents

LVD HAL Module Introduction

The Low Voltage Detection (LVD) HAL module provides a high-level API for voltage-detection applications and uses the LVD peripheral on the Synergy MCU. A user-defined callback can be created to notify the CPU when a voltage-detection event is triggered. The VCC is the source for all voltage-detection functions.

LVD HAL Module Features

The LVD HAL module supports the following functions:

  • VCC as the voltage-detection input
  • One build-time configurable low-voltage detector (via OFS1 register)
  • Two run-time configurable low-voltage detectors
  • Two result flags; one for a threshold check and one for the current state
  • Support for both interrupt or polling-event checking
LVD_BD.png
LVD HAL Module Block Diagram

LVD Hardware support details

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

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU Group VCC Rising
voltage
generates an
interrupt or
non maskable
interrupt 		VCC Falling
voltage
generates an
interrupt or
non-maskable
interrupt 		VCC Rising
and falling
voltage
generates an
interrupt or
non-maskable
interrupt 		Callback
notification
for
maskable
and non maskable
interrupt 		Reset on
falling
voltage 		Monitoring
LVD 1 and
2 status
flags by
polling
S124 ✓ ✓ ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓ ✓
MCU Group Digital Filtering with adjustable filter
time 		Event link function through ELC HAL driver
S124 N/A ⌧
S128 N/A ⌧
S1JA N/A ⌧
S3A1 N/A ⌧
S3A3 N/A ⌧
S3A6 N/A ⌧
S3A7 N/A ⌧
S5D3 ✓ ⌧
S5D5 ✓ ⌧
S5D9 ✓ ⌧
S7G2 ✓ ⌧

LVD HAL Module APIs Overview

The LVD HAL module defines APIs for opening, closing, statusGet and statusClear. The following table includes a complete list of the available APIs, an example API call and a short description of each API. A table of status return values follows the API summary table.

LVD HAL Module API Summary

Function Name Example API Call and Description
open g_lvd.p_api->open(g_lvd.p_ctrl, g_lvd.p_cfg;
Initializes a low voltage detection driver according to the passed in configuration structure. Enables an LVD peripheral based on configuration structure.
StatusGet g_lvd.p_api->statusGet(g_lvd.p_ctrl, &monitor_status);
Get the current state of the monitor, (threshold crossing detected, voltage currently within range) Can be used to poll the state of the LVD monitor at any time. Must be used if the peripheral was initialized with the lvd_response_tset to LVD_RESPONSE_NONE.
StatusClear g_lvd.p_api->statusClear(g_lvd.p_ctrl);
Clears the latched status of the monitor. Must be used if the peripheral was initialized with lvd_response_t set to LVD_RESPONSE_NONE.
close g_lvd.p_api->close(g_lvd.p_ctrl, g_lvd.p_cfg);
Disables the LVD peripheral. Closes the driver instance.
versionGet g_lvd.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_IN_USE Driver already open or unable to acquire hardware lock.
SSP_ERR_NOT_OPEN Unit is not open.
SSP_ERR_ASSERTION Invalid configuration value.
SSP_ERR_INVALID_MODE If the attempted mode is invalid for this configuration.
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.

LVD HAL Module Operational Overview

The LVD HAL module supports the configuration and operation of the LVD monitors in the Synergy MCUs. The LVD HAL module provides configuration structures that provide all the information needed to fully configure a single LVD monitor. One instance of the LVD HAL module is needed per instance of an LVD monitor, with the exception of the LVD0 monitor. The LVD0 monitor is not configurable at runtime and must be configured at compile time via the OFS1 register.

The LVD1 and LVD2 monitors are both configurable at runtime and are configured by this module. The lvd_api_t::open function allows the user to configure and enable an LVD monitor with a single function call; the lvd_api_t::close function disables the LVD monitor. The lvd_api_t::statusGet function returns the current status of the LVD monitor. The lvd_api_t::statusGet function should be used if the module is in polling mode, that is, without the LVD monitor interrupt enabled.

The monitor status consists of two flags. The first flag is a latched flag called lvd_status_t::crossing_detected, which indicates if the voltage being monitored has crossed the voltage threshold. In polling mode, this flag must be cleared via a call to lvd_api_t::statusClear. The flag does not need to be cleared explicitly if the LVD interrupt is in use, it will be cleared in the LVD interrupt by the driver code after the user-callback function is called. The second flag, lvd_status_t::current_state, is the instantaneous status of the monitored voltage with respect to the voltage threshold; this flag is not latched and will change as the monitored voltage changes.

The LVD HAL module can be configured to enable one or several of the LVD peripheral interrupts. If an interrupt is to be used, the user should provide a callback function for that monitor. Separate callback routines should be provided for each LVD monitor.

The LVD HAL module requires functionality provided by the BSP; this driver makes use of hardware locks provided by the BSP for register locks as well as enabling and clearing interrupts.

LVD HAL Module Important Operational Notes and Limitations

LVD HAL Module Operational Notes

  • Once the appropriate values are chosen for these settings, you should add the code to call the LVD HAL module lvd_api_t::open API function to your project. This function should be called once early in the application.
  • The module can be closed and reopened whenever the configuration of an LVD monitor needs to be changed. Calling the LVD lvd_api_t::open API function configures and enables the LVD hardware peripheral for the specified LVD monitor.
  • The close function disables the LVD monitor and closes the driver.
  • Using this module to configure the LVD peripheral to generate an interrupt requires the corresponding interrupt to be enabled in the module properties tab.
  • A callback function is not required when using the LVD interrupts, but is recommended.
  • A unique callback function for each LVD interrupt is not required, but is recommended.
  • Clock system initialization, configuration, and runtime modification are handled outside this module. This driver only makes changes to the digital filter sample clock based on the user's choice of sample clock divisor. The digital filter sample clock is derived from the LOCO system clock.
  • Not all voltage thresholds are available on all MCUs.
  • Digital filtering of the VCC input to the LVD monitor is not available on all MCUs.
  • The LVD driver requires functionality provided by the BSP; it makes use of hardware locks provided by the BSP for register locks as well as enabling and clearing interrupts.

LVD HAL Module Limitations

  • The process of configuring and enabling a Low Voltage Detection monitor has very specific timing constraints and register write ordering. Because of these constraints, the entire process of configuring and enabling a voltage monitor is most effectively performed by a single function. The open API function performs configuration and enables the monitor in order to properly enforce the timing and register write ordering constraints.
  • All series of Synergy microcontrollers have an Option-Setting Memory which can be used to set the operating state of peripherals after a reset. The OFS can be used to set the state of the IWDT, WDT, LVD, and CGC HOCO.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the LVD HAL Module in an Application

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

LVD HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_lvd Low Voltage Detection Driver on r_lvd Threads New Stack> Driver> Power> Low Voltage Detection Driver on r_lvd

When the LVD Driver on r_lvd 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.

LVD_MS.png
LVD HAL Module Stack

Configuring the LVD HAL Module

The LVD 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.

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 configuring interrupt priority levels.

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 LVD HAL Module on r_lvd

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enables or disables the parameter checking.
Name g_lvd Module name.
Monitor number 1 Monitor number selection.
Digital filter, enable by selecting a valid sample clock rate (S7G2 only). Digital filter is disabled, Digital filer is enabled (sampling clock is LOCO/2), Digital filer is enabled (sampling clock is LOCO/4), Digital filer is enabled (sampling clock is LOCO/8), Digital filer is enabled (sampling clock is LOCO/16)

Default: Digital filter is disabled 		Digital filter selection.
Voltage Threshold Default: 2.85V (Vdet1_13)(S7G2 only). Voltage threshold selection.
Detection Response, either reset, interrupt, non-maskable interrupt, or no response (polling mode). Maskable interrupt triggered when voltage crosses the detection threshold, Non-maskable interrupt triggered when voltage crosses the detection threshold, Reset MCU when voltage falls below the detection threshold, No response driver will be in polled mode (using statusGet and statusClear functions).

Default: Maskable interrupt triggered when voltage crosses the detection threshold 		Detection response selection.
Voltage slope, rising or falling or both Threshold crossing detected with decreasing voltage, Threshold crossing with increasing voltage, Threshold crossing detected with increasing or decreasing voltage

Default: Threshold crossing detected with decreasing voltage 		Indicates the direction of voltage change detection in relation to the threshold.
Negation of the monitor signal can be either be delayed from the reset event or from voltage returning to normal range Negation of reset signal is based on delay from reset, Negation of reset signal is based on delay from voltage returning to normal range

Default: Negation of reset signal is based on delay from reset 		Negation of the monitor signal selection.
Monitor Interrupt Callback NULL Monitor interrupt callback selection.
LVD Monitor Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		LVD monitor 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.

LVD HAL Module Clock Configuration

Clock system clock initialization, configuration, and runtime modification are handled outside this module. This module only makes changes to the digital filter sample clock based on the user's choice of sample clock divisor. The digital filter sample clock is derived from the LOCO system clock.

LVD HAL Module Pin Configuration

The LVD HAL module measures the voltage on the VCC pin only and does not need to be configured.

Using the LVD HAL Module in an Application

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

  1. Initialize the LVD HAL module using the lvd_api_t::open API.
  2. If using software polling, monitor the LVD status flags with the lvd_api_t::statusGet API and process accordingly. If using the interrupt mode, process accordingly within the callback function which will return both the monitor number as well as the status.
  3. Process as needed.
  4. Close the LVD Instance with the lvd_api_t::close API.

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

LVD_TA.png
Flow Diagram of a Typical LVD HAL Module Application