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
30 :caption: Device states and transitions
49 The device runtime power management framework has been designed to minimize
50 devices power consumption with minimal application work. Device drivers are
51 responsible for indicating when they need the device to be operational and
53 device. An application can, however, decide when to disable or enable runtime
54 power management for a device. This can be useful, for example, if an
55 application wants a particular device to be always active.
60 When runtime PM is enabled on a device it will no longer be resumed or suspended
61 during system power transitions. Instead, the device is fully responsible to
62 indicate when it needs a device and when it does not. The device runtime PM API
63 uses reference counting to keep track of device's usage. This allows the API to
64 determine when a device needs to be resumed or suspended. The API uses the *get*
65 and *put* terminology to indicate when a device is needed or not, respectively.
66 This mechanism plays a key role when we account for device dependencies. For
67 example, if a bus device is used by multiple sensors, we can keep the bus active
72 As of today, the device runtime power management API does not manage device
73 dependencies. This effectively means that, if a device depends on other
74 devices to operate (e.g. a sensor may depend on a bus device), the bus will
81 The :c:func:`pm_device_runtime_get` function can be used by a device driver to
82 indicate it *needs* the device to be active or operational. This function will
83 increase device usage count and resume the device if necessary. Similarly, the
84 :c:func:`pm_device_runtime_put` function can be used to indicate that the device
85 is no longer needed. This function will decrease the device usage count and
86 suspend the device if necessary. It is worth to note that in both cases, the
88 illustrates how a device can use this API and the expected sequence of events.
92 Synchronous operation on a single device
96 the device is suspended (in case device is no longer used). It will likely not
99 slow bus. For this reason the device drivers can also make use of the
101 the suspend operation, again, if device is no longer used. The suspension will
107 Asynchronous operation on a single device
112 In a first place, a device driver needs to implement the PM action callback used
117 static int mydev_pm_action(const struct device *dev,
122 /* suspend the device */
126 /* resume the device */
139 To enable device runtime power management on a device, the driver needs to call
141 function will suspend the device if its state is
142 :c:enumerator:`PM_DEVICE_STATE_ACTIVE`. In case the device is physically
149 /* device driver initialization function */
150 static int mydev_init(const struct device *dev)
155 /* OPTIONAL: mark device as suspended if it is physically suspended */
158 /* enable device runtime power management */
165 Device runtime power management can also be automatically enabled on a device
166 instance by adding the ``zephyr,pm-device-runtime-auto`` flag onto the corresponding
168 after the ``init`` function of the device runs and returns successfully.
174 zephyr,pm-device-runtime-auto;
177 Assuming an example device driver that implements an ``operation`` API call, the
182 static int mydev_operation(const struct device *dev)
186 /* "get" device (increases usage count, resumes device if suspended) */
192 /* do something with the device */
195 /* "put" device (decreases usage count, suspends device if no more users) */
199 In case the suspend operation is *slow*, the device driver can use the
204 static int mydev_operation(const struct device *dev)
208 /* "get" device (increases usage count, resumes device if suspended) */
214 /* do something with the device */
217 /* "put" device (decreases usage count, schedule suspend if no more users) */