Comparator Driver on r_acmphs

Table of Contents

• ACMPHS HAL Module Introduction
  • ACMPHS HAL Module Features
  • ACMPHS Hardware support details
• ACMPHS HAL Module APIs Overview
• ACMPHS HAL Module Operational Overview
  • ACMPHS HAL Module Important Operational Notes and Limitations
    • ACMPHS HAL Module Operational Notes
    • ACMPHS HAL Module Limitations
• Including the ACMPHS HAL Module in an Application
• Configuring the ACMPHS HAL Module
  • ACMPHS HAL Module Clock Configuration
  • ACMPHS HAL Module Pin Configuration
• Using the ACMPHS HAL Module in an Application

ACMPHS HAL Module Introduction

The ACMPHS HAL module implements the comparator API for signal processing applications and supports the ACMPHS peripheral available on the Synergy microcontroller hardware. A callback is available to signal the user application on transition events.

ACMPHS HAL Module Features

• Callback on rising edge, falling edge or both
• Configurable debounce filter
• Option to include comparator output on VCOUT pin

ACMPHS HAL Module Block Diagram

ACMPHS Hardware support details

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

Legend:

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

MCU Group	Query HS Comparator result	Callback on rising edge, falling edge, or both	Configurable debounce filter	Option to include comparator output on VCOUT
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	✓	✓	✓	✓
S5D3	✓	✓	✓	✓
S5D5	✓	✓	✓	✓
S5D9	✓	✓	✓	✓
S7G2	✓	✓	✓	✓

ACMPHS HAL Module APIs Overview

The ACMPHS HAL module defines APIs to open, enable, get status 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.

ACMPHS HAL Module API Summary

Function Name	Example API Call and Description
open	g_comparator0.p_api->open(g_comparator0.p_ctrl, g_comparator0.p_cfg); Configures the comparator and starts operation. Callbacks and pin output are not active until outputEnable() is called. outputEnable() should be called after the output has stabilized.
outputEnable	g_comparator0.p_api->outputEnable(g_comparator0.p_ctrl); Enables the comparator output, which can be polled using statusGet(). Also enables pin output and interrupts as configured during open().
infoGet	g_comparator0.p_api->infoGet(g_comparator0.p_ctrl, p_info); Provides the minimum stabilization wait time in microseconds.
statusGet	g_comparator0.p_api->statusGet(g_comparator0.p_ctrl, p_status); Provides the operating status of the comparator.
close	g_comparator0.p_api->close(g_comparator0.p_ctrl); Close the module.
versionGet	g_comparator0.p_api->read(&version); Retrieves the 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_TIMEOUT	The debounce filter is off and 2 consecutive matching values were not read within 1024 attempts.

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.

ACMPHS HAL Module Operational Overview

The ACMPHS HAL module controls the high-speed analog comparator peripheral on a Synergy microcontroller. It directly controls the ACMPHS hardware without using any RTOS elements and provides convenient APIs to simplify development.

ACMPHS HAL Module Important Operational Notes and Limitations

ACMPHS HAL Module Operational Notes

Comparator Output on VCOUT Pin

The signal on the VCOUT pin is a logical 'OR' of the outputs of all comparators (ACMPHS and ACMPLP) with their output pin enabled.

Interrupts and Callbacks

When a comparator event occurs, the Comparator Driver on r_acmphs HAL module calls the callback (comparator_cfg_t::p_callback) with the callback argument (comparator_callback_args_t).

ACMPHS 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. The MCU Hardware Manual shows which peripherals are available.
• Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the ACMPHS HAL Module in an Application

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

ACMPHS HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_comparator0 Comparator Driver on r_acmphs	Threads	New Stack> Driver> Analog> Comparator Driver on r_acmphs

When the Comparator Driver on r_acmphs 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.

ACMPHS HAL Module Stack

Configuring the ACMPHS HAL Module

The ACMPHS 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 ACMPHS HAL Module on r_acmphs

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Controls whether to include code for API parameter checking.
Name	g_comparator	Module name.
Channel	0	Select the hardware channel.
Trigger Edge	Rising, Falling, Both Edge Default: Both Edge	The trigger specifies when a comparator callback event should occur. Unused if the interrupt priority is disabled or the callback is NULL.
Debounce Filter	No Filter, 8, 16, 32 Default: No Filter	Select the PCLK divisor for the hardware digital debounce filter. Larger divisors provide a longer debounce and take longer for the output to update.
Invert	Not Inverted, Inverted Default: Not Inverted	Turns this on to invest comparator output. This affects the output read from StatusGet(), the pin output level, and the edge trigger.
Pin Output	Disabled, Enabled Default: Disabled	Turn this on to include the output from this comparator on VCOUT. The comparator output on VCOUT is ORed with output from all other ACMPHS and ACMPLP comparators.
Callback	NULL	Define this function in the application. It is called when the Trigger event occurs.
Comparator Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Select the interrupt priority for the comparator interrupt.

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.

ACMPHS HAL Module Clock Configuration

The ACMPHS HAL module uses the PCLKB as its clock source.

To change the clock frequency at run-time, use the CGC Interface.

ACMPHS HAL Module Pin Configuration

To use the ACMPHS 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 ACMPHS HAL Module on r_acmphs

Resource	ISDE Tab	Pin selection Sequence
ACMPHS	Pins	Select Peripherals> Analog:ACMP

Using the ACMPHS HAL Module in an Application

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

1. Initialize the ACMPHSw using the comparator_api_t::open API.
2. Before enabling the output, consult the hardware manual to configure the internal connections by setting the COMPSELn registers directly.  If the internal reference voltage is used, set COMPMDR.CiVRF.
3. After configuring the modules and internal connections, wait for the minimum stabilization wait time before enabling output.  The minimum stabilization wait time can be queried using the comparator_api_t::infoGet API.
4. Enable the comparator output using the comparator_api_t::outputEnable API.  This enables pin output, interrupts and the comparator_api_t::statusGet API as configured during the comparator_api_t::open API call.
5. [Optional] Use the comparator_api_t::statusGet API to poll comparator status.
6. [Optional] Use the comparator_api_t::close API to disable the comparator and power down the peripheral.

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

Flow Diagram of a Typical ACMPHS HAL Module Application