 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Power Profiles V2 Framework provides a high-level API used to control the system clocks, the I/O ports, the operating modes (indirectly through the clock control) and the low power modes of the MCU. The Power Profiles V2 Framework, when used with the LPM V2 Driver, CGC Driver and I/O Port Driver, gives the user advanced control over the power consumption of the MCU.
There are different low-level LPM V2 HAL modules used in the framework depending on the target MCU (as shown in the following table):
| MCU | Driver |
|---|---|
| S124 | S124 Low Power Mode Sleep on r_lpmv2 |
| S124 | S124 Low Power Mode Standby on r_lpmv2 |
| S128 | S128 Low Power Mode Sleep on r_lpmv2 |
| S128 | S128 Low Power Mode Standby on r_lpmv2 |
| S3A3 | S3A3 Low Power Mode Sleep on r_lpmv2 |
| S3A3 | S3A3 Low Power Mode Standby on r_lpmv2 |
| S3A7 | S3A7 Low Power Mode Sleep on r_lpmv2 |
| S3A7 | S3A7 Low Power Mode Standby on r_lpmv2 |
| S5D9 | S5D9 Low Power Mode Sleep on r_lpmv2 |
| S5D9 | S5D9 Low Power Mode Standby on r_lpmv2 |
| S5D9 | S5D9 Low Power Mode Deep Standby on r_lpmv2 |
| S7G2 | S7G2 Low Power Mode Sleep on r_lpmv2 |
| S7G2 | S7G2 Low Power Mode Standby on r_lpmv2 |
| S7G2 | S7G2 Low Power Mode Deep Standby on r_lpmv2 |
Because of the large number of lower level LPM V2 HAL modules available, it would be difficult to identify separate APIs and configuration settings. This module guide only goes into details for the S7G2 MCU. All the APIs and configuration settings are the same (except for those MCUs that do not support Deep Standby). It should be simple to extrapolate to any target MCU.
The Power Profiles defines APIs for common functions such as open, sleep and close. 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.
Power Profiles V2 Framework Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| open | g_sf_power_profiles_v2_common.p_api->open(g_sf_power_profiles_v2_low_power_0.p_ctrl, g_sf_power_profiles0.p_cfg);Initialize the Power Profiles V2 Framework. |
| runApply | g_sf_power_profiles_v2_common.p_api->runApply(g_sf_power_profiles_v2_common.p_ctrl, &g_sf_power_profiles_v2_run_0);Apply the selected run power profile. |
| lowPowerApply | g_sf_power_profiles_v2_common.p_api->lowPowerApply(g_sf_power_profiles_v2_common.p_ctrl, &g_sf_power_profiles_v2_low_power_0);Apply the selected low power profile. |
| close | g_sf_power_profiles_v2_common.p_api->close(g_sf_power_profiles_v2_common.p_ctrl);Close the module. |
| versionGet | g_sf_power_profiles_v2_common.p_api->versionGet(&p_version);Get version and store it in provided pointer p_version. |
Status Return Values
| Name | Description |
|---|---|
| SSP_SUCCESS | Function successful. |
| SSP_ERR_ASSERTION | Assertion error. |
| SSP_ERR_IN_USE | The framework has already been initialized. |
| SSP_ERR_INVALID_HW_CONDITION | Incompatible system clock configuration. |
| SSP_ERR_NOT_OPEN | Device not open. |
| SSP_ERR_UNSUPPORTED | The function is not supported by the module. |
| SSP_ERR_INTERNAL | Internal error. |
The Power Profiles V2 Framework provides a high-level API used to control the system clocks, the I/O ports, the operating modes (indirectly through the clock control), and the low power modes of the MCU. The Power Profiles V2 Framework, when used with the LPM V2 Driver, CGC Driver, and I/O Port Driver, gives the user advanced control over the power consumption of the MCU.
The Power Profiles V2 Framework provides 2 main functions to control the MCU power consumption, sf_power_profiles_v2_api_t::runApply and sf_power_profiles_v2_api_t::lowPowerApply. The runApply() function uses a CGC Clocks configuration and an I/O Port pin configuration to set the system clocks and I/O Port pins of the MCU. The lowPowerApply() function uses a LPM V2 configuration and two I/O Port configuration to set the low power mode and I/O Port pins before entering the configured low power mode and after waking from the low power mode. See LPM V2 module overview and the MCU hardware manual for details about the available low power modes.
The Power Profiles V2 Framework uses the LPM V2, IOPORT, and CGC Drivers of the Synergy Software Package and provides an easy-to-use software interface to control the power consumption of the MCU.
Operational Description
The Power Profiles V2 Framework configures the system in both a Run state and a Low Power state. The system clocks, I/O pins, and low power mode of the MCU can all be handled and controlled using the Power Profiles V2 Framework.
The Power Profiles V2 Framework API function sf_power_profiles_v2_api_t::open initializes the Power Profiles V2 Framework internal variables, instance variables, and the LPM V2 Driver. If the project uses ThreadX, the Framework will ensure safe use in a multi-threaded environment.
The runApply() and lowPowerApply() functions optionally use I/O Port pin configurations to provide control of the MCU I/O Ports. The lowPowerApply() function can use 2 pin configurations: one to set the pins to a state appropriate for the low power mode when the MCU will not be executing instructions, and a second for after waking from the low power mode, when instruction execution resumes.
The Power Profiles V2 Framework runApply() function applies the user-defined optional pin configuration, then applies the user-defined CGC clocks configuration. The user can switch clocks on and off, change clock dividers, and switch the system clocks using the CGC Clocks configuration structure.
The Power Profiles V2 Framework API function runApply() performs the following tasks in order:
The lowPowerApply() function uses an LPM V2 configuration to set the low power mode, the triggers for waking from the low power mode, the state of bus pins, and other settings that are MCU specific. The lowPowerApply() function can optionally use an application callback function. The prototype can be found in /src/synergy_gen/hal_data.c or /src/synergy_gen/<thread name>.c.
The Power Profiles V2 Framework lowPowerApply() function performs the following tasks in order:
1. If the project uses ThreadX, the function will get the ThreadX mutex prior to calling any lower level driver.
2. Apply the optional user-specified low power entry pin configuration.
3. Call the user specified callback function with the enumeration SF_POWER_PROFILES_V2_EVENT_PRE_LOW_POWER.
4. Apply the user-specified low power mode configuration. Any valid LPM V2 configuration can be used.
5. Enter the low power mode.
6. If the low power mode chosen was other than Deep Standby the MCU will resume execution of code from the same point once the wakeup trigger is detected. (If the LPM V2 low power mode configuration was Deep Standby, the MCU will not resume code execution but will instead go through a soft reset once the wakeup trigger is detected.)
7. Apply the optional user-specified low power exit pin configuration.
8. Call the user specified callback function with the enumeration SF_POWER_PROFILES_V2_EVENT_POST_LOW_POWER.
9. If the project uses ThreadX, the function will return the ThreadX mutex.
The Power Profiles V2 Run or Low Power profiles should be added to the project by the user. The Power Profiles V2 common module will be added automatically.
Outside of a thread:
Within a thread:
After adding a Power Profiles V2 Run or Low Power Profile, you will need to add an LPM V2 Common module. If an LPM V2 Common instance already exists in the project, it will be used. A Power Profiles V2 Run Profile does not directly use the LPM V2, but it is still a dependency for a successful build.
A Power Profiles V2 Run Profile depends upon a CGC Clocks Configuration. The configuration options of the CGC Clocks Configuration instance are provided below. If a CGC Clocks Configuration instance is not already present in the project, it will be automatically added. If one is present, it could be used instead. Controlling system clocks is a critical part of controlling power consumption of an MCU. See the CGC usage notes for more information.
The Power Profiles V2 Low Power Profile uses an LPM V2 standby instance, but an LPM V2 deep standby instance or LPM V2 sleep instance could be used instead depending on which MCU is currently being used.
The LPM V2 instance's properties can be configured by selecting the instance and reviewing the Properties pane.
Configuring the Pins for the Power Profiles V2 Framework
Optional: Create additional I/O Port pin configurations using the Pins tab as follows:
1. In the top-level directory of your project, find the file with file extension *.pincfg.
2. Make a copy of this file and rename it, keeping the new file in the same top-level directory of the project.
3. The new file is now available as an option on the Pins tab of the Synergy Configuration. Look for the file name in the drop down list on the Pins tab below "Select pin configuration".
4. Check the Generate data checkbox and type in a pin configuration name. The checkbox and text entry can be found to the right of the pin configuration drop down.
5. Configure the pins as desired for either a Run or Low Power Profile.
6. Save the project configuration and Generate Project Content.
7. To view the pin configuration that was generated, look in the file {project_directory}/src/synergy_gen/pin_data.c for the ioport_cfg_t structure of the same name as entered in the text box.
8. Add the name of the ioport_cfg_t structure to one of the pin configuration table entries for a Run or Low Power Profile.
For a Power Profiles V2 Run Profile:
For a Power Profiles V2 Low Power Profile:
Configuring the Interrupts for the Power Profiles V2 Framework
The Power Profiles V2 Framework does not use any interrupts directly, although any interrupt is capable of waking the MCU while in Sleep mode. This is handled through the LPM V2 driver configuration.
Configuring the Power Profiles V2 Callbacks
Power Profiles V2 Low Power Profiles can notify the application before entering the low power mode and after waking from low power mode. The prototype can be found in /src/hal_data.c or /src/synergy_gen/<thread name>.c.
Fill in the callback used by the Power Profiles V2 Low Power Profile:
Configuring the Low Power Module Parameters
See the LPM V2 usage notes for an in depth description of how to use LPM V2.
runApply() function, another instance of the CGC Driver is required in order to create a CGC Clocks configuration. Since the CGC Driver is included in all Synergy projects by default, this does not add to the code size of the project.The Power Profiles V2 Framework does not handle starting or stopping MCU peripherals.
The Power Profiles V2 Framework open function will not be called automatically prior to main if the project does not use ThreadX. The initialization must be done explicitly by calling g_common_init() or by explicitly calling the sf_power_profiles_v2_api_t::open API. This is not a Power Profiles V2 limitation but a result of any Framework module that supports being used without an RTOS.
Refer to the most recent SSP Release Notes for any additional operational limitations for this module.
This section describes how to include the Power Profiles V2 Framework module in an application using the SSP configurator.
To add the Power Profiles V2 Framework module to an application, simply add it to a HAL /Common thread using the stacks selection sequence given in the following table. (The default name for the Power Profiles V2 Framework module is sf_power_profiles_v2_0. This name can be changed in the associated Properties window.)
Power Profiles V2 Framework Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_sf_power_profiles_low_power_0 Power Profiles V2 Low Power Profile | Threads | New Stack> Framework> Services> Power Profiles V2 Low Power Profile |
| g_sf_power_profiles_run_0 Power Profiles V2 Run Profile | Threads | New Stack> Framework> Services> Power Profiles V2 Run Profile |
When the Power Profiles V2 Framework module on sf_power_profiles_v2 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.
The Power Profiles V2 Framework module must be configured by the user for the desired operation. The SSP configuration window will automatically identify (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules in order to ensure successful operation. Furthermore, only those properties that can be changed without causing conflicts are available for modification. Other properties are 'locked' and are 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.
There are two different stack selections for the Power Profiles V2 Framework, the Run Profile and the Low Power Profile. Their respective configuration settings will be covered separately in the following sections.
Typically, only a small number of settings must be modified from the default for lower-level drivers as indicated with red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following table identifies all the settings within the properties section for the module.
Configuration Settings for the Power Profiles V2 Run Profile
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_sf_power_profiles_v2_run_0 | Module name. |
| Pin configuration table | NULL | Pin configuration table selection. |
Configuration Settings for the Power Profiles V2 Common
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_sf_power_profiles_v2_common | Module name. |
Configuration Settings for the CGC Configuration Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_cgc_cfg0 | Module name. |
| System Clock | HOCO, MOCO, LOCO, Main Oscillator, Sub Clock, PLL Default: HOCO | System clock selection. |
| LOCO State Change | None, Start, Stop Default: None | LOCO state change selection. |
| MOCO State Change | None, Start, Stop Default: None | MOCO state change selection. |
| HOCO State Change | None, Start, Stop Default: None | HOCO state change selection. |
| Sub-Clock State Change | None, Start, Stop Default: None | Sub-clock state change selection. |
| Main Clock State Change | None, Start, Stop Default: None | Main clock state change selection. |
| PLL State Change | None, Start, Stop Default: None | PLL state change selection. |
| PLL Source Clock | HOCO, MOCO, LOCO, Main Oscillator, Sub Clock, PLL Default: HOCO | PLL source clock selection. |
| PLL Divisor | 1, 2, 3, 4 Default: 1 | PLL divisor seiection. |
| PLL Multiplier | 10.0, 10.5, 11.0, 11.5, 12.0, 12.5, 13.0, 13.5, 14.0, 14.5, 15.0, 15.5, 16.0, 16.5, 17.0, 17.5, 18.0, 18.5, 19.0, 19.5, 20.0, 20.5, 21.0, 21.5, 22.0, 22.5, 23.0, 23.5, 24.0, 24.5, 25.0, 25.5, 26.0, 26.5, 27.0, 27.5, 28.0, 28.5, 29.0, 29.5, 30.0, 31.0 Default: 10.0 | PLL multiplier selection. |
| PCLKA Divisor | 1, 2, 4, 8, 16, 64 Default: 1 | PCLKA divisor selection. |
| PCKLB Divisor | 1, 2, 4, 8, 16, 64 Default: 1 | PCKLB divisor selection. |
| PCLKC Divisor | 1, 2, 4, 8, 16, 64 Default: 1 | PCLKC divisor selection. |
| PCLKD Divisor | 1, 2, 4, 8, 16, 64 Default: 1 | PCLKD divisor selection. |
| BCLK Divisor | 1, 2, 4, 8, 16, 64 Default: 1 | BCLK divisor selection. |
| FCLK Divisor | 1, 2, 4, 8, 16, 64 Default: 1 | FCLK divisor selection. |
| ICLK Divisor | 1, 2, 4, 8, 16, 64 Default: 1 | ICLK divisor selection. |
Configuration Settings for the Lower Power Mode Common
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_lpmv2_common | Module name. |
Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the Thread Stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the Power Profiles V2 Low Power Profile
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_sf_power_profiles_v2_low_power_0 | Module name. |
| Callback (Low Power Exit Event N/A when using Deep Software Standby) | NULL | Callback selection. |
| Low power entry pin configuration table | NULL | Low power entry pin configuration table selection. |
| Low power exit pin configuration table | NULL | Low power exit pin configuration table selection. |
Configuration Settings for the Low Power Mode Deep Standby
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_lpmv2_deep_standby | Module name. |
| Output port state in standby and deep standby, applies to address output, data output, and other bus control output pins | High impedance state, No change Default: No change | Output port state selection. |
| Maintain or reset the IO port states on exit from deep standby mode | Maintain the IO port states, Reset the IO port states Default: Maintain the IO port states | Maintain or reset the IO port states selection. |
| Internal power supply control in deep standby mode | Maintain the internal power supply, Cut the power supply to standby RAM, low-speed on-chip oscillator, AGTn, and USPFS/HS resume detecting unit, Cut the power supply to LVDn, standby RAM, low-speed on-chip oscillator, AGTn, and USBFS/HS resume detecting unit Default: Maintain the internal power supply | Internal power supply control selection. |
| IRQ0-15 | Enabled, Disabled Default: Disabled | IRQ0-15 selection. |
| IRQ0-15 Edge | Disabled, Rising Edge, Falling Edge Default: Disabled | IRQ0-15 Edge selection. |
| LVD1 | Enabled, Disabled Default: Disabled | LVD1 selection. |
| LVD1 Edge | Disabled, Rising Edge, Falling Edge Default: Disabled | LVD1 Edge selection. |
| LVD2 | Enabled, Disabled Default: Disabled | LVD2 selection. |
| LVD2 Edge | Disabled, Rising Edge, Falling Edge Default: Disabled | LVD2 Edge selection. |
| RTC Interval | Enabled, Disabled Default: Disabled | RTC Interval selection. |
| RTC Alarm | Enabled, Disabled Default: Disabled | RTC Alarm selection. |
| NMI | Enabled, Disabled Default: Disabled | NMI selection. |
| NMI Edge | Disabled, Rising Edge, Falling Edge Default: Disabled | NMI Edge selection. |
| USBFS | Enabled, Disabled Default: Disabled | USBFS selection. |
| UBSHS | Enabled, Disabled Default: Disabled | UBSHS selection. |
| AGT1 | Enabled, Disabled Default: Disabled | AGT1 selection. |
Configuration Settings for the Low Power Mode Sleep
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_lpmv2_sleep0 | Module name. |
Configuration Settings for the Low Power Mode Standby
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_lpmv2_standby0 | Module name. |
| Choose the low power mode | Standby, Standby with snooze Enabled Default: Standby | Low power mode selection. |
| Output port state in standby and deep standby, applies to address output, data output, and other bus control output pins | High impedance state, No change Default: No change | Output port state selection. |
| IRQ1-15 | Enabled, Disabled Default: Disabled | IRQ1-15 selection. |
| IWDT | Enabled, Disabled Default: Disabled | IWDT selection. |
| Key Interrupt | Enabled, Disabled Default: Disabled | Key Interrupt selection. |
| LVD1 Interrupt | Enabled, Disabled Default: Disabled | LVD1 Interrupt selection. |
| LVD2 Interrupt | Enabled, Disabled Default: Disabled | LVD2 Interrupt selection. |
| Analog Comparator High-speed 0 Interrupt | Enabled, Disabled Default: Disabled | Analog Comparator High-speed 0 Interrupt selection. |
| RTC Alarm | Enabled, Disabled Default: Disabled | RTC Alarm selection. |
| RTC Period | Enabled, Disabled Default: Disabled | RTC Period selection. |
| USB High-speed | Enabled, Disabled Default: Disabled | USB High-speed selection. |
| USB Full-speed | Enabled, Disabled Default: Disabled | USB Full-speed selection. |
| AGT1 underflow | Enabled, Disabled Default: Disabled | AGT1 underflow selection. |
| AGT1 Compare Match A | Enabled, Disabled Default: Disabled | AGT1 Compare Match A selection. |
| AGT1 Compare Match B | Enabled, Disabled Default: Disabled | AGT1 Compare Match B selection. |
| 12C 0 | Enabled, Disabled Default: Disabled | 12C 0 selection. |
| Snooze Entry Source | RXD0 falling edge, IRQ0-IRQ15, KINT, ACMPHS0, RTC Alarm, RTC Period, AGT1 Underflow, AGT1 Compare Match A, AGT1 Compare Match B Default: RXD0 falling edge | Snooze Entry Source selection. |
| AGT1 Underflow | Enabled, Disabled Default: Disabled | AGT1 Underflow selection. |
| DTC Transfer Completion | Enabled, Disabled Default: Disabled | DTC Transfer Completion selection. |
| DTC Transfer Completion Negated Signal | Enabled, Disabled Default: Disabled | DTC Transfer Completion Negated Signal selection. |
| ADC0 Compare Match | Enabled, Disabled Default: Disabled | ADC0 Compare Match selection. |
| ADC0 Compare Mismatch | Enabled, Disabled Default: Disabled | ADC0 Compare Mismatch selection. |
| ADC1 Compare Match | Enabled, Disabled Default: Disabled | ADC1 Compare Match selection. |
| ADC1 Compare Mismatch | Enabled, Disabled Default: Disabled | ADC1 Compare Mismatch selection. |
| SCI0 Address Match | Enabled, Disabled Default: Disabled | SCI0 Address Match selection. |
| DTC state in Snoooze Mode | Enabled, Disabled Default: Disabled | DTC state in Snoooze Mode selection. |
Configuration Settings for the Power Profiles V2 Common
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_sf_power_profiles_v2_common | Module name. |
Configuration Settings for the Low Power Mode Common
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_lpmv2_common | Module name. |
The Power Profiles V2 framework does not require any specific clock settings
The application may optionally maintain the I/OPort state during a low power mode.
The typical steps in using the Power Profiles V2 Framework module in an application are:
g_sf_power_profiles_v2_common.p_api->runApply(g_sf_power_profiles_v2_common.p_ctrl, &g_sf_power_profiles_v2_run_0);g_sf_power_profiles_v2_common.p_api->lowPowerApply(g_sf_power_profiles_v2_common.p_ctrl, &g_sf_power_profiles_v2_low_power_0);g_sf_power_profiles_v2_common.p_api->close(g_sf_power_profiles_v2_common.p_ctrl);These common steps are illustrated in a typical operational flow in the following figure:
