Power Management & Low Power¶

Power modes, PDS sleep and wake-up, the low-power framework and the low-power UART.

hal_pm.h¶

#include "hal_pm.h" (Source)

Power-management primitives: PDS and HBN sleep entry, wakeup sources, 32 kHz clock ownership and sleep-domain policy.

Two sleep modes are available:

• PDS (power-down sleep): the CPU and most digital domains are powered down, retained RAM keeps its contents. On wake-up the CPU is reset, so execution only resumes where it stopped when the low-power framework saved and restores the context. Use hal_lp_enter() (hal_lp.h) for that; the PDS functions here are its building blocks.
• HBN (hibernate): everything except the always-on domain is powered down; wake-up is a full boot. Only the 4 KB HBN RAM (hal_hbnram_mgnt.h) can carry state across.

Wake-up times are given in RTC ticks of the 32.768 kHz clock unless stated otherwise. Functions marked IPRO7 or IPRO6 only are no-ops (or not available) on the other chip.

pm_pds_enable¶

void pm_pds_enable(uint32_t *cfg);

Program the PDS hardware and execute WFI (low level).

Writes back the data cache (IPRO7), applies the level configuration (including pm_pds_set_misc_keep() and the BLE domain policy) and waits for the PDS sequencer to power the core down. No wakeup source is armed here; use pm_pds_mode_enter() or, to resume execution after the sleep, hal_lp_enter().

A completed PDS sleep resets the CPU, so the function returns only when the core did not power down: an enabled interrupt was pending, the one-shot fallback set with pm_pds_wfi_fallback_set() expired, or the level in cfg is not supported. On IPRO7 the interrupt enable state of the caller is restored on return.

pm_pds_set_misc_keep¶

void pm_pds_set_misc_keep(bool keep);

Keep the Misc power domain alive across PDS sleeps.

By default PDS level 31 powers down and resets the Misc domain, which contains the IEEE 802.15.4 MAC. With keep = true the domain stays powered and out of reset (its clock is still gated), so its register state survives the sleep and does not need to be re-initialized on every wake-up, at the cost of higher sleep current.

The setting changes the HAL's default PDS configuration and stays in effect for all later sleeps until changed again. Call it before the first PDS entry. An active BLE domain policy (pm_pds_ble_ctlr_domain_policy_set()) overrides it.

pm_pds_ble_ctlr_domain_policy_set¶

void pm_pds_ble_ctlr_domain_policy_set(uint32_t policy);

Set the PDS domain policy for the following PDS entries (IPRO7).

The policy is applied on top of the HAL's default configuration for each entry; the defaults themselves are not modified, so setting PM_PDS_BLE_CTLR_DOMAIN_POLICY_NONE restores the default behaviour. In builds where the policy is not supported the call has no effect.

pm_pds_ble_ctlr_domain_policy_get¶

uint32_t pm_pds_ble_ctlr_domain_policy_get(void);

Get the PDS domain policy set with pm_pds_ble_ctlr_domain_policy_set().

Returns: The current policy bits; always PM_PDS_BLE_CTLR_DOMAIN_POLICY_NONE in builds where the policy is not supported.

pm_pds_set_dcdc11_vsel¶

void pm_pds_set_dcdc11_vsel(uint8_t vsel, bool enable);

Set the PDS voltage-select field PDS_CTL[27:23] (IPRO6 only).

Stores the value in the IPRO6 PDS level configuration, which the HAL writes to the hardware on every PDS entry. The field selects the voltage of the main LDO11 regulator, which is powered down during PDS, so it does not lower the PDS sleep current; the retention rail is set with pm_ldo11_rt_set(). No effect on IPRO7.

pm_pds_get_dcdc11_vsel¶

void pm_pds_get_dcdc11_vsel(uint8_t *vsel, uint8_t *enable);

Read back the values set with pm_pds_set_dcdc11_vsel() (IPRO6 only).

pm_ldo11_rt_set¶

void pm_ldo11_rt_set(uint8_t sel);

Set the LDO11 retention voltage used during PDS (IPRO6 only).

