Synergy Software Package User's Manual
CGC Driver

Table of Contents

CGC HAL Module Introduction

The CGC HAL module provides a high-level API for clock-control applications and configures and controls the clock-control functions of a Synergy MCU using the clock-control peripheral. Since every project requires a clock function, the CGC HAL module is added to a project by default. (The module is configured in the ISDE.) A user-defined callback can be created to signal when the main oscillator has stopped.

CGC HAL Module Features

The CGC HAL module supports the configuration and control of the various clocking functions on the Synergy MCU. Key features include the following:

  • Selects the system clock source

• HOCO (high-speed on-chip oscillator), MOCO (middle-speed on-chip oscillator), LOCO (low-speed on-chip oscillator), Main Clock, PLL, or Sub-Oscillator

  • Configures internal clocks and turns them on or off
  • Configures the output clocks
  • Sets up the Oscillation Stop Detection feature
  • Sets up clock divisors on each of the up to six clock domains
  • Some Synergy MCUs also support controllable external clock outputs, which may have independent divisors
CGC_BD.png
CGC HAL Module Block Diagram

CGC Hardware support details

The following hardware features are, or are not, supported by SSP for the Clock Generation Circuit specifications for the clock sources.

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU
Group 		MOSC SOSC PLL Circuit HOCO MOCO LOCO
S124 ✓ ✓ N/A ✓ ✓ ✓
S128 ✓ ✓ N/A ✓ ✓ ✓
S1JA ✓ ✓ N/A ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓ ✓
MCU
Group 		IWDTLOCO JTAG External clock input SWD External
clock input 		Low Voltage
Operating Power
Control Mode
S124 ✓ N/A ⌧ ✓
S128 ✓ N/A ⌧ ✓
S1JA ✓ N/A ⌧ ✓
S3A1 ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ N/A
S5D5 ✓ ✓ ✓ N/A
S5D9 ✓ ✓ ✓ N/A
S7G2 ✓ ✓ ✓ N/A

CGC HAL Module APIs Overview

The CGC HAL module defines APIs for initializing, starting, controlling and stopping the MCU clock. A complete list of the available APIs, an example API call and a short description of each can be found in the following API Summary table. A table of status return values are listed after the API summary.

CGC HAL Module API Summary

