pm: device: move pm_device_runtime_init_* funcs

Move the `pm_device_runtime_init_*` functions from <pm/device_runtime.h>
to <pm/device.h>. The initial device state should be settable
independently of whether `CONFIG_PM_DEVICE_RUNTIME` is enabled.

This also resolves a compilation error when attempting to use these
functions without also including <pm/device.h>.

Function documentation is also updated to be more general than only
referencing runtime PM, as this also applies to system PM and manually
run actions.

Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>

doc/guides/pm/device_runtime.rst

@@ -145,7 +145,7 @@ To enable device runtime power management on a device, the driver needs to call
 function will suspend the device if its state is
 :c:enumerator:`PM_DEVICE_STATE_ACTIVE`. In case the device is physically
 suspended, the init function should call
-:c:func:`pm_device_runtime_init_suspended` before calling
+:c:func:`pm_device_init_suspended` before calling
 :c:func:`pm_device_runtime_enable`.
 
 .. code-block:: c
@@ -157,7 +157,7 @@ suspended, the init function should call
         ...
 
         /* OPTIONAL: mark device as suspended if it is physically suspended */
-        pm_device_runtime_init_suspended(dev);
+        pm_device_init_suspended(dev);
 
         /* enable device runtime power management */
         ret = pm_device_runtime_enable(dev);

drivers/gpio/gpio_stm32.c

@@ -626,7 +626,7 @@ static int gpio_stm32_init(const struct device *dev)
 		return ret;
 	}
 
-	pm_device_runtime_init_suspended(dev);
+	pm_device_init_suspended(dev);
 	(void)pm_device_runtime_enable(dev);
 
 	return 0;

drivers/power_domain/power_domain_gpio.c

@@ -83,10 +83,10 @@ static int pd_gpio_init(const struct device *dev)
 
 	if (pm_device_on_power_domain(dev)) {
 		/* Device is unpowered */
-		pm_device_runtime_init_off(dev);
+		pm_device_init_off(dev);
 		rc = gpio_pin_configure_dt(&cfg->enable, GPIO_DISCONNECTED);
 	} else {
-		pm_device_runtime_init_suspended(dev);
+		pm_device_init_suspended(dev);
 		rc = gpio_pin_configure_dt(&cfg->enable, GPIO_OUTPUT_INACTIVE);
 	}
 

include/pm/device.h

@@ -361,6 +361,44 @@ void pm_device_children_action_run(const struct device *dev,
 		pm_device_action_failed_cb_t failure_cb);
 
 #if defined(CONFIG_PM_DEVICE) || defined(__DOXYGEN__)
+/**
+ * @brief Initialize a device state to #PM_DEVICE_STATE_SUSPENDED.
+ *
+ * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. However
+ * in order to save power some drivers may choose to only initialize the device
+ * to the suspended state, or actively put the device into the suspended state.
+ * This function can therefore be used to notify the PM subsystem that the
+ * device is in #PM_DEVICE_STATE_SUSPENDED instead of the default.
+ *
+ * @param dev Device instance.
+ */
+static inline void pm_device_init_suspended(const struct device *dev)
+{
+	struct pm_device *pm = dev->pm;
+
+	pm->state = PM_DEVICE_STATE_SUSPENDED;
+}
+
+/**
+ * @brief Initialize a device state to #PM_DEVICE_STATE_OFF.
+ *
+ * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
+ * general, this makes sense because the device initialization function will
+ * resume and configure a device, leaving it operational. However, when power
+ * domains are enabled, the device may be connected to a switchable power
+ * source, in which case it won't be powered at boot. This function can
+ * therefore be used to notify the PM subsystem that the device is in
+ * #PM_DEVICE_STATE_OFF instead of the default.
+ *
+ * @param dev Device instance.
+ */
+static inline void pm_device_init_off(const struct device *dev)
+{
+	struct pm_device *pm = dev->pm;
+
+	pm->state = PM_DEVICE_STATE_OFF;
+}
+
 /**
  * @brief Mark a device as busy.
  *
@@ -484,6 +522,14 @@ bool pm_device_state_is_locked(const struct device *dev);
 bool pm_device_on_power_domain(const struct device *dev);
 
 #else
+static inline void pm_device_init_suspended(const struct device *dev)
+{
+	ARG_UNUSED(dev);
+}
+static inline void pm_device_init_off(const struct device *dev)
+{
+	ARG_UNUSED(dev);
+}
 static inline void pm_device_busy_set(const struct device *dev)
 {
 	ARG_UNUSED(dev);

include/pm/device_runtime.h

@@ -37,7 +37,7 @@ extern "C" {
  * @retval -ENOSYS If the functionality is not available.
  * @retval -errno Other negative errno, result of suspending the device.
  *
- * @see pm_device_runtime_init_suspended()
+ * @see pm_device_init_suspended()
  */
 int pm_device_runtime_enable(const struct device *dev);
 
@@ -137,43 +137,6 @@ int pm_device_runtime_put_async(const struct device *dev);
  */
 bool pm_device_runtime_is_enabled(const struct device *dev);
 
-/**
- * @brief Initialize a device state to #PM_DEVICE_STATE_SUSPENDED.
- *
- * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
- * general, this makes sense because the device initialization function will
- * resume and configure a device, leaving it operational. However, when device
- * runtime PM is enabled, the device may not be resumed and the init function
- * will just enable device runtime PM. If that is the case, this function can be
- * used to set the initial device state to #PM_DEVICE_STATE_SUSPENDED.
- *
- * @param dev Device instance.
- */
-static inline void pm_device_runtime_init_suspended(const struct device *dev)
-{
-	struct pm_device *pm = dev->pm;
-
-	pm->state = PM_DEVICE_STATE_SUSPENDED;
-}
-
-/**
- * @brief Initialize a device state to #PM_DEVICE_STATE_OFF.
- *
- * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
- * general, this makes sense because the device initialization function will
- * resume and configure a device, leaving it operational. However, when device
- * runtime PM is enabled, the device may be connected to a power domain, at
- * which case it won't be powered at boot.
- *
- * @param dev Device instance.
- */
-static inline void pm_device_runtime_init_off(const struct device *dev)
-{
-	struct pm_device *pm = dev->pm;
-
-	pm->state = PM_DEVICE_STATE_OFF;
-}
-
 #else
 static inline int pm_device_runtime_enable(const struct device *dev) { return -ENOSYS; }
 static inline int pm_device_runtime_disable(const struct device *dev) { return -ENOSYS; }
@@ -181,8 +144,6 @@ static inline int pm_device_runtime_get(const struct device *dev) { return 0; }
 static inline int pm_device_runtime_put(const struct device *dev) { return 0; }
 static inline int pm_device_runtime_put_async(const struct device *dev) { return 0; }
 static inline bool pm_device_runtime_is_enabled(const struct device *dev) { return false; }
-static inline void pm_device_runtime_init_suspended(const struct device *dev) { }
-static inline void pm_device_runtime_init_off(const struct device *dev) { }
 #endif
 
 /** @} */

tests/subsys/pm/power_domain/src/main.c

@@ -123,9 +123,9 @@ static void test_power_domain_device_runtime(void)
 	deva = DEVICE_DT_GET(TEST_DEVA);
 	devb = DEVICE_DT_GET(TEST_DEVB);
 
-	pm_device_runtime_init_suspended(domain);
+	pm_device_init_suspended(domain);
-	pm_device_runtime_init_suspended(deva);
+	pm_device_init_suspended(deva);
-	pm_device_runtime_init_suspended(devb);
+	pm_device_init_suspended(devb);
 
 	pm_device_runtime_enable(domain);
 	pm_device_runtime_enable(deva);