Synergy Software Package User's Manual
Clock Accurate Circuit Driver

Table of Contents

CAC HAL Module Introduction

The CAC HAL module provides a high-level API for clock accuracy control applications and uses the Clock Frequency Accuracy Measurement Circuit (CAC) peripheral on a Synergy MCU. This is particularly useful function when implementing a fail-safe mechanism for reliability-oriented applications. A user-defined callback can be created to respond to various error indications.

CAC HAL Module Features

  • Supports clock frequency-measurement and monitoring based on a reference signal input.
  • Reference can be either an externally supplied clock source or an internal clock sources.
  • An interrupt request may optionally be generated by a completed measurement, a detected frequency error, or a counter overflow.
  • A digital filter is available for an externally supplied reference clock, and dividers are available for both internally supplied measurement and reference clocks.
  • Edge-detection options for the reference clock are configurable as rising, falling, or both.
CAC_BD.png
CAC HAL Module Block Diagram

CAC Hardware support details

The following hardware features are, or are not, supported by SSP for the CAC.

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU
Group 		Measurement
Clock Targets:
Main Clock
Oscillator 		Measurement
Clock Targets:
Sub-Clock
Oscillator 		Measurement
Clock
Targets:
HOCO Clock 		Measurement
Clock
Targets:
MOCO Clock 		Measurement
Clock Targets:
LOCO Clock
S124 ✓ ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓
MCU
Group 		Measurement
Clock
Targets:
IWDTCLK 		Measurement
Clock Targets:
Peripheral
Module Clock B 		Measurement
Reference
Clocks:
External clock
input to the
CACREF pin 		Measurement
Reference
Clocks: Main
Clock
Oscillator 		Measurement
Reference
Clocks: Sub-
Clock
Oscillator
S124 ✓ ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓
MCU
Group 		Measurement
Reference
Clocks:
HOCO Clock 		Measurement
Reference
Clocks:
MOCO Clock 		Measurement
Reference
Clocks:
LOCO Clock 		Measurement
Reference
Clocks:
IWDTCLK
Clock 		Measurement
Reference Clocks:
Peripheral Module
Clock B
S124 ✓ ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓
MCU
Group 		Selectable
Function:
Digital Filter 		Interrupt
Sources:
Measurement
End 		Interrupt
Sources:
Frequency
Error 		Interrupt
Sources:
Overflow 		Module-stop function to
reduce power
consumption
S124 ✓ ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓

CAC HAL Module APIs Overview

The CAC HAL module defines APIs for opening, closing, reading, starting, stopping and resetting the CAC. 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.

CAC HAL Module API Summary

Function Name Example API Call and Description
open g_cac0.p_api->open(g_cac0.p_ctrl, g_cac0.p_cfg)
Open function for CAC device.
read g_cac0.p_api->read(g_cac0.p_ctrl, &cac0_status, &cac0_counter)
Read function for CAC peripheral.
close g_cac0.p_api->close(g_cac0.p_ctrl)
Close function for CAC device.
stopMeasurement g_cac0.p_api->stopMeasurement(g_cac0.p_ctrl)
Ends a measurement for the CAC peripheral.
startMeasurement g_cac0.p_api->startMeasurement(g_cac0.p_ctrl)
Begin a measurement for the CAC peripheral.
reset g_cac0.p_api->reset(g_cac0.p_ctrl)
Reset function for CAC device.
versionGet g_cac0.p_api->versionGet(&cac0_version)
Get the CAC API and code version information.
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 One or more configuration options are invalid
SSP_ERR_NOT_OPEN Open has not been successfully called
SSP_ERR_ASSERTION Null provided for p_ctrl, p_cfg and others
SSP_ERR_INVALID_POINTER Interrupt specified with NULL callback
SSP_ERR_HW_LOCKED Hardware lock for CAC peripheral is already taken
SSP_ERR_INVALID_CAC_REF_CLOCK Measured clock rate smaller than reference clock rate
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.

CAC HAL Module Operational Overview

The CAC HAL module API interfaces with a clock frequency-measurement circuit capable of monitoring the clock frequency based on a reference signal input. The reference signal may be an externally supplied clock source or one of several available internal clock sources. An interrupt request may optionally be generated by a completed measurement, a detected frequency error, or a counter overflow. A digital filter is available for an externally supplied reference clock, and dividers are available for both internally supplied measurement and reference clocks. Edge-detection options for the reference clock are configurable as rising, falling, or both.