The register is retained across PDS, so one call after each power-on covers all later sleeps. A lower retention voltage lowers the PDS sleep current. No effect on IPRO7.

pm_ldo11_use_ext_dcdc¶

void pm_ldo11_use_ext_dcdc(void);

Hand the 1.1 V core rail over to an external DCDC (IPRO6 only).

Steps the internal LDO11 SoC and retention outputs down to 1.05 V, waits 1 ms, then sets 1.00 V, so that an external 1.1 V supply on the same rail carries the load. Only for boards that have such a supply (CONFIG_LP_LDO11_EXT_DCDC). No effect on IPRO7.

pm_pds_set_32k_src¶

void pm_pds_set_32k_src(uint8_t use_xtal, uint32_t settle_ms);

Select the 32 kHz clock source and take ownership of it.

Until this is called the HAL owns the 32 kHz selection and keeps the RC32K oscillator as the default. After the call the selection made here is preserved through PDS entries. Nothing calls it during boot, so the platform default is unchanged unless an application or component (for example the BLE controller low-power support) calls it.

pm_pds_get_32k_src¶

void pm_pds_get_32k_src(uint8_t *use_xtal, uint8_t *forced_rc);

Read the current 32 kHz clock selection.

pm_pds_mode_enter¶

void pm_pds_mode_enter(enum pm_pds_sleep_level pds_level, uint32_t sleep_time);

Arm the timed wakeup and enter PDS sleep.

Masks all wakeup sources and clears pending wake events, arms the RTC compare for sleep_time (and, on IPRO7, the GPIO pins armed with pm_pds_gpio_wakeup_set()), then calls pm_pds_enable().

A completed PDS sleep resets the CPU: the boot ROM continues at the callback set with pm_set_wakeup_callback() or performs a normal boot. The function therefore returns only when the core did not power down (see pm_pds_enable()). To sleep and continue after the call, use hal_lp_enter().

pm_pds_gpio_wakeup_set¶

int pm_pds_gpio_wakeup_set(uint8_t pin, uint8_t trigger);

Arm a GPIO as a PDS wakeup source (IPRO7 only).

PDS keeps the GPIO pad logic powered, so ordinary GPIOs can wake the chip (HBN only has the always-on pads). The hardware groups the pins (GPIO0-3, 4-7, 8-9, 20-23, 24-27, 28-31, 32-35, 36-39, 40-41) and the trigger is set per group, so pins in one group share the trigger of the last call for that group. GPIO10 to GPIO19 cannot wake the chip from PDS.

The pin's PDS pad configuration is set right away to input with the pull-up enabled. The arming takes effect at the next pm_pds_mode_enter() (also when called through hal_lp_enter()) and stays until pm_pds_gpio_wakeup_unset() or pm_pds_gpio_wakeup_clear().

pm_pds_gpio_wakeup_clear¶

void pm_pds_gpio_wakeup_clear(void);

Disarm all GPIO wakeup pins armed with pm_pds_gpio_wakeup_set() (IPRO7 only).

pm_pds_gpio_wakeup_unset¶

void pm_pds_gpio_wakeup_unset(uint8_t pin);

Disarm one GPIO wakeup pin armed with pm_pds_gpio_wakeup_set() (IPRO7 only).

The pin group stays armed while another pin of the group is armed.

pm_pds_gpio_wakeup_dump¶

void pm_pds_gpio_wakeup_dump(void);

Print the PDS GPIO wakeup configuration and the pad levels PDS currently sees (IPRO7 only).

Applies the pending GPIO arming to the hardware first (as the next PDS entry would), then prints the PDS GPIO registers and wakeup-source enables. Does not enter sleep. Intended for debugging a GPIO wakeup that does not trigger.

pm_pds_gpio_wakeup_source¶

int pm_pds_gpio_wakeup_source(void);

Get the GPIO that woke the chip from PDS (IPRO7 only).

Call it after the wake-up and before the next PDS entry.

Returns: The lowest armed GPIO number whose PDS wakeup event is pending, or -1 if the wake-up was not caused by an armed GPIO.

pm_pds_rtc_target_override_set¶

void pm_pds_rtc_target_override_set(uint64_t target_ticks);

Set an absolute RTC wake-up time for the next PDS entry (IPRO7 only).

The next pm_pds_mode_enter() call with a non-zero sleep time arms the RTC compare at target_ticks instead of "now + sleep time", and consumes the setting. If the target is not in the future it is ignored and the relative sleep time is used. Use it when the deadline is already known as an absolute RTC count, so no relative time has to be derived from it.

pm_pds_wfi_fallback_set¶

void pm_pds_wfi_fallback_set(uint64_t counts);

Bound the WFI of the next PDS entry (IPRO7 only).

If the core is still running counts machine-timer counts after the WFI that enters PDS, the machine timer ends the WFI and pm_pds_enable() returns (hal_lp_enter() then reports HAL_LP_ERR_ENTRY_ABORTED). With 0 the machine-timer compare is parked and the WFI waits until PDS engages. The setting is consumed by the next pm_pds_enable(). hal_lp_set_entry_guard() sets it in microseconds.

pm_pds_resleep¶

void pm_pds_resleep(uint32_t sleep_time);

Re-enter PDS directly from the wake-up path (IPRO6 only).

Used by the IPRO6 Wi-Fi DTIM wake flow to go back to sleep without resuming the full firmware. Runs from TCM and does not return. On IPRO7 this is an empty function that returns immediately; IPRO7 resumes the firmware through hal_lp_enter() instead.

pm_hbn_mode_enter¶

void pm_hbn_mode_enter(enum pm_hbn_sleep_level hbn_level, uint32_t sleep_time);

Enter HBN (hibernate) sleep.

Does not return.

Everything except the always-on domain is powered down and all RAM except HBN RAM (at PM_HBN_LEVEL_0) is lost; the wake-up is a full boot.

pm_set_wakeup_callback¶

void pm_set_wakeup_callback(void(*wakeup_callback)(void));

Set the code the boot ROM jumps to after a PDS wake-up.

Without a callback, a PDS wake-up performs a normal boot. The callback runs directly after the boot ROM, before any start-up code, with the CPU freshly reset; it must not depend on XIP flash or on CPU state from before the sleep.

pm_clear_wakeup_callback¶

void pm_clear_wakeup_callback(void);

Remove the wake-up callback; the next PDS wake-up performs a normal boot.

pm_pds_sleep_level¶

PDS sleep levels.

PM_PDS_LEVEL_31 selects the deepest PDS level on every chip; the HAL maps it to the matching hardware configuration, so callers pass the same value on IPRO7 and IPRO6.

pm_hbn_sleep_level¶

HBN (hibernate) levels.

Use PM_HBN_LEVEL_0 when HBN RAM contents must survive; deeper levels also power down parts of the always-on domain.

PM_PDS_CFG_Type¶

PDS entry configuration passed to pm_pds_enable().

pm_pds_mode_enter() fills it with the HAL defaults. pm_pds_enable() currently reads only pdsLevel, sleepTime and ocramRetetion; the other fields are kept for source compatibility and do not change the sleep.

Macros¶

hal_pm_util.h¶

#include "hal_pm_util.h" (Source)

Section attributes for code and data that must run from PDS retained RAM.

Legacy header of the PDS helper module. The helper functions it used to declare are not part of the HAL build; use hal_lp.h and hal_pm.h instead.

Macros¶

hal_lp.h¶

#include "hal_lp.h" (Source)

Low-power framework (IPRO7): PDS sleep with resume, HBN fast-boot sleep, wake-up hooks and sleep timing.

hal_lp_enter() puts the chip into PDS level 31 and returns to the caller after the wake-up, as if the call had simply blocked: clocks, flash XIP access, PSRAM and the interrupt controller are restored before it returns. Peripherals that lose their configuration in PDS are re-initialized by the application, typically in a wake-up hook (hal_lp_register_wakeup_hook()). hal_lp_enter_fastboot() instead hibernates (HBN); the wake-up is a full boot that can be recognized with hal_lp_is_fastboot_wakeup().

Typical use:

hal_lp_init();                       // once, after start-up

