soc: st: stm32: Provide PM support for STM32WB0x

HoZHel · HoZHel · commit 85f6d6bdf08b · 2025-08-12T13:46:39.000+02:00
Provide PM support, specifically suspend-to-ram, for STM32WB0x.

Enable STM32_RADIO_TIMER Kconfig parameter when PM is set.

Signed-off-by: Ali Hozhabri &lt;ali.hozhabri@st.com&gt;
diff --git a/drivers/timer/Kconfig.stm32_radio b/drivers/timer/Kconfig.stm32_radio
@@ -5,7 +5,7 @@
 
 config STM32_RADIO_TIMER
 	bool "STM32 Radio Timer for WB0x"
-	default y if BT
+	default y if PM || BT
 	depends on SOC_SERIES_STM32WB0X
 	select USE_STM32_HAL_RADIO_TIMER
 	select TICKLESS_CAPABLE
diff --git a/drivers/timer/stm32_radio_timer.c b/drivers/timer/stm32_radio_timer.c
@@ -37,6 +37,10 @@ LOG_MODULE_REGISTER(radio_timer_driver);
 BUILD_ASSERT(DT_NODE_HAS_STATUS(DT_NODELABEL(clk_lsi), disabled),
 	     "At the moment, LSI is not supported");
 
+#if (defined(CONFIG_SOC_STM32WB06) || defined(CONFIG_SOC_STM32WB07)) && defined(CONFIG_PM)
+#error "At the moment, PM is not supported for WB06 & WB07"
+#endif /* (CONFIG_SOC_STM32WB06 || CONFIG_SOC_STM32WB07) && CONFIG_PM */
+
 /* Translate STU to MTU and vice versa. It is implemented by using integer operations. */
 uint32_t blue_unit_conversion(uint32_t time, uint32_t period_freq, uint32_t thr);
 static uint64_t announced_cycles;
diff --git a/dts/arm/st/wb0/stm32wb0.dtsi b/dts/arm/st/wb0/stm32wb0.dtsi
@@ -33,8 +33,27 @@
 		cpu0: cpu@0 {
 			device_type = "cpu";
 			compatible = "arm,cortex-m0+";
+			cpu-power-states = <&deepstop>;
 			reg = <0>;
 		};