The frequency of the following clocks can be measured:

  • Clock output from main-clock oscillator (main clock)
  • Clock output from sub-clock oscillator (sub clock)
  • Clock output from high-speed on-chip oscillator (HOCO clock)
  • Clock output from mid-speed on-chip oscillator (MOCO clock)
  • Clock output from low-speed on-chip oscillator (LOCO clock)
  • Clock output from IWDT-dedicated on-chip oscillator (IWDTCLK clock)
  • Peripheral module clock (PCLKB)

The measurement clock is monitored using a reference clock. The reference clock may be an external clock (supplied on the CACREF input pin) or one of the following internal clocks:

  • Clock output from main-clock oscillator (main clock)
  • Clock output from sub-clock oscillator (sub clock)
  • Clock output from high-speed on-chip oscillator (HOCO clock)
  • Clock output from mid-speed on-chip oscillator (MOCO clock)
  • Clock output from low-speed on-chip oscillator (LOCO clock)
  • Clock output from IWDT-dedicated on-chip oscillator (IWDTCLK clock)
  • Peripheral module clock (PCLKB)

Operational Description

The CAC HAL module measures the operation and accuracy of a selected clock. Once the measurement is requested, counting begins on the first valid edge detected for the reference clock and ends on the next valid edge. A valid edge can be configured to be rising, falling, or both. The count is incremented at each cycle of the measurement clock after it has passed through the divider circuit which is capable of dividing the clock by 1, 4, 8, or 32. An internally supplied reference clock also passes through a divider circuit which is capable of dividing the clock by 32, 128, 1024, or 8192. An externally supplied reference clock does not pass through a divider circuit, but may pass through a digital filter if it is configured to do so.

For example, if the sub-clock is specified as the measurement clock (32 kHz) and a divisor of 1 is specified, then the counter will increment at a 32 kHz rate. If a reference clock of 1 kHz is provided, then after one cycle of the reference clock you would expect the counter to be 32. This is where the CAC upper and lower-limit settings are examined. Part of the setup for a CAC measurement is the specification of an upper and lower limit for the measurement. When a measurement is complete, the CAC compares the counter contents to the limits configured for the measurement. If both the counter ≤ upper limit and the counter ≥ lower limit, then the measurement has completed without error and the measured frequency is operating within the defined limits. If the counter fails to meet these requirements, then a frequency error is indicated. A completed measurement may be identified by making API calls to poll the driver, or by establishing a callback function.

CAC HAL Module Important Operational Notes and Limitations

CAC HAL Module Operational Notes

Continuous Mode

The CAC module may be operated in either a single or continuous measurement mode. In continuous mode, the measuring process is restarted after each completed measurement. In non-continuous, or single measurement mode, measuring stops after the first completed measurement. The cac_cfg_t::continuous_mode configuration member controls this feature.

Interrupts and Callbacks

When a measurement is complete and a callback is provided by the user, (with one or more interrupts enabled) the CAC HAL module invokes the callback (cac_cfg_t::p_callback) with the argument cac_callback_args_t, indicating the event cac_event_t. If interrupts are not enabled, the API supports checking the measurement status to poll if the measurement is complete (cac_api_t::read), which will provide both the status of the measurement and the current value of the CAC counter register.

The CAC driver supports three interrupts:

  • A frequency error interrupt occurs when a measurement completes and the CAC counter register value is outside of the range that was specified as part of the cac_api_t::open call. The configuration cac_cfg_t::ferr_interrupt_enabled member provided in the cac_api_t::open call must be enabled for this interrupt to be generated.
  • An overflow error interrupt occurs when the CAC counter register overflows its maximum (0xFFFF) value. The configuration cac_cfg_t::ovf_interrupt_enabled member provided in the cac_api_t::open call must be enabled for this interrupt to be generated.
  • A measurement complete interrupt occurs when a measurement completes and the CAC counter register value is within the range that was specified as part of the CAC driver cac_api_t::open. The configuration cac_cfg_t::mei_interrupt_enabled member provided in the cac_api_t::open call must be enabled for this interrupt to be generated.

Reset

The cac_api_t::reset API can be used to reset the overflow, measurement end and frequency error interrupt flags after measurement has been stopped to eliminate any false triggers.

CAC HAL Module Limitations

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