hal_lp_cfg_t cfg = { 0 };
cfg.rtc_wakeup_en = 1;
cfg.rtc_sleep_us  = 500000;          // 500 ms
hal_lp_result_t res;
int reason = hal_lp_enter(&cfg, &res);
if (reason >= 0 && (reason & HAL_LP_WAKEUP_RTC)) {
    // woke up from the RTC; res.sleep_duration_us holds the time slept
}

Times are in microseconds unless stated otherwise; RTC ticks are periods of the 32.768 kHz clock. See hal_pm.h for the underlying PDS controls (GPIO wake pins, 32 kHz clock source, domain policy).

hal_lp_set_timing_policy¶

void hal_lp_set_timing_policy(uint32_t policy, uint32_t pds_wakeup_delay_us);

Set the sleep timing policy.

hal_lp_get_timing_policy¶

void hal_lp_get_timing_policy(uint32_t *policy, uint32_t *pds_wakeup_delay_us);

Get the sleep timing policy.

hal_lp_us_to_rtc_cnt¶

uint32_t hal_lp_us_to_rtc_cnt(uint64_t us);

Convert microseconds to RTC ticks according to the timing policy.

Returns: RTC ticks, rounded down: exact with HAL_LP_TIMING_POLICY_EXACT_US_TO_RTC, otherwise HAL_LP_US_TO_RTC_CNT(). Truncated to 32 bits.

hal_lp_get_pds_wakeup_delay_us¶

uint32_t hal_lp_get_pds_wakeup_delay_us(void);

Get the PDS wake-up latency currently in effect.

Returns: The latency set with hal_lp_set_timing_policy() when HAL_LP_TIMING_POLICY_PDS_WAKE_DELAY_VALID is set, otherwise HAL_LP_PDS_WAKEUP_DELAY_US, in microseconds.

hal_lp_init¶

int hal_lp_init(void);

Initialize the low-power framework.

Clears the framework state (including the RC32K ready flag), records the flash and PSRAM configuration needed to restore them after a wake-up, and installs the wake-up code in HBN RAM. Registered wake-up hooks are kept.

Returns: Always 0.

hal_lp_enter¶

int hal_lp_enter(hal_lp_cfg_t *cfg, hal_lp_result_t *result);

Enter PDS sleep and return after the wake-up.

The call blocks until the chip wakes up. In order, it:

1. consumes the entry guard set with hal_lp_set_entry_guard();
2. if cfg requests no GPIO wake-up and has no gpio_cfg, uses the configuration registered with hal_lp_gpio_wakeup_cfg() (and stores it in cfg);
3. calls pre_sleep_cb, then disables interrupts;
4. programs the GPIO wake-up pins and enters PDS level 31 with the RTC timer set to rtc_sleep_us minus the wake-up latency (see hal_lp_get_pds_wakeup_delay_us()), but at least HAL_LP_PDS_WAKEUP_MIN_US;
5. after the wake-up restores clocks, flash XIP access, PSRAM and the interrupt controller, and re-enables interrupts if they were enabled on entry;
6. runs the wake-up hooks, then post_wakeup_cb, and fills result.

Returns: HAL_LP_WAKEUP_* bits of the wake-up source (0 if none was identified) on success, or a negative value:

hal_lp_set_entry_guard¶

void hal_lp_set_entry_guard(bool abort_on_pending_irq, uint32_t entry_fallback_us);

Set entry safeguards for the next hal_lp_enter() call only.

The settings are consumed by the next hal_lp_enter(), whatever its outcome. They are kept outside hal_lp_cfg_t so that the layout of that structure stays unchanged for code built against earlier versions of this header.

hal_lp_enter_fastboot¶

int hal_lp_enter_fastboot(hal_lp_cfg_t *cfg);

Hibernate (HBN level 0); the wake-up is a full boot.

All RAM except the 4 KB HBN RAM is lost. Before entering HBN the function calls pre_sleep_cb, saves the boot parameters to HBN RAM (so that the next boot can use them), fills the wake context (hal_hbnram_lp_wake_ctx_t: requested wake-up sources, RTC count, wake counter), sets BOOT_FLAG_LP_FASTBOOT and arms the RTC timer for rtc_sleep_us (with the same minimum and latency handling as hal_lp_enter()). Everything the application needs after the wake-up must be stored in HBN RAM before this call, for example in hal_hbnram_lp_wake_ctx_t::reserved.