+
+		power-states {
+			deepstop: state0 {
+				compatible = "zephyr,power-state";
+				power-state-name = "suspend-to-ram";
+				substate-id = <0>;
+
+				/* One milisecond seems reasonable for now. */
+				min-residency-us = <1000>;
+
+				/**
+				 * tWUDEEPSTOP value from datasheets:
+				 *  STM32WB06/WB07: typ. 110µs
+				 *  STM32WB05/WB09: typ. 170µs
+				 */
+				exit-latency-us = <550>;
+			};
+		};
 	};
 
 	sram0: memory@20000000 {
diff --git a/soc/st/stm32/stm32wb0x/CMakeLists.txt b/soc/st/stm32/stm32wb0x/CMakeLists.txt
@@ -3,6 +3,7 @@
 zephyr_include_directories(${ZEPHYR_BASE}/drivers)
 
 zephyr_sources(soc.c)
+zephyr_sources_ifdef(CONFIG_PM power.c s2ram_marking.S)
 zephyr_include_directories(.)
 
 zephyr_linker_sources(RAM_SECTIONS ram_sections.ld)
diff --git a/soc/st/stm32/stm32wb0x/Kconfig b/soc/st/stm32/stm32wb0x/Kconfig
@@ -9,8 +9,20 @@ config SOC_SERIES_STM32WB0X
 	select CPU_CORTEX_M_HAS_VTOR
 	select CPU_CORTEX_M_HAS_SYSTICK
 	select CPU_HAS_ARM_MPU
+	select HAS_PM
 	select HAS_STM32CUBE
 	select SOC_EARLY_INIT_HOOK
 	# WB0x has a ROM bootloader executed at reset,
 	# which makes the following option required
 	select INIT_ARCH_HW_AT_BOOT
+
+	# STM32WB0 series only supports suspend-to-RAM as low-power mode.
+	# Make sure that S2RAM support is enabled if Power Management is
+	# selected by the user. PM_DEVICE is also required because devices
+	# need to be reinitialized after resuming. CUSTOM_MARKING is enabled
+	# to use SoC-specific hardware registers for resume detection, and
+	# CORTEX_M_SYSTICK_RESET_BY_LOW_POWER is required because the SoC
+	# is reset upon wake-up from Deepstop.
+	imply PM_DEVICE if PM
+	imply PM_S2RAM
+	imply PM_S2RAM_CUSTOM_MARKING
diff --git a/soc/st/stm32/stm32wb0x/power.c b/soc/st/stm32/stm32wb0x/power.c
@@ -0,0 +1,230 @@
+/*
+ * Copyright (c) 2025 STMicroelectronics.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * STM32WB0 Deepstop implementation for Power Management framework
+ *
+ * TODO:
+ *	- document the control flow on PM transitions
+ *	- assertions around system configuration
+ *	  (e.g., valid slow clock selected, RTC enabled, ...)
+ *	- ...
+ */
+#include <zephyr/kernel.h>
+#include <zephyr/pm/pm.h>
+#include <zephyr/sys_clock.h>
+#include <zephyr/init.h>
+#include <zephyr/arch/common/pm_s2ram.h>
+
+/* Private headers in zephyr/drivers/... */
+#include <clock_control/clock_stm32_ll_common.h>
+
+#include <soc.h>
+#include <stm32_ll_pwr.h>
+#include <stm32_ll_rcc.h>
+#include <stm32_ll_cortex.h>
+#include <stm32_ll_system.h>
+
+#include <zephyr/logging/log.h>
+LOG_MODULE_DECLARE(soc, CONFIG_SOC_LOG_LEVEL);
+
+#if defined(CONFIG_SOC_STM32WB05XX) || defined(CONFIG_SOC_STM32WB09XX)
+#define HAS_GPIO_RETENTION 1
+#else
+#define HAS_GPIO_RETENTION 0
+#endif /* CONFIG_SOC_STM32WB05XX || CONFIG_SOC_STM32WB09XX */
+
+/**
+ * System-level state managed by PM callbacks
+ *
+ * Things that need to be preserved across Deepstop, but
+ * have no associated driver to backup and restore them.
+ */
+#define SRAM		DT_CHOSEN(zephyr_sram)
+#define BL_STK_SIZ	(20 * 4)	/* in bytes */
+#define BL_STK_TOP	((void *)(DT_REG_ADDR(SRAM) + DT_REG_SIZE(SRAM) - BL_STK_SIZ))
+static uint8_t bl_stk_area_backup[BL_STK_SIZ];
+
+uint32_t RCC_APB1ENR_vr, RCC_AHBENR_vr;
+
+static void save_system_level_state(void)
+{
+	/**
+	 * The STM32WB0 bootloader uses the end of SRAM as stack.
+	 * Since it is executed on every reset, including wakeup
+	 * from Deepstop, any data placed at the end of SRAM would
+	 * be corrupted.
+	 *
+	 * Backup these words for later restoration to avoid data
+	 * corruption. A much better solution would mark this part
+	 * of SRAM as unusable, but no easy solution was found to
+	 * achieve this.
+	 */
+	memcpy(bl_stk_area_backup, BL_STK_TOP, BL_STK_SIZ);
+}
+
+static void restore_system_level_state(void)
+{
+	/* Restore bootloader stack area */
+	memcpy(BL_STK_TOP, bl_stk_area_backup, BL_STK_SIZ);
+}
+
+/* Callback for arch_pm_s2ram_suspend */
+static int suspend_system_to_deepstop(void)
+{
+	/* Enable SLEEPDEEP to allow entry in Deepstop */
+	LL_LPM_EnableDeepSleep();
+
+	/* Complete all memory transactions */
+	__DSB();
+
+
+	/* Attempt entry in Deepstop */
+	__WFI();
+
+	/**
+	 * Make sure no meaningful instruction is
+	 * executed during the two cycles latency
+	 * it takes to power-gate the CPU.
+	 */
+	__NOP();
+	__NOP();
+
+	/**
+	 * This code is reached only if the device did not
+	 * enter Deepstop mode (e.g., because an interrupt
+	 * became pending during preparatory work).
+	 *
+	 * Disable SLEEPDEEP and return the appropriate error.
+	 */
+	LL_LPM_EnableSleep();
+
+	return -EBUSY;
+}
+
+/**
+ * Backup system state to save and configure power
+ * controller before entry in Deepstop mode
+ */
+static void prepare_for_deepstop_entry(void)
+{
+	/**
+	 * DEEPSTOP2 configuration is performed in familiy-wide code
+	 * instead of here (see `soc/st/stm32/common/soc_config.c`).
+	 *
+	 * RAMRET configuration is performed once during SoC init,
+	 * since it is retained across Deepstop (see `soc.c`).
+	 **/
+
+	/* Save the clock configuration. */
+	RCC_APB1ENR_vr = RCC->APB1ENR;
+	RCC_AHBENR_vr = RCC->AHBENR;
+
+	/* Clear wakeup reason flags (which inhibit Deepstop) */
+	LL_PWR_ClearWakeupSource(LL_PWR_WAKEUP_ALL);
+	LL_SYSCFG_PWRC_ClearIT(LL_SYSCFG_PWRC_WKUP);
+	LL_PWR_ClearDeepstopSeqFlag();
+	LL_PWR_EnableWU_EWBLEHCPU();
+
+#if HAS_GPIO_RETENTION
+	/**
+	 * Enable GPIO state retention in Deepstop if available.
+	 *
+	 * Do not enable this if low-power mode debugging has been
+	 * enabled via Kconfig, because it prevents the debugger
+	 * from staying connected to the SoC.
+	 */
+	if (!IS_ENABLED(CONFIG_STM32_ENABLE_DEBUG_SLEEP_STOP)) {
+		LL_PWR_EnableGPIORET();
+		LL_PWR_EnableDBGRET();
+	}
+#endif /* HAS_GPIO_RETENTION */
+	save_system_level_state();
+}
+
+/**
+ * @brief	Restore SoC-level configuration lost in Deepstop
+ * @note	This function must be called right after wakeup.
+ */
+static void post_resume_configuration(void)
+{
+	__ASSERT_NO_MSG(LL_PWR_GetDeepstopSeqFlag() == 1);
+
+	/**
+	 * VTOR has been reset to its default value: restore it.
+	 * (Note that RAM_VR.AppBase was filled during SoC init)
+	 */
+	SCB->VTOR = RAM_VR.AppBase;
+
+	/* Restore the clock configuration. */
+	RCC->AHBENR = RCC_AHBENR_vr;
+	RCC->APB1ENR = RCC_APB1ENR_vr;
+
+	/**
+	 * Restore other miscellanous system-level things.
+	 */
+	restore_system_level_state();
+}
+
+/**
+ * Power Management subsystem callbacks
+ */
+void pm_state_set(enum pm_state state, uint8_t substate_id)
+{
+	/* Ignore substate: STM32WB0 has only one low-power mode */
+	ARG_UNUSED(substate_id);
+
+	int res;
+
+	if (state != PM_STATE_SUSPEND_TO_RAM) {
+		/**
+		 * Deepstop is a suspend-to-RAM state.
+		 * Something is wrong if a different
+		 * power state has been requested.
+		 */
+		LOG_ERR("Unsupported power state %u", state);
+	}
+	prepare_for_deepstop_entry();
+
+	/* Select Deepstop low-power mode and suspend system */
+	LL_PWR_SetPowerMode(LL_PWR_MODE_DEEPSTOP);
+
+	res = arch_pm_s2ram_suspend(suspend_system_to_deepstop);
+
+	if (res >= 0) {
+		/**
+		 * Restore system configuration only if the SoC actually
+		 * entered Deepstop - otherwise, no state has been lost
+		 * and it would be a waste of time to do so.
+		 */
+		post_resume_configuration();
+	}	
+}
+
+void pm_state_exit_post_ops(enum pm_state state, uint8_t substate_id)
+{
+	ARG_UNUSED(state);
+	ARG_UNUSED(substate_id);
+
+	/**
+	 * We restore system state in @ref{post_resume_configuration}.
+	 * The only thing we may have to do is release GPIO retention,
+	 * which we have not done yet because we wanted the driver to
+	 * restore all configuration first.
+	 *
+	 * We also need to enable IRQs to fullfill the API contract.
+	 */
+#if HAS_GPIO_RETENTION
+	LL_PWR_DisableGPIORET();
+	LL_PWR_DisableDBGRET();
+#endif /* HAS_GPIO_RETENTION */
+
+#if defined(CONFIG_SOC_STM32WB06) || defined(CONFIG_SOC_STM32WB07)
+	irq_enable(RADIO_TIMER_TXRX_WKUP_IRQn);
+#endif /* CONFIG_SOC_STM32WB06 || CONFIG_SOC_STM32WB07 */
+	irq_enable(RADIO_TIMER_CPU_WKUP_IRQn);
+	irq_enable(RADIO_TIMER_ERROR_IRQn);
+	__enable_irq();
+}
diff --git a/soc/st/stm32/stm32wb0x/s2ram_marking.S b/soc/st/stm32/stm32wb0x/s2ram_marking.S
@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2025 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * STM32WB0-specific support code for suspend-to-RAM
+ */
+
+#include <zephyr/toolchain.h>
+#include <offsets_short.h>
+#include <zephyr/arch/cpu.h>
+#include <zephyr/arch/common/pm_s2ram.h>
+
+/* Read RCC and PWRC base from Device Tree */
+#include <zephyr/devicetree.h>
+
+#define RCC_CSR			(DT_REG_ADDR(DT_NODELABEL(rcc)) + 0x94)
+#define PWR_BASE		DT_REG_ADDR(DT_NODELABEL(pwrc))
+#define PWR_SR1			0x10
+#define PWR_SR3			0x38
+
+_ASM_FILE_PROLOGUE
+
+GTEXT(pm_s2ram_mark_set)
+SECTION_FUNC(TEXT, pm_s2ram_mark_set)
+	/*
+	 * Managed by hardware - nothing to do here.
+	 */
+	bx lr
+
+/**
+ * @brief	Check whether SoC is waking up from Deepstop
+ * @returns	1 if SoC is waking up from Deepstop, 0 otherwise.
+ * @note	Registers are cleared by hardware upon reset, or
+ * 		the SoC PM code layer upon entry in Deepstop, so
+ *		this function does not clear the registers.
+ */
+GTEXT(pm_s2ram_mark_check_and_clear)
+SECTION_FUNC(TEXT, pm_s2ram_mark_check_and_clear)
+	/*
+	 * Check for Deepstop exit on wakeup event:
+	 *	- RCC_CSR is zero
+	 *	- PWRC.EXTSRR has bit DEEPSTOPF set
+	 *		(Redundant => unchecked)
+	 *	- Either PWRC_SR1 or PWRC_SR3 is non-zero
+	 *
+	 * Note that we don't have to clear any register since
+	 * they are automatically updated on reset/wake-up.
+	 *
+	 * IMPLEMENTATIONS DETAILS:
+	 *	r1 must not be modified and the stack must not be
+	 *	used by this function as of writing, due to the
+	 *	current implementation of arch_pm_s2ram_resume.
+	 *	As such, we can only use r0, r2 and r3 here.
+	 *
+	 *	N.B.: r12 is also volatile for the ARM ABI, but it
+	 *	cannot be used for most operations on ARMv6-M due
+	 *	to 16-bit Thumb limitations, so we might as well
+	 *	avoid using it entirely.
+	 */
+	ldr	r0, =RCC_CSR
+	ldr	r2, [r0]
+	cmp	r2, #0
+	bne	not_deepstop_wakeup
+
+	ldr	r0, =PWR_BASE
+	ldr	r2, [r0, #PWR_SR1]
+	ldr	r3, [r0, #PWR_SR3]
+	orrs	r2, r2, r3
+	beq	not_deepstop_wakeup
+
+	/**
+	 * All conditions met: this is a wakeup from Deepstop.
+	 */
+	movs	r0, #1
+	bx	lr
+
+not_deepstop_wakeup:
+	movs	r0, #0
+	bx      lr
