Middleware Power Modes on RAfW MCUs. This module implements the PMGR Interface.
Overview
The power management architecture and implementation of each chip or modem defines different power modes, ending up with uncorrelated power mode for different chips on Renesas portfolio. Due to the complexity of the connectivity protocols, new power save mode can be developed per specific use-case and customer application topology. The customer doesn’t need to define power mode nor should a customer be fully familiarized with all modes supported by every chip used by customer solution. The customer should only define constraint and abstract application mode of operation. It is the responsibility of the chip manufacturer (and FSP instance developer) to translate customer abstract application level definition of power requirements to the internal power mode for current technology.
Features
- Add / remove constraint
- Set /clear wake source
- Force mode
- Register / unregister application
- Open / close PMGR driver module
- Enter idle for wanted time
Configuration
Build Time Configurations for rm_pmgr_w
The following build time configurations are defined in fsp_cfg/rm_pmgr_cfg.h:
| Configuration | Options | Default | Description |
| SSL Options |
| PMGR_SSL_DPM_SUPPORT |
| Define | Enable DPM support. |
| MAX_NOTIFIER_ARRAY Value | Manual Entry | 5 | Number of registered applications |
- Note
- Tickless Idle must set to 2 in the FreeRTOS thread config under Common|General|Use Tickless Idle.
Clock Configuration
This module has no required clock configurations.
Pin Configuration
This module does not use I/O pins.
CLI command
The PMGR module have the next cli commands:
- status - PMGR show status
- add_constraint - PMGR add constraint [constraint: PMGR_CONSTRAINT_NON, PMGR_CONSTRAINT_SLEEP_PROHIBITED, PMGR_CONSTRAINT_POWER_MAC_HW, PMGR_CONSTRAINT_POWER_RAM, PMGR_CONSTRAINT_POWER_RETENTION]
- remove_constraint - PMGR remove constraint [constraint: PMGR_CONSTRAINT_NON, PMGR_CONSTRAINT_SLEEP_PROHIBITED, PMGR_CONSTRAINT_POWER_MAC_HW, PMGR_CONSTRAINT_POWER_RAM, PMGR_CONSTRAINT_POWER_RETENTION]
- set_wake_source - PMGR set wake source [wake_source: PMGR_WAKE_SOURCE_RTC, PMGR_WAKE_SOURCE_GPT, PMGR_WAKE_SOURCE_ADC, PMGR_WAKE_SOURCE_WIFI, PMGR_WAKE_SOURCE_BLE]
- clear_wake_source - PMGR clear wake source [wake_source: PMGR_WAKE_SOURCE_RTC, PMGR_WAKE_SOURCE_GPT, PMGR_WAKE_SOURCE_ADC, PMGR_WAKE_SOURCE_WIFI, PMGR_WAKE_SOURCE_BLE]
- force - PMGR force [state: PMGR_LLD_STATE2, PMGR_LLD_STATE3, PMGR_LLD_DPM, PMGR_LLD_STATE4, PMGR_LLD_CPU_CLOCK_GATING, PMGR_LLD_AUTO - for cancel]
Examples
Basic Example
This is a basic example of minimal use of the PMGR in an application.
Open / Close PMGR Driver Module
void rm_pmgr_open_close_example (void)
{
fsp_err_t err = RM_PMGR_W_Open(&g_pmgr_ctrl, &g_pmgr_cfg_tin);
assert(FSP_SUCCESS == err);
err = RM_PMGR_W_Close(&g_pmgr_ctrl);
assert(FSP_SUCCESS == err);
}
Register / Unregister Application
void tin_pmgr_callback(pmgr_callback_args_t *args)
{
pmgr_instance_info_t *p_instance_info = (pmgr_instance_info_t *)args->p_instance_info;
printf("tin_pmgr_callback with %s, constraints=%d, wake source=%d, p_instance_info->power_mode=%d\n",
pmgr_event_to_string(args->event), args->constraints, p_instance_info->wake_source, p_instance_info->power_mode);
}
void rm_pmgr_notifier_example (void)
{
fsp_err_t err = RM_PMGR_W_Open(&g_pmgr_ctrl, &g_pmgr_cfg_tin);
assert(FSP_SUCCESS == err);
{
assert(FSP_SUCCESS == err);
}
assert(FSP_SUCCESS == err);
err = RM_PMGR_W_notifier_register(
RM_PMGR_W_get_ctrl(), tin_pmgr_callback, &g_args, ¬ifier_extend);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
err = RM_PMGR_W_Close(&g_pmgr_ctrl);
assert(FSP_SUCCESS == err);
}
Wake source and Constraint
void rm_pmgr_constraints_wake_sources_example (void)
{
fsp_err_t err = RM_PMGR_W_Open(&g_pmgr_ctrl, &g_pmgr_cfg_tin);
assert(FSP_SUCCESS == err);
{
assert(FSP_SUCCESS == err);
}
assert(FSP_SUCCESS == err);
err = RM_PMGR_W_notifier_register(
RM_PMGR_W_get_ctrl(), tin_pmgr_callback, &g_args, ¬ifier_extend);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
err = RM_PMGR_W_Close(&g_pmgr_ctrl);
assert(FSP_SUCCESS == err);
}
Force state
void rm_pmgr_force_example (void)
{
fsp_err_t err = RM_PMGR_W_Open(&g_pmgr_ctrl, &g_pmgr_cfg_tin);
assert(FSP_SUCCESS == err);
{
assert(FSP_SUCCESS == err);
}
assert(FSP_SUCCESS == err);
err = RM_PMGR_W_notifier_register(
RM_PMGR_W_get_ctrl(), tin_pmgr_callback, &g_args, ¬ifier_extend);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
err = RM_PMGR_W_Close(&g_pmgr_ctrl);
assert(FSP_SUCCESS == err);
}
◆ pmgr_w_notifier_extend_t
| struct pmgr_w_notifier_extend_t |
The pmgr_w extend notifier with the following 2 features:
- Allow multiple registration to allow multiple registration, the following is added
- notifier_id - used to indicate the specific callback instance. When call to notifier_registration() notifier_id == UNDEFINE_NOTIFIER_ID
- order - used to define the order of callback notification , higher order executed first
- Allow asynchronous respond.
| Data Fields |
|---|
|
uint32_t |
order |
used to define order of notifier execution, input |
|
uint32_t |
notifier_id |
used to identify the notifier, output |
◆ pmgr_instance_ctrl_t
| struct pmgr_instance_ctrl_t |
PMGR private control block. Initialization occurs when RM_PMGR_W_Open() is called.
| Data Fields |
|---|
|
pmgr_cfg_t const * |
p_cfg |
Pointer to initial configurations. |
|
struct st_notifier_array_entry |
notifier_array[PMGR_MAX_NOTIFIER_ARRAY] |
Array of registered applications. |
|
pmgr_timer_notifier_array_entry_t |
timer_notifier_array[MAX_TIMER_NOTIFIER_ARRAY] |
|
|
uint8_t |
constraint_counter[PMGR_CONSTRAINT_MAX] |
Array of constraints counter. |
|
int16_t |
ram_counter_cause[PMGR_DBG_RAM_CONSTRAINT_MAX] |
Array for debug ram constraints counter cause. |
|
int |
debug_runtime_flag |
Debug runtime flag for ram constraints counter cause. |
|
pmgr_wake_source_t |
wake_source_bitmap |
Bitmap of wake sources. |
|
pmgr_lld_power_mode_t |
lld_power_mode |
Power mode for distinction if its force. |
◆ pmgr_debug_runtime_t
Debug runtime flag for RAM constraints counter cause
| Enumerator |
|---|
| PMGR_DEBUG_RAM_UNSET | Debug runtime flag RAM constraints unset.
|
| PMGR_DEBUG_RAM_DISABLED | Debug runtime flag RAM constraints disabled.
|
| PMGR_DEBUG_RAM_ENABLED | Debug runtime flag RAM constraints enabled.
|
◆ pmgr_wake_source_t
LLD wakeup source
| Enumerator |
|---|
| PMGR_WAKE_SOURCE_NON | no wake source defined
|
| PMGR_WAKE_SOURCE_RTC | RTC wake source.
|
| PMGR_WAKE_SOURCE_GPT | GPT wake source.
|
| PMGR_WAKE_SOURCE_GPIO | GPIO wake source.
|
| PMGR_WAKE_SOURCE_ADC | ADC wake source.
|
| PMGR_WAKE_SOURCE_WIFI | WIFI/MAC wake source.
connectivity wake source.
|
| PMGR_WAKE_SOURCE_BLE | BLE wake source.
|
| PMGR_WAKE_SOURCE_NONE | no wake source defined
|
| PMGR_WAKE_SOURCE_RTC | RTC wake source.
|
| PMGR_WAKE_SOURCE_GPT | GPT wake source.
|
| PMGR_WAKE_SOURCE_GPIO | GPIO wake source.
|
| PMGR_WAKE_SOURCE_ADC | ADC wake source.
|
| PMGR_WAKE_SOURCE_WIFI | WIFI/MAC wake source.
connectivity wake source.
|
| PMGR_WAKE_SOURCE_BLE | BLE wake source.
|
◆ pmgr_lld_power_mode_t
| Enumerator |
|---|
| PMGR_LLD_POWER_MODE_SLEEP2 | Remain on: RTC, GPIO.
|
| PMGR_LLD_POWER_MODE_SLEEP3 | Remain on: RTC, GPIO, RTM.
|
| PMGR_LLD_POWER_MODE_DPM | Remain on: RTC, GPIO, RTM + WiFi Connected.
|
| PMGR_LLD_POWER_MODE_SLEEP4 | Remain on: RTC, GPIO, RTM, RAM.
|
◆ pmgr_dbg_ram_constraint_counter_cause_t
| Enumerator |
|---|
| PMGR_DBG_RAM_CONSTRAINT_GENERIC_FORCE | If PMGR cli force DPM was done, this is the cause for decrease any ram constraints.
|
◆ pmgr_w_notifier_order_t
| Enumerator |
|---|
| PMGR_W_NOTIFIER_ORDER_SYS_LOW | 10-100 are reserved for system low order
|
| PMGR_W_NOTIFIER_ORDER_CUSTOMISED_LOW | 100-199 are reserved for customised application
|
| PMGR_W_NOTIFIER_ORDER_SYS_HIGH | 200-139 are reserved for system high order
|
| PMGR_W_NOTIFIER_ORDER_HIGHEST | first executed
|
◆ RM_PMGR_W_notifier_unregister()
Instance API extension. Unregister notifier_id from PMGR Instance
- Return values
-
| FSP_SUCCESS | Unregistration done successfully |
| FSP_ERR_INVALID_ARGUMENT | Unregistration failed: such notifier id was not found |
◆ RM_PMGR_W_set_wake_source()
Set wake source - system middleware and customised application are allowed to specify which component are used as wake source and as such should be kept powered on. Wake source are bit map, the implementation is boolean parameter per wake source (no matter how many times a wake source is set, single clear will set it to false)
- Parameters
-
| [in] | p_ctrl | Pointer to the PMGR control block. |
| [in] | wake_source | bit wise of single wake source that should be kept powered on. |
- Return values
-
| FSP_SUCCESS | Set wake source done successfully |
| FSP_ERR_IN_USE | Set wake source failed due to the semaphore is not available |
◆ RM_PMGR_W_clr_wake_source()
Clear wake source - see set_wake_source for info
- Parameters
-
| [in] | p_ctrl | Pointer to the PMGR control block. |
| [in] | wake_source | bit wise of single wake source that should be kept powered off. |
- Return values
-
| FSP_SUCCESS | Clear wake source done successfully |
| FSP_ERR_IN_USE | Clear wake source failed due to the semaphore is not available |
◆ RM_PMGR_W_get_wake_source()
Get wake source bitmap
- Parameters
-
| [in] | p_ctrl | Pointer to the PMGR control block. |
| [in] | wake_source | pointer of wake source bitmap. use pmgr_wake_source_t to check which wake source is set. |
- Return values
-
| FSP_SUCCESS | Get wake source done successfully |
| FSP_ERR_IN_USE | Get wake source failed due to the semaphore is not available |
◆ RM_PMGR_W_force()
Forces a specific power mode, overriding the Power Manager (PMGR) decision making. This function allows an application to force a low-power sleep mode. The behavior depends on the desired power mode and the provided idle_time_us value.
- Note
- This override can be permanent (sticky) for certain modes. To revert the force, and resume to automatic power management, you must explicitly set the mode to
PMGR_LLD_POWER_MODE_AUTO.
- Deep sleep modes (RAM Power Off): For modes: PMGR_LLD_POWER_MODE_SLEEP2, PMGR_LLD_POWER_MODE_SLEEP3, and PMGR_LLD_POWER_MODE_DPM The forced power mode is lost upon wakeup (PMGR resumes to PMGR_LLD_POWER_MODE_AUTO) Based on idle_time_us value, the low power mode will be immediate or at next enter_idle call
- Light sleep modes (RAM maintained): For modes: PMGR_LLD_POWER_MODE_SLEEP4, PMGR_LLD_POWER_MODE_CPU_WFI The forced power modes is "sticky" and remains until changed by another call to 'force' idle_time_us value has no effect. The low power mode will be executed at next FreeRTOS idle context
- Parameters
-
| [in] | p_ctrl | Pointer to the PMGR control block. |
| [in] | mode | Defines the power mode to enter |
| [in] | idle_time_us | For Deep sleep modes only: The expected idle duration in microseconds.
- idle_time_us > 0, low power mode executed immediately
- idle_time_us = 0, low power mode executed at next enter_idle call
|
- Return values
-
| FSP_SUCCESS | Force sleep mode done successfully |
◆ RM_PMGR_W_get_sleep_constraint_counter()
Get the specified sleep constraint count
- Parameters
-
| [in] | p_ctrl | Pointer to the PMGR control block. |
| [in] | constraint | Defines a bit map of single constraint. |
| [out] | counter | counter value of the specified constraint |
- Return values
-
| FSP_SUCCESS | Getting the specified sleep constraint count done successfully |
| FSP_ERR_IN_USE | Getting the specified sleep constraint count failed due to the semaphore is not available |
◆ RM_PMGR_W_get_ctrl()
Get ctrl - Return the global pointer for the PMGR control block. It is the customer responsibility to verify open was called with not NULL value before.
- Return values
-
| p_ctrl | Pointer to the PMGR control block. |
