Lines Matching full:device
1 .. _pm-device-runtime:
3 Device Runtime Power Management
9 The device runtime power management (PM) framework is an active power management
12 enabled by setting :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME`. In this model the device
13 driver is responsible to indicate when it needs the device and when it does not.
14 This information is used to determine when to suspend or resume a device based
17 When device runtime power management is enabled on a device, its state will be
19 not used. On the first device request, it will be resumed and so put into the
20 :c:enumerator:`PM_DEVICE_STATE_ACTIVE` state. The device will remain in this
21 state until it is no longer used. At this point, the device will be suspended
22 until the next device request. If the suspension is performed synchronously the
23 device will be immediately put into the
29 For devices on a power domain (via the devicetree 'power-domains' property), device runtime
32 calls on the child device.
34 For the previous to automatically control the power domain state, device runtime PM must be enabled
35 on the power domain device (either through the ``zephyr,pm-device-runtime-auto`` devicetree property
39 :caption: Device states and transitions
58 The device runtime power management framework has been designed to minimize
59 devices power consumption with minimal application work. Device drivers are
60 responsible for indicating when they need the device to be operational and
62 device. An application can, however, decide when to disable or enable runtime
63 power management for a device. This can be useful, for example, if an
64 application wants a particular device to be always active.
69 When runtime PM is enabled on a device it will no longer be resumed or suspended
70 during system power transitions. Instead, the device is fully responsible to
71 indicate when it needs a device and when it does not. The device runtime PM API
72 uses reference counting to keep track of device's usage. This allows the API to
73 determine when a device needs to be resumed or suspended. The API uses the *get*
74 and *put* terminology to indicate when a device is needed or not, respectively.
75 This mechanism plays a key role when we account for device dependencies. For
76 example, if a bus device is used by multiple sensors, we can keep the bus active
81 As of today, the device runtime power management API does not manage device
82 dependencies. This effectively means that, if a device depends on other
83 devices to operate (e.g. a sensor may depend on a bus device), the bus will
90 The :c:func:`pm_device_runtime_get` function can be used by a device driver to
91 indicate it *needs* the device to be active or operational. This function will
92 increase device usage count and resume the device if necessary. Similarly, the
93 :c:func:`pm_device_runtime_put` function can be used to indicate that the device
94 is no longer needed. This function will decrease the device usage count and
95 suspend the device if necessary. It is worth to note that in both cases, the
97 illustrates how a device can use this API and the expected sequence of events.
101 Synchronous operation on a single device
105 the device is suspended (in case device is no longer used). It will likely not
108 slow bus. For this reason the device drivers can also make use of the
110 the suspend operation, again, if device is no longer used. The suspension will
116 Asynchronous operation on a single device
121 In a first place, a device driver needs to implement the PM action callback used
126 static int mydev_pm_action(const struct device *dev,
131 /* suspend the device */
135 /* resume the device */
148 To enable device runtime power management on a device, the driver needs to call
150 function will suspend the device if its state is
151 :c:enumerator:`PM_DEVICE_STATE_ACTIVE`. In case the device is physically
158 /* device driver initialization function */
159 static int mydev_init(const struct device *dev)
164 /* OPTIONAL: mark device as suspended if it is physically suspended */
167 /* enable device runtime power management */
174 Device runtime power management can also be automatically enabled on a device
175 instance by adding the ``zephyr,pm-device-runtime-auto`` flag onto the corresponding
177 after the ``init`` function of the device runs and returns successfully.
183 zephyr,pm-device-runtime-auto;
186 Assuming an example device driver that implements an ``operation`` API call, the
191 static int mydev_operation(const struct device *dev)
195 /* "get" device (increases usage count, resumes device if suspended) */
201 /* do something with the device */
204 /* "put" device (decreases usage count, suspends device if no more users) */
208 In case the suspend operation is *slow*, the device driver can use the
213 static int mydev_operation(const struct device *dev)
217 /* "get" device (increases usage count, resumes device if suspended) */
223 /* do something with the device */
226 /* "put" device (decreases usage count, schedule suspend if no more users) */
233 Some helpful examples showing device runtime power management features: