pm: device: introduce pm_device_driver_deinit()

Introduce pm_device_driver_deinit() which is required to fully
support device_deinit(). This function shall be called by drivers
when device_deinit() is called.

If PM_DEVICE is enabled, it will
simply check whether the device is either SUSPENDED or OFF, this
will prevent device_deinit() on a device which is currently in
use, and ensure the device is in the correct state if device_init()
is called later.

If PM_DEVICE is not enabled, it will invoke the SUSPEND action which
mirrors the pm_device_driver_init() behavior. Note that TURN_OFF
action is not called since the device is deinitialized after this
call.

Signed-off-by: Bjarki Arge Andreasen <bjarki.andreasen@nordicsemi.no>

Author: bjarki-andreasen

include/zephyr/pm/device.h

@@ -638,6 +638,23 @@ bool pm_device_is_powered(const struct device *dev);
  */
 int pm_device_driver_init(const struct device *dev, pm_device_action_cb_t action_cb);
 
+/**
+ * @brief Deinit a device driver
+ *
+ * @details Ensures device is either SUSPENDED or OFF, and will revert the actions of
+ * pm_device_driver_init() if this is the case. Must be called at the beginning of a
+ * driver's deinit function.
+ *
+ * @note If CONFIG_PM_DEVICE=n, PM_DEVICE_ACTION_SUSPEND will be invoked
+ * unconditionally.
+ *
+ * @param dev Device instance.
+ * @param action_cb Device PM control callback function.
+ * @retval 0 if success.
+ * @retval -EBUSY Device is not SUSPENDED nor OFF
+ * @retval -errno code if failure.
+ */
+int pm_device_driver_deinit(const struct device *dev, pm_device_action_cb_t action_cb);
 #else
 static inline int pm_device_state_get(const struct device *dev,
 				      enum pm_device_state *state)
@@ -734,6 +751,11 @@ static inline int pm_device_driver_init(const struct device *dev, pm_device_acti
 	return 0;
 }
 
+static inline int pm_device_driver_deinit(const struct device *dev, pm_device_action_cb_t action_cb)
+{
+	return action_cb(dev, PM_DEVICE_ACTION_SUSPEND);
+}
+
 #endif /* CONFIG_PM_DEVICE */
 
 /** @} */

subsys/pm/device.c

@@ -401,3 +401,14 @@ int pm_device_driver_init(const struct device *dev,
 	/* Return the PM_DEVICE_ACTION_RESUME result */
 	return rc;
 }
+
+int pm_device_driver_deinit(const struct device *dev,
+			    pm_device_action_cb_t action_cb)
+{
+	struct pm_device_base *pm = dev->pm_base;
+
+	return pm->state == PM_DEVICE_STATE_SUSPENDED ||
+	       pm->state == PM_DEVICE_STATE_OFF ?
+	       0 :
+	       -EBUSY;
+}