Including the CAC HAL Module in an Application

This section describes how to include the CAC 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 Clock Accuracy Circuit 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 Clock Accuracy Circuit Driver is g_cac0. This name can be changed in the associated Properties window.)

CAC 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 Clock Accuracy Circuit Driver on r_cac 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.

CAC_MS.png
CAC HAL Module Stack

Configuring the CAC HAL Module

The CAC 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 CAC HAL Module on r_cac

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Controls whether to include code for API parameter checking.
Name g_cac0 Identifies this instance.
Continuous Measurement Operation Enabled, Disabled

Default: Enabled 		If Enabled, measurement will continuously restart after completing.
Measurement Complete Interrupt Enabled, Disabled

Default: Enabled 		Enabling allows the CAC driver to generate an interrupt when a measurement is complete, providing the CAC MEASUREMENT END interrupt is enabled in the ICU.
Overflow Interrupt Enabled, Disabled

Default: Enabled 		Enabling allows the CAC driver to generate an interrupt when a CAC overflow occurs, providing the CAC OVERFLOW interrupt is enabled in the ICU.
Frequency Error Interrupt Enabled, Disabled

Default: Enabled 		Enabling allows the CAC driver to generate an interrupt when a frequency error occurs, providing the CAC FREQUENCY ERROR interrupt is enabled in the ICU.
Upper Limit Threshold 0 Top end of allowable range for measurement complete.
Lower Limit Threshold 0 Bottom end of allowable range for measurement complete.
Reference Clock Source Main Oscillator, Sub-clock, HOCO, MOCO, LOCO, PCLKB, IWDT

Default: Main Oscillator 		Reference clock source.
Reference Clock Divider 32,128,1024,8192

Default:32 		Reference clock divider.
Reference Clock Edge Detect Rising, Falling, Both

Default: Rising 		Reference clock edge detection.
Reference Clock Digital Filter Disabled, Sampling clock = measuring frequency, Sampling clock = measuring/4, Sampling clock = measuring/16

Default: Disabled 		Reference clock digital filter.
Measurement Clock Source Main Oscillator, Sub-clock, HOCO, MOCO, LOCO, PCLKB, IWDT

Default: HOCO 		Measurement clock source.
Measurement Clock Divider 1,4,8,32

Default: 1 		Measurement clock divider.
Callback NULL Function name for callback.
Frequency Error Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		CAC Frequency Error interrupt priority selection.
Measurement End Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		CAC Measurement End interrupt priority selection.
Overflow Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		CAC Overflow 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.

CAC HAL Module Clock Configuration

Clocks are selected from the Clock tab as needed by the application.

CAC HAL Module Pin Configuration

The pins for the CAC HAL module are selected as shown in the following table; the pin settings are shown in the subsequent table. If CACREF is used to the input pin of reference clock, you must configure this pin.

Pin Selection for the CAC HAL Module on r_cac

Resource ISDE Tab Pin selection Sequence
CAC HAL Module Pins Peripherals> Monitoring: CAC> CAC0
Note
The selection sequence assumes CAC0 is the desired hardware target for the driver

Pin Configuration Settings for the CAC HAL Module

Pin Configuration Property Value Description
Operation Mode Disabled, External Reference

Default: Disabled 		Select Enable as the Operation Mode for CAC.
CACREF: None, P204

Default: None 		CACREF Pin.
Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 kit. Other Synergy kits and MCUs may have different available pin configuration settings.

Using the CAC HAL Module in an Application

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

  1. Start reference clock and measurement clock using the CGC cgc_api_t::clockStart API if needed.
    1. For started clock, use the CGC cgc_api_t::clockCheck API to confirm oscillation stability or active state.
  2. Get the API and code version information using the cac_api_t::versionGet if needed.
  3. Initialize the CAC HAL module using the cac_api_t::open API.
  4. Start a measurement using the cac_api_t::startMeasurement API.
  5. Poll using the cac_api_t::read function to look for the measurement result or get measurement status and result using callback function called in ISR.
  6. Stop the measurement using the cac_api_t::stopMeasurement API.
  7. Reset the overflow, measurement end, and frequency error interrupt flags using the cac_api_t::reset API.
  8. Close the CAC HAL module if no more measurements are needed using the cac_api_t::close API.

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

CAC_TA.png
Flow Diagram of a Typical CAC HAL Module Application