Function Name Example API Call and Description
init g_cgc.p_api->init();
Initial clock configuration called by BSP automatically.
clocksCfg g_cgc.p_api->clocksCfg(&p_clock_cfg);
The BSP calls this function at startup, but it can also be called from the application to change clocks at runtime.
clockStart g_cgc.p_api->clockStart(clock_source, &p_clock_cfg);
Start a clock.
clockStop g_cgc.p_api->clockStop(clock_source);
Stop a clock.
systemClockSet g_cgc.p_api->systemClockSet(clock_source, &p_clock_cfg);
Set the system clock.
systemClockGet g_cgc.p_api->systemClockGet(&clock_source, &clock_config);
Get the system clock information.
systemClockFreqGet g_cgc.p_api->systemClockFreqGet(&clock_source, &frequency_hz);
Return the frequency of the selected clock.
clockCheck g_cgc.p_api->clockCheck(clock_source);
Check the stability of the selected clock.
oscStopDetect g_cgc.p_api->oscStopDetect(callback, enable);
Configure the Main Oscillator stop detection.
oscStopStatusClear g_cgc.p_api->oscStopStatusClear();
Clear the oscillator stop detection flag.
busClockOutCfg g_cgc.p_api->busClockOutCfg (divider);
Configure the bus clock output secondary divider. The primary divider is set using the BSP clock configuration and the systemClockSet function (S7G2 and S3A7 MCU only).
busClockOutEnable g_cgc.p_api->busClockOutEnable ();
Enable the bus clock output (S7G2 and S3A7 MCU only).
busClockOutDisable g_cgc.p_api->busClockOutDisable ();
Disable the bus clock output (S7G2 and S3A7 MCU only).
clockOutCfg g_cgc.p_api->clockOutCfg(clock_source, clock_dividers);
Configure clockOut.
clockOutEnable g_cgc.p_api->clockOutEnable();
Enable clock output on the CLKOUT pin. The source of the clock is controlled by clockOutCfg.
clockOutDisable g_cgc.p_api->clockOutDisable();
Disable clock output on the CLKOUT pin. The source of the clock is controlled by clockOutCfg.
lcdClockCfg g_cgc.p_api->lcdClockCfg(clock);
Configure the segment LCD Clock (S3A7 and S124 MCUs only).
lcdClockEnable g_cgc.p_api->lcdClockEnable();
Enable the LCD clock (S3A7 and S124 MCUs only).
lcdClockDisable g_cgc.p_api->lcdClockDisable();
Disables the LCD clock (S3A7 and S124 MCUs only).
sdadcClockCfg g_cgc.p_api->sdadcClockCfg(clock);
Configure the source for the SDADCCLK (S1JA only).
cgc_api_t::sdadcClockEnable g_cgc.p_api->sdadcClockEnable();
Enable the SDADCCLK output (S1JA only)
cgc_api_t::sdadcClockDisable g_cgc.p_api->sdadcClockDisable();
Disable the SDADCCLK output (S1JA only)
sdramClockOutEnable g_cgc.p_api->sdramClockOutEnable();
Enables the SDRAM clock output (S7G2 MCU only).
sdramClockOutDisable g_cgc.p_api->sdramClockOutDisable();
Disables the SDRAM clock (S7G2 only).
usbClockCfg g_cgc.p_api->usbClockCfg(divider);
Configures the USB clock (S7G2 only).
systickUpdate g_cgc.p_api->systickUpdate(period_count, units);
Update the Systick timer.
versionGet g_cgc.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_ABORTED Attempt to update systick timer failed.
SSP_ERR_HARDWARE_TIMEOUT Hardware timed out.
SSP_ERR_STABILIZED Clock stabilized.
SSP_ERR_CLOCK_INACTIVE Clock not turned on.
SSP_ERR_MAIN_OCO_INACTIVE Main OCO off/unstable.
SSP_ERR_CLOCK_ACTIVE Clock active.
SSP_ERR_NOT_STABILIZED Clock source un-stabilized.
SSP_ERR_CLKOUT_EXCEEDED Clock out exceeded.
SSP_ERR_NULL_PTR Pointer null.
SSP_ERR_OSC_DET_ENABLED Oscillation stop detection enabled.
SSP_ERR_OSC_STOP_DETECTED The Oscillation stop detect status flag is set. Under this condition it is not possible to disable the Oscillation stop detection function.
SSP_ERR_OSC_STOP_CLOCK_ACTIVE The Oscillation Detect Status flag cannot be cleared if the Main Osc or PLL is set as the system clock. Change the system clock before attempting to clear this bit.
SSP_ERR_INVALID_ARGUMENT Invalid argument.
SSP_ERR_INVALID_MODE Attempt to start a clock in a restricted operating power control 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.

CGC HAL Module Operational Overview

The CGC HAL module interface provides the ability to configure and use all of the CGC HAL module's capabilities. Among those capabilities are the selection of several clock sources to use as the system clock source; additionally, the system clocks can be divided down to provide a wide range of frequencies for various system and peripheral needs.

Clock stability can be checked and clocks may also be stopped to save power when not needed. The API has a function to return the frequency of the system and system peripheral clocks at run time. There is also a feature to detect when the main oscillator has stopped, with the option of calling a user provided callback function.

The CGC HAL module can be used to:

  • Configure any of the available clocks (HOCO, MOCO, LOCO, Main Clock, PLL, Sub-Oscillator) as the system clock source
  • Configure the internal clocks (ICLK, PCLK, and so on)
  • Switch the clocks on and off
  • Configure the output clocks
  • Set up the Oscillation Stop Detection feature

The Clock Generation Circuit peripheral features the following oscillators and clock generators:

  • Main oscillator input of up to 24 MHz
  • A 32.768 kHz sub-clock oscillator
  • HOCO running at up to 64 MHz (depending on the device version)
  • MOCO running at 8 MHz
  • LOCO running at 32.768 kHz
  • PLL circuit output running between 24 MHz and 240 MHz, depending on the device

The Synergy microcontrollers have six internal clock domains. Each of them has independent divisors but are dependent upon the clock input selected in the System Clock Control Register. These are:

  • ICLK – The core clock, for CPU, DMAC, ROM and RAM (max 32/48/240 MHz)
  • PCLKA – Peripheral clock for modules including EtherC, EDMAC, USB2.0 HS, QSPI and SCIF (max 32/48/120 MHz)
  • PCLKB – Peripheral clock for modules like IIC, CAN, DAC12, RTC, USBFS, I/O Ports, WDT and IWDT (max 32/60 MHz)
  • PCLKC – Peripheral clock for ADC12 conversion clock (max 64/60 MHz)
  • PCLKD – Peripheral clock for GPT count clock (max 64/120 MHz)
  • FCLK –Clock source for the flash memory (max 32/60 MHz)

