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 pm is locked.  */
49 	/** Indicates if the device is used as a power domain */
51 	/** Indicates if device runtime PM should be automatically enabled */
57 /** @brief Device power states. */
59 	/** Device is in active or regular state. */
62 	 * Device is suspended.
65 	 *     Device context may be lost.
68 	/** Device is being suspended. */
71 	 * Device is turned off (power removed).
74 	 *     Device context is lost.
79 /** @brief Device PM actions. */
100  * @brief Device PM action callback.
102  * @param dev Device instance.
109 typedef int (*pm_device_action_cb_t)(const struct device *dev,
113  * @brief Device PM action failed callback
115  * @param dev Device that failed the action.
120 typedef bool (*pm_device_action_failed_cb_t)(const struct device *dev,
124  * @brief Device PM info
128 	/** Pointer to the device */
129 	const struct device *dev;
134 	/** Device usage count */
141 	const struct device *domain;
143 	/* Device PM status flags. */
145 	/** Device power state */
147 	/** Device PM action callback */
172  * @param node_id Devicetree node for the initialized device (can be invalid).
192  * @param node_id Devicetree node for the initialized device (can be invalid).
193  * @param pm_action_cb Device PM control callback function.
205  * Get the name of device PM resources.
207  * @param dev_id Device id.
212  * @brief Define device PM slot.
214  * This macro defines a pointer to a device in the pm_device_slots region.
215  * When invoked for each device with PM, it will effectively result in a device
220  * @param dev_id Device id.
223 	static const STRUCT_SECTION_ITERABLE_ALTERNATE(pm_device_slots, device, \
228  * Define device PM resources for the given node identifier.
230  * @param node_id Node identifier (DT_INVALID_NODE if not a DT device).
231  * @param dev_id Device id.
241  * Get a reference to the device PM resources.
243  * @param dev_id Device id.
255  * Define device PM resources for the given device name.
259  * @param dev_id Device id.
268  * Define device PM resources for the given node identifier.
282  * Define device PM resources for the given instance.
297  * @brief Obtain a reference to the device PM resources for the given device.
299  * @param dev_id Device id.
301  * @return Reference to the device PM resources (NULL if device
308  * @brief Obtain a reference to the device PM resources for the given node.
312  * @return Reference to the device PM resources (NULL if device
319  * @brief Obtain a reference to the device PM resources for the given instance.
323  * @return Reference to the device PM resources (NULL if device
330  * @brief Get name of device PM state
337  * @brief Run a pm action on a device.
339  * This function calls the device PM control callback so that the device does
342  * @param dev Device instance.
343  * @param action Device pm action.
347  * @retval -EALREADY If device is already at the requested state.
348  * @retval -EBUSY If device is changing its state.
349  * @retval -ENOSYS If device does not support PM.
350  * @retval -EPERM If device has power state locked.
353 int pm_device_action_run(const struct device *dev,
357  * @brief Run a pm action on all children of a device.
359  * This function calls all child devices PM control callback so that the device
362  * @param dev Device instance.
363  * @param action Device pm action.
366 void pm_device_children_action_run(const struct device *dev,
372  * @brief Obtain the power state of a device.
374  * @param dev Device instance.
375  * @param state Pointer where device power state will be stored.
378  * @retval -ENOSYS If device does not implement power management.
380 int pm_device_state_get(const struct device *dev,
384  * @brief Initialize a device state to #PM_DEVICE_STATE_SUSPENDED.
386  * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. However
387  * in order to save power some drivers may choose to only initialize the device
388  * to the suspended state, or actively put the device into the suspended state.
390  * device is in #PM_DEVICE_STATE_SUSPENDED instead of the default.
392  * @param dev Device instance.
394 static inline void pm_device_init_suspended(const struct device *dev)  in pm_device_init_suspended()
402  * @brief Initialize a device state to #PM_DEVICE_STATE_OFF.
404  * By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
405  * general, this makes sense because the device initialization function will
406  * resume and configure a device, leaving it operational. However, when power
407  * domains are enabled, the device may be connected to a switchable power
409  * therefore be used to notify the PM subsystem that the device is in
412  * @param dev Device instance.
414 static inline void pm_device_init_off(const struct device *dev)  in pm_device_init_off()
422  * @brief Mark a device as busy.
425  * low-power states. This can be useful if, for example, the device is in the
428  * @param dev Device instance.
432 void pm_device_busy_set(const struct device *dev);
435  * @brief Clear a device busy status.
437  * @param dev Device instance.
441 void pm_device_busy_clear(const struct device *dev);
444  * @brief Check if any device is busy.
446  * @retval false If no device is busy
452  * @brief Check if a device is busy.
454  * @param dev Device instance.
456  * @retval false If the device is not busy
457  * @retval true If the device is busy
459 bool pm_device_is_busy(const struct device *dev);
462  * @brief Enable or disable a device as a wake up source.
464  * A device marked as a wake up source will not be suspended when the system
468  * @param dev Device instance.
474 bool pm_device_wakeup_enable(const struct device *dev, bool enable);
477  * @brief Check if a device is enabled as a wake up source.
479  * @param dev Device instance.
484 bool pm_device_wakeup_is_enabled(const struct device *dev);
487  * @brief Check if a device is wake up capable
489  * @param dev Device instance.
491  * @retval true If the device is wake up capable.
492  * @retval false If the device is not wake up capable.
494 bool pm_device_wakeup_is_capable(const struct device *dev);
497  * @brief Lock current device state.
499  * This function locks the current device power state. Once
500  * locked the device power state will not be changed by
501  * system power management or device runtime power
504  * @note The given device should not have device runtime enabled.
508  * @param dev Device instance.
510 void pm_device_state_lock(const struct device *dev);
513  * @brief Unlock the current device state.
515  * Unlocks a previously locked device pm.
519  * @param dev Device instance.
521 void pm_device_state_unlock(const struct device *dev);
524  * @brief Check if the device pm is locked.
526  * @param dev Device instance.
528  * @retval true If device is locked.
529  * @retval false If device is not locked.
531 bool pm_device_state_is_locked(const struct device *dev);
534  * @brief Check if the device is on a switchable power domain.
536  * @param dev Device instance.
538  * @retval true If device is on a switchable power domain.
539  * @retval false If device is not on a switchable power domain.
541 bool pm_device_on_power_domain(const struct device *dev);
544  * @brief Add a device to a power domain.
546  * This function adds a device to a given power domain.
548  * @param dev Device to be added to the power domain.
552  * @retval -EALREADY If device is already part of the power domain.
554  * @retval -ENOSPC If there is no space available in the power domain to add the device.
556 int pm_device_power_domain_add(const struct device *dev,
557 			       const struct device *domain);
560  * @brief Remove a device from a power domain.
562  * This function removes a device from a given power domain.
564  * @param dev Device to be removed from the power domain.
569  * @retval -ENOENT If device is not in the given domain.
571 int pm_device_power_domain_remove(const struct device *dev,
572 				  const struct device *domain);
575  * @brief Check if the device is currently powered.
577  * @param dev Device instance.
579  * @retval true If device is currently powered
580  * @retval false If device is not currently powered
582 bool pm_device_is_powered(const struct device *dev);
584 static inline int pm_device_state_get(const struct device *dev,  in pm_device_state_get()
594 static inline void pm_device_init_suspended(const struct device *dev)  in pm_device_init_suspended()
598 static inline void pm_device_init_off(const struct device *dev)  in pm_device_init_off()
602 static inline void pm_device_busy_set(const struct device *dev)  in pm_device_busy_set()
606 static inline void pm_device_busy_clear(const struct device *dev)  in pm_device_busy_clear()
611 static inline bool pm_device_is_busy(const struct device *dev)  in pm_device_is_busy()
616 static inline bool pm_device_wakeup_enable(const struct device *dev,  in pm_device_wakeup_enable()
623 static inline bool pm_device_wakeup_is_enabled(const struct device *dev)  in pm_device_wakeup_is_enabled()
628 static inline bool pm_device_wakeup_is_capable(const struct device *dev)  in pm_device_wakeup_is_capable()
633 static inline void pm_device_state_lock(const struct device *dev)  in pm_device_state_lock()
637 static inline void pm_device_state_unlock(const struct device *dev)  in pm_device_state_unlock()
641 static inline bool pm_device_state_is_locked(const struct device *dev)  in pm_device_state_is_locked()
646 static inline bool pm_device_on_power_domain(const struct device *dev)  in pm_device_on_power_domain()
652 static inline int pm_device_power_domain_add(const struct device *dev,  in pm_device_power_domain_add()
653 					     const struct device *domain)  in pm_device_power_domain_add()
658 static inline int pm_device_power_domain_remove(const struct device *dev,  in pm_device_power_domain_remove()
659 						const struct device *domain)  in pm_device_power_domain_remove()
664 static inline bool pm_device_is_powered(const struct device *dev)  in pm_device_is_powered()