pm: policy: latency: Add support for immediate action

Remove API for subscription to the latency change. This API was added
to support executing immediate action on latency change but
implementation was calling subscriber callbacks with interrupts locked
which is not desirable. In general, it is non-trivial task to
manage multiple requests and perform asynchronous action for the
top request. On-off manager implements that for binary case.

Additionally, API was missing a notifiction to the requestor when
immediate action is completed and it is required for the used to
know when requested latency requirement is fulfilled.

Proposed API is adding a possible notification for request and
update and adds option to add a manager for controlling immediate
action. Added notifications make sense only if immediate action
is used. Immediate action implements support for binary case
where there is a single action that is performed when latency
is below a given threshold. In future it can be extended to
support gradual manager.

Signed-off-by: Krzysztof Chruściński <[email protected]>

Author: nordic-krch

include/zephyr/pm/policy.h

@@ -13,6 +13,7 @@
 #include <zephyr/device.h>
 #include <zephyr/pm/state.h>
 #include <zephyr/sys/slist.h>
+#include <zephyr/sys/onoff.h>
 #include <zephyr/toolchain.h>
 
 #ifdef __cplusplus
@@ -27,37 +28,29 @@ extern "C" {
  */
 
 /**
- * @brief Callback to notify when maximum latency changes.
- *
- * @param latency New maximum latency. Positive value represents latency in
- * microseconds. SYS_FOREVER_US value lifts the latency constraint. Other values
- * are forbidden.
- */
-typedef void (*pm_policy_latency_changed_cb_t)(int32_t latency);
-
-/**
- * @brief Latency change subscription.
+ * @brief Latency request.
  *
  * @note All fields in this structure are meant for private usage.
  */
-struct pm_policy_latency_subscription {
+struct pm_policy_latency_request {
 	/** @cond INTERNAL_HIDDEN */
 	sys_snode_t node;
-	pm_policy_latency_changed_cb_t cb;
+	uint32_t value_us;
+	struct onoff_client cli;
+	void *internal;
+	uint32_t flags;
 	/** @endcond */
 };
 
 /**
- * @brief Latency request.
+ * @brief Callback to notify when maximum latency changes.
  *
- * @note All fields in this structure are meant for private usage.
+ * @param latency New maximum latency. Positive value represents latency in
+ * microseconds. SYS_FOREVER_US value lifts the latency constraint. Other values
+ * are forbidden.
  */
-struct pm_policy_latency_request {
-	/** @cond INTERNAL_HIDDEN */
-	sys_snode_t node;
-	uint32_t value_us;
-	/** @endcond */
-};
+typedef void (*pm_policy_latency_changed_cb_t)(struct pm_policy_latency_request *req,
+					       int32_t latency);
 
 /**
  * @brief Event.
@@ -275,63 +268,140 @@ static inline int32_t pm_policy_next_event_ticks(void)
  * The system will not enter any power state that would make the system to
  * exceed the given latency value.
  *
+ * If immediate control manager is provided request may trigger an action asynchronous action
+ * to reconfigure the system runtime to fullfil requested latency. @p req contains an
+ * asynchronous notification field that must be initialize prior to the call to get the
+ * notification.
+ *
  * @param req Latency request.
  * @param value_us Maximum allowed latency in microseconds.
+ *
+ * @retval 0 if request is applied.
+ * @retval 1 if request required immediate action that is not completed. Configured completion
+ * notification will inform about completion.
+ * @retval -EIO immediate action returned error.
+ */
+int pm_policy_latency_request_add(struct pm_policy_latency_request *req, uint32_t value_us);
+
+/**
+ * @brief Synchronously add a new latency requirement.
+ *
+ * If immediate control manager is not used then it is an equivalent of
+ * @ref pm_policy_latency_request_add. If immediate control manager is used then context
+ * blocks until request is completed. It can only be called from the thread context.
+ * Asynchronous notification field in the @p req is configured and used internally.
+ *
+ * @retval 0 if request required immediate action that is not completed. Configured completion
+ * notification will inform about completion.
+ * @retval -EIO immediate action returned error.
  */
-void pm_policy_latency_request_add(struct pm_policy_latency_request *req,
-				   uint32_t value_us);
+int pm_policy_latency_request_add_sync(struct pm_policy_latency_request *req, uint32_t value_us);
 
 /**
  * @brief Update a latency requirement.
  *
  * @param req Latency request.
  * @param value_us New maximum allowed latency in microseconds.
+ *
+ * @retval 0 if request is applied.
+ * @retval 1 if request required immediate action that is not completed. Configured completion
+ * notification will inform about completion.
+ * @retval -EIO immediate action returned error.
+ */
+int pm_policy_latency_request_update(struct pm_policy_latency_request *req, uint32_t value_us);
+
+/**
+ * @brief Synchronously update a latency requirement.
+ *
+ * If immediate control manager is not used then it is an equivalent of
+ * @ref pm_policy_latency_request_update. If immediate control manager is used then context
+ * blocks until request is completed. It can only be called from the thread context.
+ * Asynchronous notification field in the @p req is configured and used internally.
+ *
+ * @retval 0 if request required immediate action that is not completed. Configured completion
+ * notification will inform about completion.
+ * @retval -EIO immediate action returned error.
  */
-void pm_policy_latency_request_update(struct pm_policy_latency_request *req,
-				      uint32_t value_us);
+int pm_policy_latency_request_update_sync(struct pm_policy_latency_request *req, uint32_t value_us);
 
 /**
  * @brief Remove a latency requirement.
  *
  * @param req Latency request.
+ *
+ * @retval 0 if request removed successfully.
+ * @retval -EALREADY if request is not active and cannot be removed.
+ * @retval -EIO immediate action returned error.
+ */
+int pm_policy_latency_request_remove(struct pm_policy_latency_request *req);
+
+/** @brief Immediate action manager for single threshold.
+ *
+ * If there is only a single threshold that triggers an action then @ref onoff_manager
+ * can handle that. Structure must be persistent.
  */
-void pm_policy_latency_request_remove(struct pm_policy_latency_request *req);
+struct pm_policy_latency_immediate_binary {
+	/** Onoff manager. */
+	struct onoff_manager *mgr;
+	/** Latency threshold. Value below threshold trigger 'on' action. */
+	int32_t thr;
+};
+
+struct pm_policy_latency_immediate_ctrl {
+	/** Indication that onoff manager is used. In future gradual manager might
+	 * also be supported.
+	 */
+	bool onoff;
+	/** Pointer to the manager which controls immediate action. */
+	union {
+		struct pm_policy_latency_immediate_binary *bin_mgr;
+		void *mgr;
+	};
+};
 
 /**
  * @brief Subscribe to maximum latency changes.
  *
  * @param req Subscription request.
  * @param cb Callback function (NULL to disable).
  */
-void pm_policy_latency_changed_subscribe(struct pm_policy_latency_subscription *req,
-					 pm_policy_latency_changed_cb_t cb);
+int pm_policy_latency_immediate_ctrl_add(struct pm_policy_latency_immediate_ctrl *mgr);
 
 /**
  * @brief Unsubscribe to maximum latency changes.
  *
  * @param req Subscription request.
  */
-void pm_policy_latency_changed_unsubscribe(struct pm_policy_latency_subscription *req);
 #else
-static inline void pm_policy_latency_request_add(
+static inline int pm_policy_latency_request_add(
 	struct pm_policy_latency_request *req, uint32_t value_us)
 {
 	ARG_UNUSED(req);
 	ARG_UNUSED(value_us);
+	return 0;
 }
 
-static inline void pm_policy_latency_request_update(
+static inline int pm_policy_latency_request_update(
 	struct pm_policy_latency_request *req, uint32_t value_us)
 {
 	ARG_UNUSED(req);
 	ARG_UNUSED(value_us);
+	return 0;
 }
 
-static inline void pm_policy_latency_request_remove(
+static inline int pm_policy_latency_request_remove(
 	struct pm_policy_latency_request *req)
 {
 	ARG_UNUSED(req);
+	return 0;
 }
+
+static inline int pm_policy_latency_immediate_ctrl_add(struct pm_policy_latency_immediate_ctrl *mgr)
+{
+	ARG_UNUSED(mgr);
+	return 0;
+}
+
 #endif /* CONFIG_PM CONFIG_PM_POLICY_LATENCY_STANDALONE */
 
 /**

samples/subsys/pm/latency/sample.yaml

@@ -25,34 +25,25 @@ tests:
         - "<inf> app: Sleeping for 1.3 seconds, we should enter SUSPEND_TO_IDLE"
         - "<inf> soc_pm: Entering SUSPEND_TO_IDLE{0}"
         - "<inf> app: Opening test device"
-        - "<inf> dev_test: Adding latency constraint: 20ms"
-        - "<inf> app: Latency constraint changed: 20ms"
         - "<inf> app: Sleeping for 1.1 seconds, we should enter RUNTIME_IDLE"
         - "<inf> soc_pm: Entering RUNTIME_IDLE{0}"
         - "<inf> app: Sleeping for 1.2 seconds, we should enter RUNTIME_IDLE"
         - "<inf> soc_pm: Entering RUNTIME_IDLE{0}"
         - "<inf> app: Sleeping for 1.3 seconds, we should enter RUNTIME_IDLE"
         - "<inf> soc_pm: Entering RUNTIME_IDLE{0}"
         - "<inf> app: Updating latency constraint: 10ms"
-        - "<inf> app: Latency constraint changed: 10ms"
-        - "<inf> dev_test: Latency constraint changed: 10ms"
         - "<inf> app: Sleeping for 1.1 seconds, we should stay ACTIVE"
         - "<inf> app: Sleeping for 1.2 seconds, we should stay ACTIVE"
         - "<inf> app: Sleeping for 1.3 seconds, we should stay ACTIVE"
         - "<inf> app: Updating latency constraint: 30ms"
-        - "<inf> app: Latency constraint changed: 20ms"
-        - "<inf> dev_test: Latency constraint changed: 20ms"
         - "<inf> app: Closing test device"
         - "<inf> dev_test: Removing latency constraint"
-        - "<inf> app: Latency constraint changed: 30ms"
-        - "<inf> dev_test: Latency constraint changed: 30ms"
         - "<inf> app: Sleeping for 1.1 seconds, we should enter RUNTIME_IDLE"
         - "<inf> soc_pm: Entering RUNTIME_IDLE{0}"
         - "<inf> app: Sleeping for 1.2 seconds, we should enter SUSPEND_TO_IDLE"
         - "<inf> soc_pm: Entering SUSPEND_TO_IDLE{0}"
         - "<inf> app: Sleeping for 1.3 seconds, we should enter SUSPEND_TO_IDLE"
         - "<inf> soc_pm: Entering SUSPEND_TO_IDLE{0}"
         - "<inf> app: Removing latency constraint"
-        - "<inf> app: Latency constraint changed: none"
         - "<inf> app: Finished, we should now enter STANDBY"
         - "<inf> soc_pm: Entering STANDBY{0}"

samples/subsys/pm/latency/src/main.c

@@ -13,19 +13,8 @@
 
 LOG_MODULE_REGISTER(app, CONFIG_APP_LOG_LEVEL);
 
-static void on_latency_changed(int32_t latency)
-{
-	if (latency == SYS_FOREVER_US) {
-		LOG_INF("Latency constraint changed: none");
-	} else {
-		LOG_INF("Latency constraint changed: %" PRId32 "ms",
-			latency / USEC_PER_MSEC);
-	}
-}
-
 int main(void)
 {
-	struct pm_policy_latency_subscription subs;
 	struct pm_policy_latency_request req;
 	const struct device *dev;
 
@@ -35,8 +24,6 @@ int main(void)
 		return 0;
 	}
 
-	pm_policy_latency_changed_subscribe(&subs, on_latency_changed);
-
 	/* test without any latency constraint */
 	LOG_INF("Sleeping for 1.1 seconds, we should enter RUNTIME_IDLE");
 	k_msleep(1100);
@@ -101,8 +88,6 @@ int main(void)
 	LOG_INF("Removing latency constraints");
 	pm_policy_latency_request_remove(&req);
 
-	pm_policy_latency_changed_unsubscribe(&subs);
-
 	LOG_INF("Finished, we should now enter STANDBY");
 	return 0;
 }

samples/subsys/pm/latency/src/test.c

@@ -13,28 +13,15 @@
 LOG_MODULE_REGISTER(dev_test, CONFIG_APP_LOG_LEVEL);
 
 struct dev_test_data {
-	struct pm_policy_latency_subscription subs;
 	struct pm_policy_latency_request req;
 };
 
-static void on_latency_changed(int32_t latency)
-{
-	if (latency == SYS_FOREVER_US) {
-		LOG_INF("Latency constraint changed: none");
-	} else {
-		LOG_INF("Latency constraint changed: %" PRId32 "ms",
-			latency / USEC_PER_MSEC);
-	}
-}
-
 static void dev_test_open(const struct device *dev)
 {
 	struct dev_test_data *data = dev->data;
 
 	LOG_INF("Adding latency constraint: 20ms");
 	pm_policy_latency_request_add(&data->req, 20000);
-
-	pm_policy_latency_changed_subscribe(&data->subs, on_latency_changed);
 }
 
 static void dev_test_close(const struct device *dev)
@@ -43,8 +30,6 @@ static void dev_test_close(const struct device *dev)
 
 	LOG_INF("Removing latency constraint");
 	pm_policy_latency_request_remove(&data->req);
-
-	pm_policy_latency_changed_unsubscribe(&data->subs);
 }
 
 static const struct test_api dev_test_api = {

subsys/pm/Kconfig

@@ -53,6 +53,11 @@ config PM_NEED_ALL_DEVICES_IDLE
 	  When this option is enabled, check that no devices are busy before
 	  entering into system low power mode.
 
+config PM_POLICY_LATENCY_IMMEDIATE_BIN_ACTION
+	bool "Support latency change action"
+	select ONOFF
+	imply POLL
+
 endif # PM
 
 config PM_DEVICE