In addition, some of the Synergy microcontrollers also support controllable external clock outputs, some of which have independent divisors. These are:

  • CLKOUT – CLOCKOUT/BUZZER clock (max 24 MHz) (independent clock selector and divisor)
  • BCLK – External bus clock to external bus controller (max 16/120 MHz)
  • SDCLK – SDRAM clock (max 120 MHz)
  • UCLK – USB clock (max 120 MHz) (independent divisor/selector on Synergy version 2)
  • LCD_CLK – LCD Clock (independent clock selector but no divisor)

CGC HAL Module Changing the System Clock Peripheral Clock Divisors at Runtime

The CGC HAL module also has the option to change the system clock and clock tree settings at runtime via the cgc_api_t::clocksCfg API function. Choose New Stack > System > CGC Configuration Instance to create a configuration structure for use with the cgc_api_t::clocksCfg API function.

The cgc_api_t::clocksCfg function allows changes to the system clock, the peripheral clock dividers, the PLL multiplier and divider, and the state of the system clocks (stop/start) (HOCO, Main Oscillator, Subclock oscillator, and so on). The options in the following figure show an example where the system clock is being changed from HOCO to MOCO, and the peripheral clock dividers are also being updated. The options for each clock are Start, Stop, and None (meaning no change.) Not all clocks are available on all MCUs. Not all peripheral clocks are available on all MCUs.

CGC_CP.png
CGC Configuration Properties

The function call for the above example is:

g_cgc.p_api->clocksCfg(&g_cgc_cfg0);

CGC HAL Module Option Setting Memory

 Synergy microcontrollers all include an Option-Setting Memory, this memory 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. The following table lists CGC HOCO parameters that can be configured by OFS registers.

OFS register setting possibilities

Control Description
HOCO oscillation enable Automatically starts the HOCO after a Reset, if enabled.
HOCO Frequency S7 and S5 Series
- 16 MHz
- 18 MHz
- 20 MHz
S3 and S1 Series
- 24 MHz
- 32 MHz
- 48 MHz
- 64 MHz

You can set the OFS register values through the properties dialog, the properties dialog is available on the Synergy Configuration editor when you select the BSP tab.

CGC_RS.png
OFS Register Settings

Low Power Operation

The CGC HAL module also handles operating power control modes of the MCU since the Low Power Modes Version 2 HAL module will no longer handle operation-power control modes of the MCU.

When the operating power control mode is set to Sub-Oscillator Speed Mode, all system clocks except the Sub-Oscillator and the LOCO clock are turned off. To further lower the power consumption, the application program can call the clockStop API function to turn off the LOCO clock.

CGC HAL Module Important Operational Notes and Limitations

CGC HAL Module Operational Notes

  • The CGC HAL module has no dependencies with respect to the ThreadX RTOS.
  • The CGC HAL module is a core function of the MCU and is set after by the BSP initialization process.  It is quite possible that the CGC can be left unchanged. However, the CGC HAL module provides functions that change the clock configuration that can balance the requirements of operating speed and power consumption, depending on application requirements.
  • The CGC peripheral of the Synergy microcontrollers support Oscillator Stop Detection. If enabled in the application, the Oscillator Stop Detection function will automatically detect if the Main/PLL clock has stopped and switches operation to the MOCO. When enabling this functionality in the SSP a callback function has to be manually created by the user. The following steps detail this procedure.
CGC_ED.png
Oscillator Stop Detect Enable/Disable
Note
In SSP 1.4.0 and later, the Oscillator Stop Detect property is set to default as Enabled. Previous versions of SSP set the default to Disabled.
  • If the Configure Subclock Drive on Reset is set to Disabled, then the subclock will not be configured at startup. In order to configure the subclock the user has to create a definition of a weakly linked function R_BSP_WarmStart(). In this function if the argument is "BSP_WARM_START_POST_C", the user can call the API cgc_api_t::clockStart clockStart to start the subclock.
CGC_DR.png
Configure Sub-Clock Drive on Reset

In the application code, create a callback function. In this example, it is called osc_stop_callback.

void osc_stop_callback(cgc_callback_args_t * p_args)
{
/* perform Oscillator Stop Detection processing */
}

Enable the oscillator stop detection by calling the API with the previously declared callback.

/* Enable the Osc Stop Detect functionality */
g_cgc.p_api->oscStopDetect( osc_stop_callback, true );

Enable the interrupt within the ICU

