10 #include <zephyr/device.h>
20  * @brief Device Power Management API
21  * @defgroup subsys_pm_device Device
28 struct device;
30 /** @brief Device PM flags. */
32 	/** Indicate if the device is busy or not. */
34 	/** Indicate if the device failed to power up. */
36 	/** Indicate if the device has claimed a power domain */
39 	 * Indicates whether or not the device is capable of waking the system
43 	/** Indicates if the device is being used as wakeup source. */
45 	/** Indicates if device runtime is enabled  */
47 	/** Indicates if the device is used as a power domain */
49 	/** Indicates if device runtime PM should be automatically enabled */
51 	/** Indicates that device runtime PM supports suspending and resuming from any context. */
57 /** @brief Flag indicating that runtime PM API for the device can be called from any context.
59  * If @ref PM_DEVICE_ISR_SAFE flag is used for device definition, it indicates that PM actions
62  * less resources (~80 byte less RAM) and allows to use device runtime PM from any context
67 /** @brief Device power states. */
69 	/** Device is in active or regular state. */
72 	 * Device is suspended.
75 	 *     Device context may be lost.
78 	/** Device is being suspended. */
81 	 * Device is turned off (power removed).
84 	 *     Device context is lost.
89 /** @brief Device PM actions. */
110  * @brief Device PM action callback.
112  * @param dev Device instance.
119 typedef int (*pm_device_action_cb_t)(const struct device *dev,
123  * @brief Device PM action failed callback
125  * @param dev Device that failed the action.
130 typedef bool (*pm_device_action_failed_cb_t)(const struct device *dev,
134  * @brief Device PM info
140 	/** Device PM status flags. */
142 	/** Device power state */
144 	/** Device PM action callback */
147 	/** Device usage count */
152 	const struct device *domain;
157  * @brief Runtime PM info for device with generic PM.
167 	/** Pointer to the device */
168 	const struct device *dev;
179  * @brief Runtime PM info for device with synchronous PM.
219  * @param node_id Devicetree node for the initialized device (can be invalid).
239  * @param node_id Devicetree node for the initialized device (can be invalid).
240  * @param pm_action_cb Device PM control callback function.
258  * @param node_id Devicetree node for the initialized device (can be invalid).
259  * @param pm_action_cb Device PM control callback function.
269  * Get the name of device PM resources.
271  * @param dev_id Device id.
277  * @brief Define device PM slot.
279  * This macro defines a pointer to a device in the pm_device_slots region.
280  * When invoked for each device with PM, it will effectively result in a device
285  * @param dev_id Device id.
288 	static STRUCT_SECTION_ITERABLE_ALTERNATE(pm_device_slots, device, \
296  * Define device PM resources for the given node identifier.
298  * @param node_id Node identifier (DT_INVALID_NODE if not a DT device).
299  * @param dev_id Device id.
310  * Get a reference to the device PM resources.
312  * @param dev_id Device id.
324  * Define device PM resources for the given device name.
328  * @param dev_id Device id.
339  * Define device PM resources for the given node identifier.
345  * @param ... Optional flag to indicate that device is isr_ok. Use @ref PM_DEVICE_ISR_SAFE or 0.
354  * Define device PM resources for the given instance.
360  * @param ... Optional flag to indicate that device is isr_ok. Use @ref PM_DEVICE_ISR_SAFE or 0.
371  * @brief Obtain a reference to the device PM resources for the given device.
373  * @param dev_id Device id.
375  * @return Reference to the device PM resources (NULL if device
382  * @brief Obtain a reference to the device PM resources for the given node.
386  * @return Reference to the device PM resources (NULL if device
393  * @brief Obtain a reference to the device PM resources for the given instance.
397  * @return Reference to the device PM resources (NULL if device
404  * @brief Get name of device PM state
411  * @brief Run a pm action on a device.
413  * This function calls the device PM control callback so that the device does
416  * @param dev Device instance.
417  * @param action Device pm action.
421  * @retval -EALREADY If device is already at the requested state.
422  * @retval -EBUSY If device is changing its state.
423  * @retval -ENOSYS If device does not support PM.
424  * @retval -EPERM If device has power state locked.
427 int pm_device_action_run(const struct device *dev,
431  * @brief Run a pm action on all children of a device.
433  * This function calls all child devices PM control callback so that the device
436  * @param dev Device instance.
437  * @param action Device pm action.
440 void pm_device_children_action_run(const struct device *dev,
446  * @brief Obtain the power state of a device.
448  * @param dev Device instance.
449  * @param state Pointer where device power state will be stored.
452  * @retval -ENOSYS If device does not implement power management.
454 int pm_device_state_get(const struct device *dev,
458  * @brief Initialize a device state to #PM_DEVICE_STATE_SUSPENDED.
460  * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. However
461  * in order to save power some drivers may choose to only initialize the device
462  * to the suspended state, or actively put the device into the suspended state.
464  * device is in #PM_DEVICE_STATE_SUSPENDED instead of the default.
466  * @param dev Device instance.
468 static inline void pm_device_init_suspended(const struct device *dev)  in pm_device_init_suspended()
476  * @brief Initialize a device state to #PM_DEVICE_STATE_OFF.
478  * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
479  * general, this makes sense because the device initialization function will
480  * resume and configure a device, leaving it operational. However, when power
481  * domains are enabled, the device may be connected to a switchable power
483  * therefore be used to notify the PM subsystem that the device is in
486  * @param dev Device instance.
488 static inline void pm_device_init_off(const struct device *dev)  in pm_device_init_off()
496  * @brief Mark a device as busy.
499  * low-power states. This can be useful if, for example, the device is in the
502  * @param dev Device instance.
506 void pm_device_busy_set(const struct device *dev);
509  * @brief Clear a device busy status.
511  * @param dev Device instance.
515 void pm_device_busy_clear(const struct device *dev);
518  * @brief Check if any device is busy.
520  * @retval false If no device is busy
526  * @brief Check if a device is busy.
528  * @param dev Device instance.
530  * @retval false If the device is not busy
531  * @retval true If the device is busy
533 bool pm_device_is_busy(const struct device *dev);
536  * @brief Enable or disable a device as a wake up source.
538  * A device marked as a wake up source will not be suspended when the system
542  * @param dev Device instance.
548 bool pm_device_wakeup_enable(const struct device *dev, bool enable);
551  * @brief Check if a device is enabled as a wake up source.
553  * @param dev Device instance.
558 bool pm_device_wakeup_is_enabled(const struct device *dev);
561  * @brief Check if a device is wake up capable
563  * @param dev Device instance.
565  * @retval true If the device is wake up capable.
566  * @retval false If the device is not wake up capable.
568 bool pm_device_wakeup_is_capable(const struct device *dev);
571  * @brief Check if the device is on a switchable power domain.
573  * @param dev Device instance.
575  * @retval true If device is on a switchable power domain.
576  * @retval false If device is not on a switchable power domain.
578 bool pm_device_on_power_domain(const struct device *dev);
581  * @brief Add a device to a power domain.
583  * This function adds a device to a given power domain.
585  * @param dev Device to be added to the power domain.
589  * @retval -EALREADY If device is already part of the power domain.
591  * @retval -ENOSPC If there is no space available in the power domain to add the device.
593 int pm_device_power_domain_add(const struct device *dev,
594 			       const struct device *domain);
597  * @brief Remove a device from a power domain.
599  * This function removes a device from a given power domain.
601  * @param dev Device to be removed from the power domain.
606  * @retval -ENOENT If device is not in the given domain.
608 int pm_device_power_domain_remove(const struct device *dev,
609 				  const struct device *domain);
612  * @brief Check if the device is currently powered.
614  * @param dev Device instance.
616  * @retval true If device is currently powered, or is assumed to be powered
618  * @retval false If device is not currently powered
620 bool pm_device_is_powered(const struct device *dev);
623  * @brief Setup a device driver into the lowest valid power mode
626  * init function to automatically setup the device into the lowest power
627  * mode. It assumes that the device has been configured as if it is in
628  * @ref PM_DEVICE_STATE_OFF, or @ref PM_DEVICE_STATE_SUSPENDED if device can
631  * @param dev Device instance.
632  * @param action_cb Device PM control callback function.
636 int pm_device_driver_init(const struct device *dev, pm_device_action_cb_t action_cb);
639 static inline int pm_device_state_get(const struct device *dev,  in pm_device_state_get()
649 static inline void pm_device_init_suspended(const struct device *dev)  in pm_device_init_suspended()
653 static inline void pm_device_init_off(const struct device *dev)  in pm_device_init_off()
657 static inline void pm_device_busy_set(const struct device *dev)  in pm_device_busy_set()
661 static inline void pm_device_busy_clear(const struct device *dev)  in pm_device_busy_clear()
666 static inline bool pm_device_is_busy(const struct device *dev)  in pm_device_is_busy()
671 static inline bool pm_device_wakeup_enable(const struct device *dev,  in pm_device_wakeup_enable()
678 static inline bool pm_device_wakeup_is_enabled(const struct device *dev)  in pm_device_wakeup_is_enabled()
683 static inline bool pm_device_wakeup_is_capable(const struct device *dev)  in pm_device_wakeup_is_capable()
688 static inline bool pm_device_on_power_domain(const struct device *dev)  in pm_device_on_power_domain()
694 static inline int pm_device_power_domain_add(const struct device *dev,  in pm_device_power_domain_add()
695 					     const struct device *domain)  in pm_device_power_domain_add()
702 static inline int pm_device_power_domain_remove(const struct device *dev,  in pm_device_power_domain_remove()
703 						const struct device *domain)  in pm_device_power_domain_remove()
710 static inline bool pm_device_is_powered(const struct device *dev)  in pm_device_is_powered()
716 static inline int pm_device_driver_init(const struct device *dev, pm_device_action_cb_t action_cb)  in pm_device_driver_init()