[nrf fromtree] pm: Add constraint lists and APIs

Some pieces of the system may have custom types of constraints that they
define based on different effects and reasons than just the standard
"zephyr,disabling-states". To avoid every single one of these component
reinventing the wheel, make some common APIs to handle these type of
custom constraint lists.

Signed-off-by: Declan Snyder <[email protected]>
(cherry picked from commit a4225b1)

Author: Declan Snyder

include/zephyr/pm/policy.h

@@ -125,6 +125,36 @@ void pm_policy_state_lock_get(enum pm_state state, uint8_t substate_id);
  */
 void pm_policy_state_lock_put(enum pm_state state, uint8_t substate_id);
 
+/**
+ * @brief Apply power state constraints by locking the specified states.
+ *
+ * This function locks all power states specified in the union of all constraints
+ * in the provided constraint list. Each constraint in the set contributes to
+ * determining which power states should be locked (not allowed), by increasing
+ * a reference count just as if pm_policy_state_lock_get was called on each constraints'
+ * states individually.
+ *
+ * @param constraints Pointer to the power state constraints set to apply.
+ *
+ * @see pm_policy_state_constraints_put()
+ */
+void pm_policy_state_constraints_get(struct pm_state_constraints *constraints);
+
+/**
+ * @brief Remove power state constraints by unlocking the specified states.
+ *
+ * This function unlocks all power states that were previously locked by a
+ * corresponding call to pm_policy_state_constraints_get() with the same
+ * constraint set. The function decreases the lock counter for each affected
+ * power state specified in the union of all constraints in the list, just as
+ * if pm_policy_state_put was called on all the constraints' states individually.
+ *
+ * @param constraints Pointer to the power state constraints set to remove.
+ *
+ * @see pm_policy_state_constraints_get()
+ */
+void pm_policy_state_constraints_put(struct pm_state_constraints *constraints);
+
 /**
  * @brief Check if a power state lock is active (not allowed).
  *

include/zephyr/pm/state.h

@@ -168,7 +168,8 @@ struct pm_state_info {
 };
 
 /**
- * Power state information needed to lock a power state.
+ * Information needed to be able to reference a power state as a constraint
+ * on some device or system functions.
  */
 struct pm_state_constraint {
 	 /**
@@ -185,6 +186,16 @@ struct pm_state_constraint {
 	uint8_t substate_id;
 };
 
+/**
+ * Collection of multiple power state constraints.
+ */
+struct pm_state_constraints {
+	/** Array of power state constraints */
+	struct pm_state_constraint *list;
+	/** Number of constraints in the list */
+	size_t count;
+};
+
 /** @cond INTERNAL_HIDDEN */
 
 /**
@@ -359,6 +370,54 @@ struct pm_state_constraint {
 			Z_PM_STATE_FROM_DT_CPU, (), node_id)		       \
 	}
 
+/**
+ * @brief initialize a device pm constraint with information from devicetree.
+ *
+ * @param node_id Node identifier.
+ */
+#define PM_STATE_CONSTRAINT_INIT(node_id)                                     \
+	{                                                                     \
+		.state = PM_STATE_DT_INIT(node_id),                           \
+		.substate_id = DT_PROP_OR(node_id, substate_id, 0),           \
+	}
+
+#define Z_PM_STATE_CONSTRAINT_REF(node_id, phandle, idx)                        \
+	PM_STATE_CONSTRAINT_INIT(DT_PHANDLE_BY_IDX(node_id, phandle, idx))
+
+#define Z_PM_STATE_CONSTRAINTS_LIST_NAME(node_id, phandles)                   \
+	_CONCAT_4(node_id, _, phandles, _constraints)
+
+/**
+ * @brief Define a list of power state constraints from devicetree.
+ *
+ * This macro creates an array of pm_state_constraint structures initialized
+ * with power state information from the specified devicetree property.
+ *
+ * @param node_id Devicetree node identifier.
+ * @param prop Property name containing the list of power state phandles.
+ */
+#define PM_STATE_CONSTRAINTS_LIST_DEFINE(node_id, prop)                                    \
+	struct pm_state_constraint Z_PM_STATE_CONSTRAINTS_LIST_NAME(node_id, prop)[] =     \
+	{                                                                                  \
+		DT_FOREACH_PROP_ELEM_SEP(node_id, prop, Z_PM_STATE_CONSTRAINT_REF, (,))    \
+	}
+
+/**
+ * @brief Get power state constraints structure from devicetree.
+ *
+ * This macro creates a structure containing a pointer to the constraints list
+ * and the count of constraints, suitable for initializing a pm_state_constraints
+ * structure. Must be used after the PM_STATE_CONSTRAINTS_LIST_DEFINE call for the same
+ * @param prop to refer to the array of constraints.
+ *
+ * @param node_id Devicetree node identifier.
+ * @param prop Property name containing the list of power state phandles.
+ */
+#define PM_STATE_CONSTRAINTS_GET(node_id, prop)                                            \
+	{                                                                                  \
+		.list = Z_PM_STATE_CONSTRAINTS_LIST_NAME(node_id, prop),                   \
+		.count = DT_PROP_LEN(node_id, prop),                                       \
+	}
 
 #if defined(CONFIG_PM) || defined(__DOXYGEN__)
 /**
@@ -403,6 +462,18 @@ const char *pm_state_to_str(enum pm_state state);
  * @return 0 on success, -EINVAL if the string is invalid or NULL.
  */
 int pm_state_from_str(const char *name, enum pm_state *out);
+
+/**
+ * @brief Check if a power management constraint matches any in a set of constraints.
+ *
+ * @param constraints Pointer to the power state constraints structure.
+ * @param match The constraint to match against.
+ *
+ * @return true if the constraint matches, false otherwise.
+ */
+bool pm_state_in_constraints(const struct pm_state_constraints *constraints,
+			     const struct pm_state_constraint match);
+
 /**
  * @}
  */
@@ -428,6 +499,14 @@ static inline const struct pm_state_info *pm_state_get(uint8_t cpu,
 	return NULL;
 }
 
+static inline bool pm_state_in_constraints(struct pm_state_constraints *constraints,
+					   struct pm_state_constraint match)
+{
+	ARG_UNUSED(constraints);
+	ARG_UNUSED(match);
+
+	return false;
+}
 #endif /* CONFIG_PM */
 
 #ifdef __cplusplus

subsys/pm/policy/policy_device_lock.c

@@ -24,16 +24,6 @@ struct pm_state_device_constraint {
  */
 #define PM_CONSTRAINTS_NAME(node_id) _CONCAT(__devicepmconstraints_, node_id)
 
-/**
- * @brief initialize a device pm constraint with information from devicetree.
- *
- * @param node_id Node identifier.
- */
-#define PM_STATE_CONSTRAINT_INIT(node_id)                                     \
-	{                                                                     \
-		.state = PM_STATE_DT_INIT(node_id),                           \
-		.substate_id = DT_PROP_OR(node_id, substate_id, 0),           \
-	}
 
 /**
  * @brief Helper macro to define a device pm constraints.

subsys/pm/policy/policy_state_lock.c

@@ -65,6 +65,14 @@ void pm_policy_state_lock_get(enum pm_state state, uint8_t substate_id)
 #endif
 }
 
+void pm_policy_state_constraints_get(struct pm_state_constraints *constraints)
+{
+	for (int i = 0; i < constraints->count; i++) {
+		pm_policy_state_lock_get(constraints->list[i].state,
+					 constraints->list[i].substate_id);
+	}
+}
+
 void pm_policy_state_lock_put(enum pm_state state, uint8_t substate_id)
 {
 #if DT_HAS_COMPAT_STATUS_OKAY(zephyr_power_state)
@@ -84,6 +92,14 @@ void pm_policy_state_lock_put(enum pm_state state, uint8_t substate_id)
 #endif
 }
 
+void pm_policy_state_constraints_put(struct pm_state_constraints *constraints)
+{
+	for (int i = 0; i < constraints->count; i++) {
+		pm_policy_state_lock_put(constraints->list[i].state,
+					 constraints->list[i].substate_id);
+	}
+}
+
 bool pm_policy_state_lock_is_active(enum pm_state state, uint8_t substate_id)
 {
 #if DT_HAS_COMPAT_STATUS_OKAY(zephyr_power_state)

subsys/pm/state.c

@@ -152,3 +152,20 @@ int pm_state_from_str(const char *name, enum pm_state *out)
 
 	return 0;
 }
+
+bool pm_state_in_constraints(const struct pm_state_constraints *constraints,
+			     const struct pm_state_constraint match)
+{
+	struct pm_state_constraint *constraints_list = constraints->list;
+	size_t num_constraints = constraints->count;
+	bool match_found = false;
+
+	for (int i = 0; i < num_constraints; i++) {
+		enum pm_state state = constraints_list[i].state;
+		uint8_t substate = constraints_list[i].substate_id;
+
+		match_found |= ((state == match.state) && (substate == match.substate_id));
+	}
+
+	return match_found;
+}