/* Osc Stop Detect is an NMI interrupt.  Enable the NMI in ICU */
R_ICU->NMIER_b.OSTEN = 1;

CGC HAL Module Limitations

Refer to the most recent SSP release notes for limitations on the use of this module.

Including the CGC HAL Module in an Application

This section describes how to include the CGC 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.

The CGC Driver is automatically added to the HAL/Common thread, so it only needs to be added to a new thread if it has been removed. (The default name for the CGC is g_cgc0. This name can be changed in the associated Properties window.)

CGC HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_cgc CGC HAL on r_cgc Threads New Stack> Driver> System> CGC Driver on r_cgc

When the CGC Driver on r_cgc 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.

CGC_MS.png
CGC HAL Module Stack

Configuring the CGC HAL Module

The CGC 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 CGC HAL Module on r_cgc

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable the parameter error checking.
Main Oscillator Wait Time 3,35,67,131,259,547,1059,2147,4291,8163 cycles
Default: 8163 cycles 		Set to 0 if a resonator, or crystal, is used. Set to 1 if an external oscillator input is used.
Main Oscillator Clock Source External Oscillator, Crystal or Resonator
Default: Crystal or Resonator 		Set to one of these values. It should be at least as long as the main clock stabilization time. This delay will be configured only if #define CGC_CFG_MAIN_OSC_CLOCK_SOURCE is set to 0, indicating that a resonator/ crystal is used. Set the main clock oscillation stabilization time to longer than or equal to the stabilization time recommended by the oscillator manufacturer.
Oscillator Stop Detect Enabled, Disabled
Default: Enabled 		This allows the R_CGC_OscStopDetect function code to be generated if enabled. The user must call this function with a callback pointer to use this feature.
Subclock Drive Middle (4.4pf), Standard (12.5pf)
Default: Standard (12.5pf) 		This setting is for matching the subclock oscillator drive capacitance based on the crystal parameters #define CGC_CFG_SUBCLOCK_ DRIVE.
Low Voltage Mode Enable, Disable
Default: Disable 		Low voltage mode selection.
Name g_cgc Module name.
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.

In some cases, settings other than the defaults for the CGC HAL module can be desirable. For example, it might be useful to selectively turn clocks on or off or change frequency to optimize power and performance characteristics.

Note
Most of the property settings for modules are fairly intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.

CGC HAL Module Clock Configuration

The default CGC HAL module clock frequencies that will be set by the BSP initialization process are configurable in the ISDE by using the Clocks tab in the configurator. Invalid selections are indicated in red when selected.

CGC_CS.png
Default Clock Settings via the Clocks Tab

In this example, the Clock Source is HOCO, and various clock dividers are chosen for the peripheral clocks.  If a valid USB Clock (UCLK) cannot be achieved, it is highlighted in RED. It should be noted that this is only advisory, and the project will still build, as such a clock frequency may be required.

CGC HAL Module Pin Configuration

The CGC peripheral module controls the output of BCLK and SDCLK signals. Use the Clocks tab to enable/disable this functionality. The BCLK_SDCLK I/O pin must be selected and configured as required via the Pins tab.

CGC_CT.png
Enabling/Disabling SDCLK and BCLK via the Clock Tab

In this example, SDRAM Clock is enabled, BUS Clock is disabled.

CGC_PT.png
Enabling/Disabling SDCLK and BCLK via the Pins Tab

In this example, SDRAM Clock/BUS Clock is enabled on P602.

Additional pin settings associated with the CGC allow for the enabling/disabling of the external oscillator pins and the setting of the system Clock Out pin.

The Synergy devices can run from its on chip oscillators, in which case there is no requirement for the main clock external oscillator pins XTAL and EXTAL.  These could be used as input pins by the application. The functionality of the sub clock external oscillator pins XCIN and XCOUT is fixed.

CGC_EX.png
Enabling/Disabling EXTAL, XTAL and CLKOUT via the Pins Tab

In this example, an external Main Oscillator is used via pins P212 and P213 and the CLKOUT is enabled on P205.

Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy Kits and Synergy MCUs may have different available pin configuration settings.

Using the CGC Module in an Application

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

  1. The CGC is automatically set after the system reset.
  2. Configure the clock as desired using the cgc_api_t::clocksCfg API.
  3. Start clocks using the cgc_api_t::clockStart API if needed.
  4. Stop clocks using the cgc_api_t::clockStop API if needed.
  5. Other CGC functions as needed.

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

CGC_TA.png
Flow Diagram of a Typical CGC HAL Module Application