After the wake-up, the firmware detects it with hal_lp_is_fastboot_wakeup() and reads the context with hal_lp_get_wake_context().

Returns: Does not return on success.

hal_lp_is_fastboot_wakeup¶

bool hal_lp_is_fastboot_wakeup(void);

Check whether this boot is a wake-up from hal_lp_enter_fastboot().

Checks the wake-context magic and BOOT_FLAG_LP_FASTBOOT, and clears the flag, so only the first call after such a wake-up returns true. Safe to call early in main().

Returns: true if this boot resumed from hal_lp_enter_fastboot(), false otherwise.

hal_lp_get_wake_context¶

const volatile hal_hbnram_lp_wake_ctx_t * hal_lp_get_wake_context(void);

Get the wake context written by hal_lp_enter_fastboot().

The contents are meaningful when hal_lp_is_fastboot_wakeup() has returned true (or hal_hbnram_lp_wake_ctx_t::magic is HAL_HBNRAM_LP_WAKE_CTX_MAGIC).

Returns: Pointer to the context in HBN RAM; never NULL.

hal_lp_gpio_wakeup_cfg¶

int hal_lp_gpio_wakeup_cfg(hal_lp_gpio_cfg_t *cfg);

Register a default GPIO wake-up configuration.

hal_lp_enter() and hal_lp_enter_fastboot() use it when the request passed to them has gpio_wakeup_en = 0 and gpio_cfg = NULL. Only the pointer is stored, so the configuration must stay valid; NULL removes it.

Returns: Always 0.

hal_lp_get_wakeup_reason¶

int hal_lp_get_wakeup_reason(void);

Get the wake-up reason of the last hal_lp_enter() sleep.

Returns: HAL_LP_WAKEUP_* bits; HAL_LP_WAKEUP_UNKNOWN (0) if no source was identified.

hal_lp_get_wakeup_gpio¶

uint32_t hal_lp_get_wakeup_gpio(void);

Get the GPIO bits of the last wake-up.

Returns: GPIO wake bits; always 0 on IPRO7. Use pm_pds_gpio_wakeup_source() to find the pin.

hal_lp_register_wakeup_hook¶

int hal_lp_register_wakeup_hook(hal_lp_wakeup_hook_t hook, void *arg);

Register a wake-up hook.

Hooks are called in registration order. Up to 8 hooks can be registered; registering a hook that is already registered only replaces its argument.

hal_lp_unregister_wakeup_hook¶

int hal_lp_unregister_wakeup_hook(hal_lp_wakeup_hook_t hook);

Unregister a wake-up hook.

hal_lp_wakeup_hook_count¶

uint32_t hal_lp_wakeup_hook_count(void);

Get the number of registered wake-up hooks.

Hooks run after every hal_lp_enter() wake-up, whichever component requested the sleep.

Returns: Number of registered hooks.

hal_lp_get_virtual_us¶

uint64_t hal_lp_get_virtual_us(void);

Get a time stamp that keeps counting during sleep, in microseconds.

Derived from the always-on RTC counter (32.768 kHz, about 30.5 us resolution), which keeps running in PDS. Its accuracy is that of the selected 32 kHz clock. The count restarts when the RTC counter is cleared (power-on reset, rtc_init()).

Returns: Time in microseconds.

hal_lp_get_virtual_ms¶

uint64_t hal_lp_get_virtual_ms(void);

Get the time stamp of hal_lp_get_virtual_us() in milliseconds.

Returns: Time in milliseconds.

hal_lp_rtc_clk_sel¶

void hal_lp_rtc_clk_sel(bool use_xtal32k);

Select the clock source of the RTC and the sleep timer.

Only switches the selection; the 32.768 kHz crystal must already be running (pm_pds_set_32k_src() powers it up and also records the choice for later PDS entries).

