power: Add notifier API

Get rid of weak functions adding a new API to register an object to
receive notifications when the system changes power state.

Signed-off-by: Flavio Ceolin <[email protected]>

Author: Flavio Ceolin

include/power/power.h

@@ -65,6 +65,34 @@ extern unsigned char pm_idle_exit_notify;
  * @{
  */
 
+/**
+ * Power management notifier struct
+ *
+ * This struct contains callbacks that are called when the target enters and
+ * exits power states.
+ *
+ * As currently implemented the entry callback is invoked when
+ * transitioning from PM_STATE_ACTIVE to another state, and the exit
+ * callback is invoked when transitioning from a non-active state to
+ * PM_STATE_ACTIVE. This behavior may change in the future.
+ *
+ * @note These callbacks can be called from the ISR of the event
+ *       that caused the kernel exit from idling.
+ */
+struct pm_notifier {
+	sys_snode_t _node;
+	/**
+	 * Application defined function for doing any target specific operations
+	 * for power state entry.
+	 */
+	void (*state_entry)(enum power_states state);
+	/**
+	 * Application defined function for doing any target specific operations
+	 * for power state exit.
+	 */
+	void (*state_exit)(enum power_states state);
+};
+
 /**
  * @brief Check if particular power state is a sleep state.
  *
@@ -299,20 +327,27 @@ enum power_states pm_system_suspend(int32_t ticks);
 void pm_power_state_exit_post_ops(enum power_states state);
 
 /**
- * @brief Application defined function for power state entry
+ * @brief Register a power management notifier
+ *
+ * Register the given notifier from the power management notification
+ * list.
  *
- * Application defined function for doing any target specific operations
- * for power state entry.
+ * @param notifier pm_notifier object to be registered.
  */
-void pm_notify_power_state_entry(enum power_states state);
+void pm_notifier_register(struct pm_notifier *notifier);
 
 /**
- * @brief Application defined function for sleep state exit
+ * @brief Unregister a power management notifier
+ *
+ * Remove the given notifier from the power management notification
+ * list. After that this object callbacks will not be called.
+ *
+ * @param notifier pm_notifier object to be unregistered.
  *
- * Application defined function for doing any target specific operations
- * for sleep state exit.
+ * @return 0 if the notifier was successfully removed, a negative value
+ * otherwise.
  */
-void pm_notify_power_state_exit(enum power_states state);
+int pm_notifier_unregister(struct pm_notifier *notifier);
 
 /**
  * @}

samples/boards/mec15xxevb_assy6853/power_management/src/power_mgmt.c

@@ -85,7 +85,7 @@ static void pm_latency_check(void)
 }
 
 /* Hooks to count entry/exit */
-void pm_notify_power_state_entry(enum power_states state)
+static void notify_pm_state_entry(enum power_states state)
 {
 	if (!checks_enabled) {
 		return;
@@ -106,7 +106,7 @@ void pm_notify_power_state_entry(enum power_states state)
 	}
 }
 
-void pm_notify_power_state_exit(enum power_states state)
+static void notify_pm_state_exit(enum power_states state)
 {
 	if (!checks_enabled) {
 		return;
@@ -251,6 +251,11 @@ static void resume_all_tasks(void)
 	k_thread_resume(&thread_b_id);
 }
 
+static struct pm_notifier notifier = {
+	.state_entry = notify_pm_state_entry,
+	.state_exit = notify_pm_state_exit,
+};
+
 int test_pwr_mgmt_multithread(bool use_logging, uint8_t cycles)
 {
 	uint8_t iterations = cycles;
@@ -260,6 +265,7 @@ int test_pwr_mgmt_multithread(bool use_logging, uint8_t cycles)
 	 * https://github.com/zephyrproject-rtos/zephyr/issues/20033
 	 */
 
+	pm_notifier_register(&notifier);
 	create_tasks();
 
 	LOG_WRN("PM multi-thread test started for cycles: %d, logging: %d",
@@ -312,6 +318,7 @@ int test_pwr_mgmt_multithread(bool use_logging, uint8_t cycles)
 	LOG_INF("PM multi-thread completed");
 	pm_check_counters(cycles);
 	pm_reset_counters();
+	pm_notifier_unregister(&notifier);
 
 	return 0;
 }
@@ -323,6 +330,7 @@ int test_pwr_mgmt_singlethread(bool use_logging, uint8_t cycles)
 	LOG_WRN("PM single-thread test started for cycles: %d, logging: %d",
 		cycles, use_logging);
 
+	pm_notifier_register(&notifier);
 	checks_enabled = true;
 	while (iterations-- > 0) {
 
@@ -359,6 +367,7 @@ int test_pwr_mgmt_singlethread(bool use_logging, uint8_t cycles)
 	LOG_INF("PM single-thread completed");
 	pm_check_counters(cycles);
 	pm_reset_counters();
+	pm_notifier_unregister(&notifier);
 
 	return 0;
 }

subsys/power/power.c

@@ -18,6 +18,8 @@ LOG_MODULE_REGISTER(power);
 static int post_ops_done = 1;
 static enum power_states forced_pm_state = POWER_STATE_AUTO;
 static enum power_states pm_state;
+static sys_slist_t pm_notifiers = SYS_SLIST_STATIC_INIT(&pm_notifiers);
+static struct k_spinlock pm_notifier_lock;
 
 #ifdef CONFIG_PM_DEBUG
 
@@ -64,16 +66,6 @@ static void pm_log_debug_info(enum power_states state) { }
 void pm_dump_debug_info(void) { }
 #endif
 
-__weak void pm_notify_power_state_entry(enum power_states state)
-{
-	/* This function can be overridden by the application. */
-}
-
-__weak void pm_notify_power_state_exit(enum power_states state)
-{
-	/* This function can be overridden by the application. */
-}
-
 void pm_power_state_force(enum power_states state)
 {
 	__ASSERT(state >= POWER_STATE_AUTO &&
@@ -89,12 +81,38 @@ void pm_power_state_force(enum power_states state)
 #endif
 }
 
+/*
+ * Function called to notify when the system is entering / exiting a
+ * power state
+ */
+static inline void pm_state_notify(bool entering_state)
+{
+	struct pm_notifier *notifier;
+	k_spinlock_key_t pm_notifier_key;
+	void (*callback)(enum power_states state);
+
+	pm_notifier_key = k_spin_lock(&pm_notifier_lock);
+	SYS_SLIST_FOR_EACH_CONTAINER(&pm_notifiers, notifier, _node) {
+		if (entering_state) {
+			callback = notifier->state_entry;
+		} else {
+			callback = notifier->state_exit;
+		}
+
+		if (callback) {
+			callback(pm_state);
+		}
+	}
+	k_spin_unlock(&pm_notifier_lock, pm_notifier_key);
+}
+
 
 static enum power_states _handle_device_abort(enum power_states state)
 {
 	LOG_DBG("Some devices didn't enter suspend state!");
 	pm_resume_devices();
-	pm_notify_power_state_exit(pm_state);
+	pm_state_notify(false);
+
 	pm_state = POWER_STATE_ACTIVE;
 	return pm_state;
 }
@@ -118,7 +136,7 @@ static enum power_states pm_policy_mgr(int32_t ticks)
 		     pm_is_deep_sleep_state(pm_state) : 0;
 
 	post_ops_done = 0;
-	pm_notify_power_state_entry(pm_state);
+	pm_state_notify(true);
 
 	if (deep_sleep) {
 		/* Suspend peripherals. */
@@ -161,7 +179,7 @@ static enum power_states pm_policy_mgr(int32_t ticks)
 		post_ops_done = 1;
 		/* clear forced_pm_state */
 		forced_pm_state = POWER_STATE_AUTO;
-		pm_notify_power_state_exit(pm_state);
+		pm_state_notify(false);
 		pm_power_state_exit_post_ops(pm_state);
 	}
 
@@ -193,11 +211,33 @@ void pm_system_resume(void)
 	 */
 	if (!post_ops_done) {
 		post_ops_done = 1;
-		pm_notify_power_state_exit(pm_state);
+		pm_state_notify(false);
 		pm_power_state_exit_post_ops(pm_state);
 	}
 }
 
+void pm_notifier_register(struct pm_notifier *notifier)
+{
+	k_spinlock_key_t pm_notifier_key = k_spin_lock(&pm_notifier_lock);
+
+	sys_slist_append(&pm_notifiers, &notifier->_node);
+	k_spin_unlock(&pm_notifier_lock, pm_notifier_key);
+}
+
+int pm_notifier_unregister(struct pm_notifier *notifier)
+{
+	int ret = -EINVAL;
+	k_spinlock_key_t pm_notifier_key;
+
+	pm_notifier_key = k_spin_lock(&pm_notifier_lock);
+	if (sys_slist_find_and_remove(&pm_notifiers, &(notifier->_node))) {
+		ret = 0;
+	}
+	k_spin_unlock(&pm_notifier_lock, pm_notifier_key);
+
+	return ret;
+}
+
 #if CONFIG_PM_DEVICE
 static int pm_init(const struct device *dev)
 {
@@ -206,6 +246,5 @@ static int pm_init(const struct device *dev)
 	pm_create_device_list();
 	return 0;
 }
-
 SYS_INIT(pm_init, APPLICATION, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT);
 #endif /* CONFIG_PM_DEVICE */

tests/subsys/power/power_mgmt/src/main.c

@@ -32,7 +32,7 @@ static struct dummy_driver_api *api;
  */
 __weak void pm_power_state_set(enum power_states state)
 {
-	/* at this point, pm_notify_power_state_entry() implemented in
+	/* at this point, notify_pm_state_entry() implemented in
 	 * this file has been called and set_pm should have been set
 	 */
 	zassert_true(set_pm == true,
@@ -88,7 +88,7 @@ enum power_states pm_policy_next_state(int ticks)
 }
 
 /* implement in application, called by idle thread */
-void pm_notify_power_state_entry(enum power_states state)
+static void notify_pm_state_entry(enum power_states state)
 {
 	uint32_t device_power_state;
 
@@ -106,7 +106,7 @@ void pm_notify_power_state_entry(enum power_states state)
 }
 
 /* implement in application, called by idle thread */
-void pm_notify_power_state_exit(enum power_states state)
+static void notify_pm_state_exit(enum power_states state)
 {
 	uint32_t device_power_state;
 
@@ -152,9 +152,9 @@ void test_power_idle(void)
  *  - The system support control of power state ordering between
  *    subsystems and devices
  *  - The application can control system power state transitions in idle thread
- *    through pm_notify_power_state_entry and pm_notify_power_state_exit
+ *    through pm_notify_pm_state_entry and pm_notify_pm_state_exit
  *
- * @see pm_notify_power_state_entry(), pm_notify_power_state_exit()
+ * @see pm_notify_pm_state_entry(), pm_notify_pm_state_exit()
  *
  * @ingroup power_tests
  */
@@ -211,6 +211,13 @@ void test_teardown(void)
 
 void test_main(void)
 {
+	struct pm_notifier notifier = {
+		.state_entry = notify_pm_state_entry,
+		.state_exit = notify_pm_state_exit,
+	};
+
+	pm_notifier_register(&notifier);
+
 	ztest_test_suite(power_management_test,
 			 ztest_1cpu_unit_test(test_power_idle),
 			 ztest_unit_test_setup_teardown(test_power_state_trans,
@@ -221,4 +228,5 @@ void test_main(void)
 						test_setup,
 						test_teardown));
 	ztest_run_test_suite(power_management_test);
+	pm_notifier_unregister(&notifier);
 }

tests/subsys/power/power_mgmt_soc/src/power_mgmt.c

@@ -68,8 +68,7 @@ static void pm_latency_check(void)
 			"Sleep entry latency is higher than expected");
 }
 
-/* Hooks to count entry/exit */
-void pm_notify_power_state_entry(enum power_states state)
+static void notify_pm_state_entry(enum power_states state)
 {
 	if (!checks_enabled) {
 		return;
@@ -84,7 +83,7 @@ void pm_notify_power_state_entry(enum power_states state)
 	}
 }
 
-void pm_notify_power_state_exit(enum power_states state)
+static void notify_pm_state_exit(enum power_states state)
 {
 	if (!checks_enabled) {
 		return;
@@ -97,6 +96,11 @@ void pm_notify_power_state_exit(enum power_states state)
 	}
 }
 
+static struct pm_notifier notifier = {
+	.state_entry = notify_pm_state_entry,
+	.state_exit = notify_pm_state_exit,
+};
+
 static void pm_check_counters(uint8_t cycles)
 {
 	for (int i = 0; i < SLP_STATES_SUPPORTED; i++) {
@@ -218,6 +222,7 @@ int test_pwr_mgmt_multithread(uint8_t cycles)
 {
 	uint8_t iterations = cycles;
 
+	pm_notifier_register(&notifier);
 	create_tasks();
 
 	LOG_INF("PM multi-thread test started for cycles: %d", cycles);
@@ -257,6 +262,7 @@ int test_pwr_mgmt_multithread(uint8_t cycles)
 	}
 
 	destroy_tasks();
+	pm_notifier_unregister(&notifier);
 
 	LOG_INF("PM multi-thread completed");
 	pm_check_counters(cycles);
@@ -271,6 +277,7 @@ int test_pwr_mgmt_singlethread(uint8_t cycles)
 
 	LOG_INF("PM single-thread test started for cycles: %d", cycles);
 
+	pm_notifier_register(&notifier);
 	checks_enabled = true;
 	while (iterations-- > 0) {
 
@@ -296,6 +303,7 @@ int test_pwr_mgmt_singlethread(uint8_t cycles)
 		pm_exit_marker();
 	}
 
+	pm_notifier_unregister(&notifier);
 	LOG_INF("PM single-thread completed");
 	pm_check_counters(cycles);
 	pm_reset_counters();