hal_lp_rc32k_coarse_adj¶

int hal_lp_rc32k_coarse_adj(uint32_t expect_time, uint32_t actual_time);

Apply a coarse frequency correction to the RC32K oscillator.

Adjusts the oscillator in proportion to the relative error (actual_time - expect_time) / expect_time, measured by the caller over the same interval with a reference clock and with the RC32K clock.

hal_lp_set_rc32k_ready¶

void hal_lp_set_rc32k_ready(uint8_t ready);

Mark the RC32K calibration as complete or not.

While marked ready, hal_lp_rc32k_coarse_adj() makes no further changes. The flag is cleared by hal_lp_init().

hal_lp_get_rc32k_ready¶

uint8_t hal_lp_get_rc32k_ready(void);

Get the RC32K ready flag set with hal_lp_set_rc32k_ready().

Returns: 1 if ready, 0 if not.

hal_lp_xip_recovery¶

void hal_lp_xip_recovery(void);

Restore flash XIP access after a PDS wake-up.

Called automatically on the hal_lp_enter() wake-up path; only custom wake-up code that runs before that point needs to call it. Does nothing unless a recovery is pending and hal_lp_init() has recorded the flash configuration.

hal_lp_get_psram_dqs_cfg¶

uint16_t hal_lp_get_psram_dqs_cfg(void);

Get the PSRAM calibration value that hal_lp_init() records for the wake-up path.

Weak function: the default returns 0 (no PSRAM). Builds with CONFIG_USE_PSRAM provide the calibrated value (see hal_psram.h).

Returns: PSRAM DQS configuration, or 0 when there is no PSRAM.

hal_lp_psram_restore¶

void hal_lp_psram_restore(void);

Re-initialize the PSRAM after a PDS wake-up.

Called automatically by the framework when a PSRAM configuration was recorded (hal_lp_get_psram_dqs_cfg() returned non-zero), both after a wake-up and after an aborted entry. Weak function: the default does nothing; builds with CONFIG_USE_PSRAM provide the implementation.

hal_lp_gpio_trig_t¶

GPIO wake-up trigger mode.

hal_lp_gpio_res_t¶

GPIO pull resistor for wake-up pins.

hal_lp_gpio_pin_cfg_t¶

Per-pin GPIO wake-up configuration.

hal_lp_gpio_cfg_t¶

GPIO wake-up configuration for hal_lp_enter().

Each pin in wakeup_mask is configured as an input with default_res and unmasked as a PDS wake-up pin; the trigger mode is programmed for the pin groups GPIO0-3, GPIO4-7 and GPIO8-9.

hal_lp_cfg_t¶

Sleep request for hal_lp_enter() and hal_lp_enter_fastboot().

Zero-initialize the structure and set the fields you need.

hal_lp_result_t¶

Result of hal_lp_enter().

Typedefs¶

Macros¶

lp_uart.h¶

#include "lp_uart.h" (Source)

Minimal polled UART output for low-power wake-up code.

Debug output for code that runs while the chip wakes up from sleep, before the normal UART driver and XIP flash are available. The functions run from TCM and busy-wait on the UART transmit FIFO; they do not use interrupts or DMA. String arguments must also be readable at that point (not in XIP flash before it has been restored).

lp_uart_init¶

void lp_uart_init(int uart_id, uint32_t baudrate);

Set up a UART for transmit and receive with minimal initialization.

Sets the bit period for TX and RX and enables both directions; pin multiplexing is not changed, and the UART clock is assumed to be the 32 MHz XCLK.

lp_uart_putc¶

void lp_uart_putc(int uart_id, char c);

Send one character; waits until the transmit FIFO has space.

lp_uart_puts¶

void lp_uart_puts(int uart_id, const char *str);

Send a NUL-terminated string; each '\n' is sent as CR LF.

lp_uart_puthex¶

void lp_uart_puthex(int uart_id, uint32_t val);

Send a value as 0x followed by 8 upper-case hexadecimal digits.

lp_uart_putdec¶

void lp_uart_putdec(int uart_id, uint32_t val);

Send an unsigned value in decimal, without leading zeros.

Macros¶