Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 1 | Runtime Power Management Framework for I/O Devices |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 2 | |
Rafael J. Wysocki | 9659cc0 | 2011-02-18 23:20:21 +0100 | [diff] [blame] | 3 | (C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 4 | (C) 2010 Alan Stern <stern@rowland.harvard.edu> |
Rafael J. Wysocki | f71495f | 2014-05-16 02:47:37 +0200 | [diff] [blame] | 5 | (C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 6 | |
| 7 | 1. Introduction |
| 8 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 9 | Support for runtime power management (runtime PM) of I/O devices is provided |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 10 | at the power management core (PM core) level by means of: |
| 11 | |
| 12 | * The power management workqueue pm_wq in which bus types and device drivers can |
| 13 | put their PM-related work items. It is strongly recommended that pm_wq be |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 14 | used for queuing all work items related to runtime PM, because this allows |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 15 | them to be synchronized with system-wide power transitions (suspend to RAM, |
| 16 | hibernation and resume from system sleep states). pm_wq is declared in |
| 17 | include/linux/pm_runtime.h and defined in kernel/power/main.c. |
| 18 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 19 | * A number of runtime PM fields in the 'power' member of 'struct device' (which |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 20 | is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 21 | be used for synchronizing runtime PM operations with one another. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 22 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 23 | * Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 24 | include/linux/pm.h). |
| 25 | |
| 26 | * A set of helper functions defined in drivers/base/power/runtime.c that can be |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 27 | used for carrying out runtime PM operations in such a way that the |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 28 | synchronization between them is taken care of by the PM core. Bus types and |
| 29 | device drivers are encouraged to use these functions. |
| 30 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 31 | The runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 32 | fields of 'struct dev_pm_info' and the core helper functions provided for |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 33 | runtime PM are described below. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 34 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 35 | 2. Device Runtime PM Callbacks |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 36 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 37 | There are three device runtime PM callbacks defined in 'struct dev_pm_ops': |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 38 | |
| 39 | struct dev_pm_ops { |
| 40 | ... |
| 41 | int (*runtime_suspend)(struct device *dev); |
| 42 | int (*runtime_resume)(struct device *dev); |
Rafael J. Wysocki | e1b1903 | 2009-12-03 21:04:08 +0100 | [diff] [blame] | 43 | int (*runtime_idle)(struct device *dev); |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 44 | ... |
| 45 | }; |
| 46 | |
Ming Lei | 2fb242a | 2011-10-09 11:40:25 +0800 | [diff] [blame] | 47 | The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 48 | are executed by the PM core for the device's subsystem that may be either of |
| 49 | the following: |
| 50 | |
| 51 | 1. PM domain of the device, if the device's PM domain object, dev->pm_domain, |
| 52 | is present. |
| 53 | |
| 54 | 2. Device type of the device, if both dev->type and dev->type->pm are present. |
| 55 | |
| 56 | 3. Device class of the device, if both dev->class and dev->class->pm are |
| 57 | present. |
| 58 | |
| 59 | 4. Bus type of the device, if both dev->bus and dev->bus->pm are present. |
| 60 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 61 | If the subsystem chosen by applying the above rules doesn't provide the relevant |
| 62 | callback, the PM core will invoke the corresponding driver callback stored in |
| 63 | dev->driver->pm directly (if present). |
| 64 | |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 65 | The PM core always checks which callback to use in the order given above, so the |
| 66 | priority order of callbacks from high to low is: PM domain, device type, class |
| 67 | and bus type. Moreover, the high-priority one will always take precedence over |
| 68 | a low-priority one. The PM domain, bus type, device type and class callbacks |
| 69 | are referred to as subsystem-level callbacks in what follows. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 70 | |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 71 | By default, the callbacks are always invoked in process context with interrupts |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 72 | enabled. However, the pm_runtime_irq_safe() helper function can be used to tell |
| 73 | the PM core that it is safe to run the ->runtime_suspend(), ->runtime_resume() |
| 74 | and ->runtime_idle() callbacks for the given device in atomic context with |
| 75 | interrupts disabled. This implies that the callback routines in question must |
| 76 | not block or sleep, but it also means that the synchronous helper functions |
| 77 | listed at the end of Section 4 may be used for that device within an interrupt |
| 78 | handler or generally in an atomic context. |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 79 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 80 | The subsystem-level suspend callback, if present, is _entirely_ _responsible_ |
| 81 | for handling the suspend of the device as appropriate, which may, but need not |
| 82 | include executing the device driver's own ->runtime_suspend() callback (from the |
Rafael J. Wysocki | a6ab7aa | 2009-12-22 20:43:17 +0100 | [diff] [blame] | 83 | PM core's point of view it is not necessary to implement a ->runtime_suspend() |
| 84 | callback in a device driver as long as the subsystem-level suspend callback |
| 85 | knows what to do to handle the device). |
| 86 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 87 | * Once the subsystem-level suspend callback (or the driver suspend callback, |
| 88 | if invoked directly) has completed successfully for the given device, the PM |
| 89 | core regards the device as suspended, which need not mean that it has been |
| 90 | put into a low power state. It is supposed to mean, however, that the |
| 91 | device will not process data and will not communicate with the CPU(s) and |
| 92 | RAM until the appropriate resume callback is executed for it. The runtime |
| 93 | PM status of a device after successful execution of the suspend callback is |
| 94 | 'suspended'. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 95 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 96 | * If the suspend callback returns -EBUSY or -EAGAIN, the device's runtime PM |
| 97 | status remains 'active', which means that the device _must_ be fully |
| 98 | operational afterwards. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 99 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 100 | * If the suspend callback returns an error code different from -EBUSY and |
| 101 | -EAGAIN, the PM core regards this as a fatal error and will refuse to run |
| 102 | the helper functions described in Section 4 for the device until its status |
| 103 | is directly set to either'active', or 'suspended' (the PM core provides |
| 104 | special helper functions for this purpose). |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 105 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 106 | In particular, if the driver requires remote wakeup capability (i.e. hardware |
Rafael J. Wysocki | a6ab7aa | 2009-12-22 20:43:17 +0100 | [diff] [blame] | 107 | mechanism allowing the device to request a change of its power state, such as |
| 108 | PCI PME) for proper functioning and device_run_wake() returns 'false' for the |
| 109 | device, then ->runtime_suspend() should return -EBUSY. On the other hand, if |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 110 | device_run_wake() returns 'true' for the device and the device is put into a |
| 111 | low-power state during the execution of the suspend callback, it is expected |
| 112 | that remote wakeup will be enabled for the device. Generally, remote wakeup |
| 113 | should be enabled for all input devices put into low-power states at run time. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 114 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 115 | The subsystem-level resume callback, if present, is _entirely_ _responsible_ for |
| 116 | handling the resume of the device as appropriate, which may, but need not |
| 117 | include executing the device driver's own ->runtime_resume() callback (from the |
| 118 | PM core's point of view it is not necessary to implement a ->runtime_resume() |
| 119 | callback in a device driver as long as the subsystem-level resume callback knows |
| 120 | what to do to handle the device). |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 121 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 122 | * Once the subsystem-level resume callback (or the driver resume callback, if |
| 123 | invoked directly) has completed successfully, the PM core regards the device |
| 124 | as fully operational, which means that the device _must_ be able to complete |
| 125 | I/O operations as needed. The runtime PM status of the device is then |
| 126 | 'active'. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 127 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 128 | * If the resume callback returns an error code, the PM core regards this as a |
| 129 | fatal error and will refuse to run the helper functions described in Section |
| 130 | 4 for the device, until its status is directly set to either 'active', or |
| 131 | 'suspended' (by means of special helper functions provided by the PM core |
| 132 | for this purpose). |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 133 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 134 | The idle callback (a subsystem-level one, if present, or the driver one) is |
| 135 | executed by the PM core whenever the device appears to be idle, which is |
| 136 | indicated to the PM core by two counters, the device's usage counter and the |
| 137 | counter of 'active' children of the device. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 138 | |
| 139 | * If any of these counters is decreased using a helper function provided by |
| 140 | the PM core and it turns out to be equal to zero, the other counter is |
| 141 | checked. If that counter also is equal to zero, the PM core executes the |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 142 | idle callback with the device as its argument. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 143 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 144 | The action performed by the idle callback is totally dependent on the subsystem |
| 145 | (or driver) in question, but the expected and recommended action is to check |
Rafael J. Wysocki | a6ab7aa | 2009-12-22 20:43:17 +0100 | [diff] [blame] | 146 | if the device can be suspended (i.e. if all of the conditions necessary for |
| 147 | suspending the device are satisfied) and to queue up a suspend request for the |
Alan Stern | 43d51af | 2013-06-03 21:49:59 +0200 | [diff] [blame] | 148 | device in that case. If there is no idle callback, or if the callback returns |
Ulf Hansson | d66e6db | 2013-10-15 22:25:08 +0200 | [diff] [blame] | 149 | 0, then the PM core will attempt to carry out a runtime suspend of the device, |
| 150 | also respecting devices configured for autosuspend. In essence this means a |
| 151 | call to pm_runtime_autosuspend() (do note that drivers needs to update the |
| 152 | device last busy mark, pm_runtime_mark_last_busy(), to control the delay under |
| 153 | this circumstance). To prevent this (for example, if the callback routine has |
| 154 | started a delayed suspend), the routine must return a non-zero value. Negative |
| 155 | error return codes are ignored by the PM core. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 156 | |
| 157 | The helper functions provided by the PM core, described in Section 4, guarantee |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 158 | that the following constraints are met with respect to runtime PM callbacks for |
| 159 | one device: |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 160 | |
| 161 | (1) The callbacks are mutually exclusive (e.g. it is forbidden to execute |
| 162 | ->runtime_suspend() in parallel with ->runtime_resume() or with another |
| 163 | instance of ->runtime_suspend() for the same device) with the exception that |
| 164 | ->runtime_suspend() or ->runtime_resume() can be executed in parallel with |
| 165 | ->runtime_idle() (although ->runtime_idle() will not be started while any |
| 166 | of the other callbacks is being executed for the same device). |
| 167 | |
| 168 | (2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active' |
| 169 | devices (i.e. the PM core will only execute ->runtime_idle() or |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 170 | ->runtime_suspend() for the devices the runtime PM status of which is |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 171 | 'active'). |
| 172 | |
| 173 | (3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device |
| 174 | the usage counter of which is equal to zero _and_ either the counter of |
| 175 | 'active' children of which is equal to zero, or the 'power.ignore_children' |
| 176 | flag of which is set. |
| 177 | |
| 178 | (4) ->runtime_resume() can only be executed for 'suspended' devices (i.e. the |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 179 | PM core will only execute ->runtime_resume() for the devices the runtime |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 180 | PM status of which is 'suspended'). |
| 181 | |
| 182 | Additionally, the helper functions provided by the PM core obey the following |
| 183 | rules: |
| 184 | |
| 185 | * If ->runtime_suspend() is about to be executed or there's a pending request |
| 186 | to execute it, ->runtime_idle() will not be executed for the same device. |
| 187 | |
| 188 | * A request to execute or to schedule the execution of ->runtime_suspend() |
| 189 | will cancel any pending requests to execute ->runtime_idle() for the same |
| 190 | device. |
| 191 | |
| 192 | * If ->runtime_resume() is about to be executed or there's a pending request |
| 193 | to execute it, the other callbacks will not be executed for the same device. |
| 194 | |
| 195 | * A request to execute ->runtime_resume() will cancel any pending or |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 196 | scheduled requests to execute the other callbacks for the same device, |
| 197 | except for scheduled autosuspends. |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 198 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 199 | 3. Runtime PM Device Fields |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 200 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 201 | The following device runtime PM fields are present in 'struct dev_pm_info', as |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 202 | defined in include/linux/pm.h: |
| 203 | |
| 204 | struct timer_list suspend_timer; |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 205 | - timer used for scheduling (delayed) suspend and autosuspend requests |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 206 | |
| 207 | unsigned long timer_expires; |
| 208 | - timer expiration time, in jiffies (if this is different from zero, the |
| 209 | timer is running and will expire at that time, otherwise the timer is not |
| 210 | running) |
| 211 | |
| 212 | struct work_struct work; |
| 213 | - work structure used for queuing up requests (i.e. work items in pm_wq) |
| 214 | |
| 215 | wait_queue_head_t wait_queue; |
| 216 | - wait queue used if any of the helper functions needs to wait for another |
| 217 | one to complete |
| 218 | |
| 219 | spinlock_t lock; |
| 220 | - lock used for synchronisation |
| 221 | |
| 222 | atomic_t usage_count; |
| 223 | - the usage counter of the device |
| 224 | |
| 225 | atomic_t child_count; |
| 226 | - the count of 'active' children of the device |
| 227 | |
| 228 | unsigned int ignore_children; |
| 229 | - if set, the value of child_count is ignored (but still updated) |
| 230 | |
| 231 | unsigned int disable_depth; |
Masanari Iida | 1f999d1 | 2014-11-08 17:54:51 +0900 | [diff] [blame] | 232 | - used for disabling the helper functions (they work normally if this is |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 233 | equal to zero); the initial value of it is 1 (i.e. runtime PM is |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 234 | initially disabled for all devices) |
| 235 | |
Geert Uytterhoeven | e1a2976 | 2014-03-24 21:31:27 +0100 | [diff] [blame] | 236 | int runtime_error; |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 237 | - if set, there was a fatal error (one of the callbacks returned error code |
Masanari Iida | 1f999d1 | 2014-11-08 17:54:51 +0900 | [diff] [blame] | 238 | as described in Section 2), so the helper functions will not work until |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 239 | this flag is cleared; this is the error code returned by the failing |
| 240 | callback |
| 241 | |
| 242 | unsigned int idle_notification; |
| 243 | - if set, ->runtime_idle() is being executed |
| 244 | |
| 245 | unsigned int request_pending; |
| 246 | - if set, there's a pending request (i.e. a work item queued up into pm_wq) |
| 247 | |
| 248 | enum rpm_request request; |
| 249 | - type of request that's pending (valid if request_pending is set) |
| 250 | |
| 251 | unsigned int deferred_resume; |
| 252 | - set if ->runtime_resume() is about to be run while ->runtime_suspend() is |
| 253 | being executed for that device and it is not practical to wait for the |
| 254 | suspend to complete; means "start a resume as soon as you've suspended" |
| 255 | |
Rafael J. Wysocki | 7a1a8eb | 2009-12-03 21:19:18 +0100 | [diff] [blame] | 256 | unsigned int run_wake; |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 257 | - set if the device is capable of generating runtime wake-up events |
Rafael J. Wysocki | 7a1a8eb | 2009-12-03 21:19:18 +0100 | [diff] [blame] | 258 | |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 259 | enum rpm_status runtime_status; |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 260 | - the runtime PM status of the device; this field's initial value is |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 261 | RPM_SUSPENDED, which means that each device is initially regarded by the |
| 262 | PM core as 'suspended', regardless of its real hardware status |
| 263 | |
Rafael J. Wysocki | 87d1b3e | 2010-03-06 21:28:17 +0100 | [diff] [blame] | 264 | unsigned int runtime_auto; |
| 265 | - if set, indicates that the user space has allowed the device driver to |
| 266 | power manage the device at run time via the /sys/devices/.../power/control |
| 267 | interface; it may only be modified with the help of the pm_runtime_allow() |
| 268 | and pm_runtime_forbid() helper functions |
| 269 | |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 270 | unsigned int no_callbacks; |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 271 | - indicates that the device does not use the runtime PM callbacks (see |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 272 | Section 8); it may be modified only by the pm_runtime_no_callbacks() |
| 273 | helper function |
| 274 | |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 275 | unsigned int irq_safe; |
| 276 | - indicates that the ->runtime_suspend() and ->runtime_resume() callbacks |
| 277 | will be invoked with the spinlock held and interrupts disabled |
| 278 | |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 279 | unsigned int use_autosuspend; |
| 280 | - indicates that the device's driver supports delayed autosuspend (see |
| 281 | Section 9); it may be modified only by the |
| 282 | pm_runtime{_dont}_use_autosuspend() helper functions |
| 283 | |
| 284 | unsigned int timer_autosuspends; |
| 285 | - indicates that the PM core should attempt to carry out an autosuspend |
| 286 | when the timer expires rather than a normal suspend |
| 287 | |
| 288 | int autosuspend_delay; |
| 289 | - the delay time (in milliseconds) to be used for autosuspend |
| 290 | |
| 291 | unsigned long last_busy; |
| 292 | - the time (in jiffies) when the pm_runtime_mark_last_busy() helper |
| 293 | function was last called for this device; used in calculating inactivity |
| 294 | periods for autosuspend |
| 295 | |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 296 | All of the above fields are members of the 'power' member of 'struct device'. |
| 297 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 298 | 4. Runtime PM Device Helper Functions |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 299 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 300 | The following runtime PM helper functions are defined in |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 301 | drivers/base/power/runtime.c and include/linux/pm_runtime.h: |
| 302 | |
| 303 | void pm_runtime_init(struct device *dev); |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 304 | - initialize the device runtime PM fields in 'struct dev_pm_info' |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 305 | |
| 306 | void pm_runtime_remove(struct device *dev); |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 307 | - make sure that the runtime PM of the device will be disabled after |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 308 | removing the device from device hierarchy |
| 309 | |
| 310 | int pm_runtime_idle(struct device *dev); |
Alan Stern | 43d51af | 2013-06-03 21:49:59 +0200 | [diff] [blame] | 311 | - execute the subsystem-level idle callback for the device; returns an |
| 312 | error code on failure, where -EINPROGRESS means that ->runtime_idle() is |
| 313 | already being executed; if there is no callback or the callback returns 0 |
Ulf Hansson | d66e6db | 2013-10-15 22:25:08 +0200 | [diff] [blame] | 314 | then run pm_runtime_autosuspend(dev) and return its result |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 315 | |
| 316 | int pm_runtime_suspend(struct device *dev); |
Rafael J. Wysocki | a6ab7aa | 2009-12-22 20:43:17 +0100 | [diff] [blame] | 317 | - execute the subsystem-level suspend callback for the device; returns 0 on |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 318 | success, 1 if the device's runtime PM status was already 'suspended', or |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 319 | error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt |
Rafael J. Wysocki | 632e270 | 2011-07-01 22:29:15 +0200 | [diff] [blame] | 320 | to suspend the device again in future and -EACCES means that |
| 321 | 'power.disable_depth' is different from 0 |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 322 | |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 323 | int pm_runtime_autosuspend(struct device *dev); |
| 324 | - same as pm_runtime_suspend() except that the autosuspend delay is taken |
| 325 | into account; if pm_runtime_autosuspend_expiration() says the delay has |
| 326 | not yet expired then an autosuspend is scheduled for the appropriate time |
| 327 | and 0 is returned |
| 328 | |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 329 | int pm_runtime_resume(struct device *dev); |
Thadeu Lima de Souza Cascardo | de8164f | 2010-01-17 19:22:28 -0200 | [diff] [blame] | 330 | - execute the subsystem-level resume callback for the device; returns 0 on |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 331 | success, 1 if the device's runtime PM status was already 'active' or |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 332 | error code on failure, where -EAGAIN means it may be safe to attempt to |
| 333 | resume the device again in future, but 'power.runtime_error' should be |
Rafael J. Wysocki | 632e270 | 2011-07-01 22:29:15 +0200 | [diff] [blame] | 334 | checked additionally, and -EACCES means that 'power.disable_depth' is |
| 335 | different from 0 |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 336 | |
| 337 | int pm_request_idle(struct device *dev); |
Rafael J. Wysocki | a6ab7aa | 2009-12-22 20:43:17 +0100 | [diff] [blame] | 338 | - submit a request to execute the subsystem-level idle callback for the |
| 339 | device (the request is represented by a work item in pm_wq); returns 0 on |
| 340 | success or error code if the request has not been queued up |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 341 | |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 342 | int pm_request_autosuspend(struct device *dev); |
| 343 | - schedule the execution of the subsystem-level suspend callback for the |
| 344 | device when the autosuspend delay has expired; if the delay has already |
| 345 | expired then the work item is queued up immediately |
| 346 | |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 347 | int pm_schedule_suspend(struct device *dev, unsigned int delay); |
Rafael J. Wysocki | a6ab7aa | 2009-12-22 20:43:17 +0100 | [diff] [blame] | 348 | - schedule the execution of the subsystem-level suspend callback for the |
| 349 | device in future, where 'delay' is the time to wait before queuing up a |
| 350 | suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work |
| 351 | item is queued up immediately); returns 0 on success, 1 if the device's PM |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 352 | runtime status was already 'suspended', or error code if the request |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 353 | hasn't been scheduled (or queued up if 'delay' is 0); if the execution of |
| 354 | ->runtime_suspend() is already scheduled and not yet expired, the new |
| 355 | value of 'delay' will be used as the time to wait |
| 356 | |
| 357 | int pm_request_resume(struct device *dev); |
Rafael J. Wysocki | a6ab7aa | 2009-12-22 20:43:17 +0100 | [diff] [blame] | 358 | - submit a request to execute the subsystem-level resume callback for the |
| 359 | device (the request is represented by a work item in pm_wq); returns 0 on |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 360 | success, 1 if the device's runtime PM status was already 'active', or |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 361 | error code if the request hasn't been queued up |
| 362 | |
| 363 | void pm_runtime_get_noresume(struct device *dev); |
| 364 | - increment the device's usage counter |
| 365 | |
| 366 | int pm_runtime_get(struct device *dev); |
| 367 | - increment the device's usage counter, run pm_request_resume(dev) and |
| 368 | return its result |
| 369 | |
| 370 | int pm_runtime_get_sync(struct device *dev); |
| 371 | - increment the device's usage counter, run pm_runtime_resume(dev) and |
| 372 | return its result |
| 373 | |
Rafael J. Wysocki | a436b6a | 2015-12-17 02:54:26 +0100 | [diff] [blame] | 374 | int pm_runtime_get_if_in_use(struct device *dev); |
| 375 | - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the |
| 376 | runtime PM status is RPM_ACTIVE and the runtime PM usage counter is |
| 377 | nonzero, increment the counter and return 1; otherwise return 0 without |
| 378 | changing the counter |
| 379 | |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 380 | void pm_runtime_put_noidle(struct device *dev); |
| 381 | - decrement the device's usage counter |
| 382 | |
| 383 | int pm_runtime_put(struct device *dev); |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 384 | - decrement the device's usage counter; if the result is 0 then run |
| 385 | pm_request_idle(dev) and return its result |
| 386 | |
| 387 | int pm_runtime_put_autosuspend(struct device *dev); |
| 388 | - decrement the device's usage counter; if the result is 0 then run |
| 389 | pm_request_autosuspend(dev) and return its result |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 390 | |
| 391 | int pm_runtime_put_sync(struct device *dev); |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 392 | - decrement the device's usage counter; if the result is 0 then run |
| 393 | pm_runtime_idle(dev) and return its result |
| 394 | |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 395 | int pm_runtime_put_sync_suspend(struct device *dev); |
| 396 | - decrement the device's usage counter; if the result is 0 then run |
| 397 | pm_runtime_suspend(dev) and return its result |
| 398 | |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 399 | int pm_runtime_put_sync_autosuspend(struct device *dev); |
| 400 | - decrement the device's usage counter; if the result is 0 then run |
| 401 | pm_runtime_autosuspend(dev) and return its result |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 402 | |
| 403 | void pm_runtime_enable(struct device *dev); |
Rafael J. Wysocki | e358bad | 2011-07-06 10:52:06 +0200 | [diff] [blame] | 404 | - decrement the device's 'power.disable_depth' field; if that field is equal |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 405 | to zero, the runtime PM helper functions can execute subsystem-level |
Rafael J. Wysocki | e358bad | 2011-07-06 10:52:06 +0200 | [diff] [blame] | 406 | callbacks described in Section 2 for the device |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 407 | |
| 408 | int pm_runtime_disable(struct device *dev); |
Rafael J. Wysocki | e358bad | 2011-07-06 10:52:06 +0200 | [diff] [blame] | 409 | - increment the device's 'power.disable_depth' field (if the value of that |
| 410 | field was previously zero, this prevents subsystem-level runtime PM |
Geert Uytterhoeven | 91e63cc | 2014-03-24 21:31:28 +0100 | [diff] [blame] | 411 | callbacks from being run for the device), make sure that all of the |
| 412 | pending runtime PM operations on the device are either completed or |
| 413 | canceled; returns 1 if there was a resume request pending and it was |
| 414 | necessary to execute the subsystem-level resume callback for the device |
| 415 | to satisfy that request, otherwise 0 is returned |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 416 | |
Rafael J. Wysocki | e358bad | 2011-07-06 10:52:06 +0200 | [diff] [blame] | 417 | int pm_runtime_barrier(struct device *dev); |
| 418 | - check if there's a resume request pending for the device and resume it |
| 419 | (synchronously) in that case, cancel any other pending runtime PM requests |
| 420 | regarding it and wait for all runtime PM operations on it in progress to |
| 421 | complete; returns 1 if there was a resume request pending and it was |
| 422 | necessary to execute the subsystem-level resume callback for the device to |
| 423 | satisfy that request, otherwise 0 is returned |
| 424 | |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 425 | void pm_suspend_ignore_children(struct device *dev, bool enable); |
| 426 | - set/unset the power.ignore_children flag of the device |
| 427 | |
| 428 | int pm_runtime_set_active(struct device *dev); |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 429 | - clear the device's 'power.runtime_error' flag, set the device's runtime |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 430 | PM status to 'active' and update its parent's counter of 'active' |
| 431 | children as appropriate (it is only valid to use this function if |
| 432 | 'power.runtime_error' is set or 'power.disable_depth' is greater than |
| 433 | zero); it will fail and return error code if the device has a parent |
| 434 | which is not active and the 'power.ignore_children' flag of which is unset |
| 435 | |
| 436 | void pm_runtime_set_suspended(struct device *dev); |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 437 | - clear the device's 'power.runtime_error' flag, set the device's runtime |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 438 | PM status to 'suspended' and update its parent's counter of 'active' |
| 439 | children as appropriate (it is only valid to use this function if |
| 440 | 'power.runtime_error' is set or 'power.disable_depth' is greater than |
| 441 | zero) |
| 442 | |
ShuoX Liu | fbadc58 | 2013-01-23 21:49:37 +0100 | [diff] [blame] | 443 | bool pm_runtime_active(struct device *dev); |
| 444 | - return true if the device's runtime PM status is 'active' or its |
| 445 | 'power.disable_depth' field is not equal to zero, or false otherwise |
| 446 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 447 | bool pm_runtime_suspended(struct device *dev); |
Rafael J. Wysocki | f08f5a0 | 2010-12-16 17:11:58 +0100 | [diff] [blame] | 448 | - return true if the device's runtime PM status is 'suspended' and its |
| 449 | 'power.disable_depth' field is equal to zero, or false otherwise |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 450 | |
Kevin Hilman | f3393b6 | 2011-07-12 11:17:09 +0200 | [diff] [blame] | 451 | bool pm_runtime_status_suspended(struct device *dev); |
| 452 | - return true if the device's runtime PM status is 'suspended' |
| 453 | |
Rafael J. Wysocki | 87d1b3e | 2010-03-06 21:28:17 +0100 | [diff] [blame] | 454 | void pm_runtime_allow(struct device *dev); |
| 455 | - set the power.runtime_auto flag for the device and decrease its usage |
| 456 | counter (used by the /sys/devices/.../power/control interface to |
| 457 | effectively allow the device to be power managed at run time) |
| 458 | |
| 459 | void pm_runtime_forbid(struct device *dev); |
| 460 | - unset the power.runtime_auto flag for the device and increase its usage |
| 461 | counter (used by the /sys/devices/.../power/control interface to |
| 462 | effectively prevent the device from being power managed at run time) |
| 463 | |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 464 | void pm_runtime_no_callbacks(struct device *dev); |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 465 | - set the power.no_callbacks flag for the device and remove the runtime |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 466 | PM attributes from /sys/devices/.../power (or prevent them from being |
| 467 | added when the device is registered) |
| 468 | |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 469 | void pm_runtime_irq_safe(struct device *dev); |
| 470 | - set the power.irq_safe flag for the device, causing the runtime-PM |
Rafael J. Wysocki | 64584eb | 2011-08-25 15:31:05 +0200 | [diff] [blame] | 471 | callbacks to be invoked with interrupts off |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 472 | |
Krzysztof Kozlowski | 3fb1581 | 2014-11-14 09:47:25 +0100 | [diff] [blame] | 473 | bool pm_runtime_is_irq_safe(struct device *dev); |
| 474 | - return true if power.irq_safe flag was set for the device, causing |
| 475 | the runtime-PM callbacks to be invoked with interrupts off |
| 476 | |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 477 | void pm_runtime_mark_last_busy(struct device *dev); |
| 478 | - set the power.last_busy field to the current time |
| 479 | |
| 480 | void pm_runtime_use_autosuspend(struct device *dev); |
| 481 | - set the power.use_autosuspend flag, enabling autosuspend delays |
| 482 | |
| 483 | void pm_runtime_dont_use_autosuspend(struct device *dev); |
| 484 | - clear the power.use_autosuspend flag, disabling autosuspend delays |
| 485 | |
| 486 | void pm_runtime_set_autosuspend_delay(struct device *dev, int delay); |
| 487 | - set the power.autosuspend_delay value to 'delay' (expressed in |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 488 | milliseconds); if 'delay' is negative then runtime suspends are |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 489 | prevented |
| 490 | |
| 491 | unsigned long pm_runtime_autosuspend_expiration(struct device *dev); |
| 492 | - calculate the time when the current autosuspend delay period will expire, |
| 493 | based on power.last_busy and power.autosuspend_delay; if the delay time |
| 494 | is 1000 ms or larger then the expiration time is rounded up to the |
| 495 | nearest second; returns 0 if the delay period has already expired or |
| 496 | power.use_autosuspend isn't set, otherwise returns the expiration time |
| 497 | in jiffies |
| 498 | |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 499 | It is safe to execute the following helper functions from interrupt context: |
| 500 | |
| 501 | pm_request_idle() |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 502 | pm_request_autosuspend() |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 503 | pm_schedule_suspend() |
| 504 | pm_request_resume() |
| 505 | pm_runtime_get_noresume() |
| 506 | pm_runtime_get() |
| 507 | pm_runtime_put_noidle() |
| 508 | pm_runtime_put() |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 509 | pm_runtime_put_autosuspend() |
| 510 | pm_runtime_enable() |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 511 | pm_suspend_ignore_children() |
| 512 | pm_runtime_set_active() |
| 513 | pm_runtime_set_suspended() |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 514 | pm_runtime_suspended() |
| 515 | pm_runtime_mark_last_busy() |
| 516 | pm_runtime_autosuspend_expiration() |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 517 | |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 518 | If pm_runtime_irq_safe() has been called for a device then the following helper |
| 519 | functions may also be used in interrupt context: |
| 520 | |
Ming Lei | 2e6ba51 | 2011-09-21 22:31:33 +0200 | [diff] [blame] | 521 | pm_runtime_idle() |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 522 | pm_runtime_suspend() |
| 523 | pm_runtime_autosuspend() |
| 524 | pm_runtime_resume() |
| 525 | pm_runtime_get_sync() |
Kevin Hilman | 02b2677 | 2011-08-05 21:45:20 +0200 | [diff] [blame] | 526 | pm_runtime_put_sync() |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 527 | pm_runtime_put_sync_suspend() |
Colin Cross | 311aab7 | 2011-08-08 23:39:36 +0200 | [diff] [blame] | 528 | pm_runtime_put_sync_autosuspend() |
Alan Stern | c7b61de | 2010-12-01 00:14:42 +0100 | [diff] [blame] | 529 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 530 | 5. Runtime PM Initialization, Device Probing and Removal |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 531 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 532 | Initially, the runtime PM is disabled for all devices, which means that the |
Masanari Iida | 1f999d1 | 2014-11-08 17:54:51 +0900 | [diff] [blame] | 533 | majority of the runtime PM helper functions described in Section 4 will return |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 534 | -EAGAIN until pm_runtime_enable() is called for the device. |
| 535 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 536 | In addition to that, the initial runtime PM status of all devices is |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 537 | 'suspended', but it need not reflect the actual physical state of the device. |
| 538 | Thus, if the device is initially active (i.e. it is able to process I/O), its |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 539 | runtime PM status must be changed to 'active', with the help of |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 540 | pm_runtime_set_active(), before pm_runtime_enable() is called for the device. |
| 541 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 542 | However, if the device has a parent and the parent's runtime PM is enabled, |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 543 | calling pm_runtime_set_active() for the device will affect the parent, unless |
| 544 | the parent's 'power.ignore_children' flag is set. Namely, in that case the |
| 545 | parent won't be able to suspend at run time, using the PM core's helper |
| 546 | functions, as long as the child's status is 'active', even if the child's |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 547 | runtime PM is still disabled (i.e. pm_runtime_enable() hasn't been called for |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 548 | the child yet or pm_runtime_disable() has been called for it). For this reason, |
| 549 | once pm_runtime_set_active() has been called for the device, pm_runtime_enable() |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 550 | should be called for it too as soon as reasonably possible or its runtime PM |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 551 | status should be changed back to 'suspended' with the help of |
| 552 | pm_runtime_set_suspended(). |
| 553 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 554 | If the default initial runtime PM status of the device (i.e. 'suspended') |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 555 | reflects the actual state of the device, its bus type's or its driver's |
| 556 | ->probe() callback will likely need to wake it up using one of the PM core's |
| 557 | helper functions described in Section 4. In that case, pm_runtime_resume() |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 558 | should be used. Of course, for this purpose the device's runtime PM has to be |
Rafael J. Wysocki | 5e928f7 | 2009-08-18 23:38:32 +0200 | [diff] [blame] | 559 | enabled earlier by calling pm_runtime_enable(). |
| 560 | |
Ben Dooks | f6a2fbb | 2015-04-17 01:14:15 +0100 | [diff] [blame] | 561 | Note, if the device may execute pm_runtime calls during the probe (such as |
| 562 | if it is registers with a subsystem that may call back in) then the |
| 563 | pm_runtime_get_sync() call paired with a pm_runtime_put() call will be |
| 564 | appropriate to ensure that the device is not put back to sleep during the |
| 565 | probe. This can happen with systems such as the network device layer. |
| 566 | |
Ulf Hansson | ea30994 | 2013-11-08 06:13:51 +0100 | [diff] [blame] | 567 | It may be desirable to suspend the device once ->probe() has finished. |
| 568 | Therefore the driver core uses the asyncronous pm_request_idle() to submit a |
| 569 | request to execute the subsystem-level idle callback for the device at that |
| 570 | time. A driver that makes use of the runtime autosuspend feature, may want to |
| 571 | update the last busy mark before returning from ->probe(). |
Rafael J. Wysocki | f5da24d | 2011-07-02 14:27:11 +0200 | [diff] [blame] | 572 | |
| 573 | Moreover, the driver core prevents runtime PM callbacks from racing with the bus |
| 574 | notifier callback in __device_release_driver(), which is necessary, because the |
| 575 | notifier is used by some subsystems to carry out operations affecting the |
| 576 | runtime PM functionality. It does so by calling pm_runtime_get_sync() before |
| 577 | driver_sysfs_remove() and the BUS_NOTIFY_UNBIND_DRIVER notifications. This |
| 578 | resumes the device if it's in the suspended state and prevents it from |
| 579 | being suspended again while those routines are being executed. |
| 580 | |
| 581 | To allow bus types and drivers to put devices into the suspended state by |
| 582 | calling pm_runtime_suspend() from their ->remove() routines, the driver core |
| 583 | executes pm_runtime_put_sync() after running the BUS_NOTIFY_UNBIND_DRIVER |
| 584 | notifications in __device_release_driver(). This requires bus types and |
| 585 | drivers to make their ->remove() callbacks avoid races with runtime PM directly, |
| 586 | but also it allows of more flexibility in the handling of devices during the |
| 587 | removal of their drivers. |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 588 | |
Krzysztof Kozlowski | 8fd2910 | 2016-04-03 12:23:07 +0900 | [diff] [blame] | 589 | Drivers in ->remove() callback should undo the runtime PM changes done |
| 590 | in ->probe(). Usually this means calling pm_runtime_disable(), |
| 591 | pm_runtime_dont_use_autosuspend() etc. |
| 592 | |
Rafael J. Wysocki | 87d1b3e | 2010-03-06 21:28:17 +0100 | [diff] [blame] | 593 | The user space can effectively disallow the driver of the device to power manage |
| 594 | it at run time by changing the value of its /sys/devices/.../power/control |
| 595 | attribute to "on", which causes pm_runtime_forbid() to be called. In principle, |
| 596 | this mechanism may also be used by the driver to effectively turn off the |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 597 | runtime power management of the device until the user space turns it on. |
| 598 | Namely, during the initialization the driver can make sure that the runtime PM |
Rafael J. Wysocki | 87d1b3e | 2010-03-06 21:28:17 +0100 | [diff] [blame] | 599 | status of the device is 'active' and call pm_runtime_forbid(). It should be |
| 600 | noted, however, that if the user space has already intentionally changed the |
| 601 | value of /sys/devices/.../power/control to "auto" to allow the driver to power |
| 602 | manage the device at run time, the driver may confuse it by using |
| 603 | pm_runtime_forbid() this way. |
| 604 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 605 | 6. Runtime PM and System Sleep |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 606 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 607 | Runtime PM and system sleep (i.e., system suspend and hibernation, also known |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 608 | as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of |
| 609 | ways. If a device is active when a system sleep starts, everything is |
| 610 | straightforward. But what should happen if the device is already suspended? |
| 611 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 612 | The device may have different wake-up settings for runtime PM and system sleep. |
| 613 | For example, remote wake-up may be enabled for runtime suspend but disallowed |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 614 | for system sleep (device_may_wakeup(dev) returns 'false'). When this happens, |
| 615 | the subsystem-level system suspend callback is responsible for changing the |
| 616 | device's wake-up setting (it may leave that to the device driver's system |
| 617 | suspend routine). It may be necessary to resume the device and suspend it again |
| 618 | in order to do so. The same is true if the driver uses different power levels |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 619 | or other settings for runtime suspend and system sleep. |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 620 | |
Rafael J. Wysocki | 455716e | 2011-07-01 22:29:05 +0200 | [diff] [blame] | 621 | During system resume, the simplest approach is to bring all devices back to full |
| 622 | power, even if they had been suspended before the system suspend began. There |
| 623 | are several reasons for this, including: |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 624 | |
| 625 | * The device might need to switch power levels, wake-up settings, etc. |
| 626 | |
| 627 | * Remote wake-up events might have been lost by the firmware. |
| 628 | |
| 629 | * The device's children may need the device to be at full power in order |
| 630 | to resume themselves. |
| 631 | |
| 632 | * The driver's idea of the device state may not agree with the device's |
| 633 | physical state. This can happen during resume from hibernation. |
| 634 | |
| 635 | * The device might need to be reset. |
| 636 | |
| 637 | * Even though the device was suspended, if its usage counter was > 0 then most |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 638 | likely it would need a runtime resume in the near future anyway. |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 639 | |
Rafael J. Wysocki | 455716e | 2011-07-01 22:29:05 +0200 | [diff] [blame] | 640 | If the device had been suspended before the system suspend began and it's |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 641 | brought back to full power during resume, then its runtime PM status will have |
Rafael J. Wysocki | 455716e | 2011-07-01 22:29:05 +0200 | [diff] [blame] | 642 | to be updated to reflect the actual post-system sleep status. The way to do |
| 643 | this is: |
Alan Stern | f1212ae | 2009-12-22 20:43:40 +0100 | [diff] [blame] | 644 | |
| 645 | pm_runtime_disable(dev); |
| 646 | pm_runtime_set_active(dev); |
| 647 | pm_runtime_enable(dev); |
| 648 | |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 649 | The PM core always increments the runtime usage counter before calling the |
Rafael J. Wysocki | 1e2ef05 | 2011-07-06 10:51:58 +0200 | [diff] [blame] | 650 | ->suspend() callback and decrements it after calling the ->resume() callback. |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 651 | Hence disabling runtime PM temporarily like this will not cause any runtime |
Rafael J. Wysocki | 1e2ef05 | 2011-07-06 10:51:58 +0200 | [diff] [blame] | 652 | suspend attempts to be permanently lost. If the usage count goes to zero |
| 653 | following the return of the ->resume() callback, the ->runtime_idle() callback |
| 654 | will be invoked as usual. |
| 655 | |
Rafael J. Wysocki | 455716e | 2011-07-01 22:29:05 +0200 | [diff] [blame] | 656 | On some systems, however, system sleep is not entered through a global firmware |
| 657 | or hardware operation. Instead, all hardware components are put into low-power |
| 658 | states directly by the kernel in a coordinated way. Then, the system sleep |
| 659 | state effectively follows from the states the hardware components end up in |
| 660 | and the system is woken up from that state by a hardware interrupt or a similar |
| 661 | mechanism entirely under the kernel's control. As a result, the kernel never |
| 662 | gives control away and the states of all devices during resume are precisely |
| 663 | known to it. If that is the case and none of the situations listed above takes |
| 664 | place (in particular, if the system is not waking up from hibernation), it may |
| 665 | be more efficient to leave the devices that had been suspended before the system |
| 666 | suspend began in the suspended state. |
| 667 | |
Rafael J. Wysocki | f71495f | 2014-05-16 02:47:37 +0200 | [diff] [blame] | 668 | To this end, the PM core provides a mechanism allowing some coordination between |
| 669 | different levels of device hierarchy. Namely, if a system suspend .prepare() |
| 670 | callback returns a positive number for a device, that indicates to the PM core |
| 671 | that the device appears to be runtime-suspended and its state is fine, so it |
| 672 | may be left in runtime suspend provided that all of its descendants are also |
| 673 | left in runtime suspend. If that happens, the PM core will not execute any |
| 674 | system suspend and resume callbacks for all of those devices, except for the |
| 675 | complete callback, which is then entirely responsible for handling the device |
| 676 | as appropriate. This only applies to system suspend transitions that are not |
| 677 | related to hibernation (see Documentation/power/devices.txt for more |
| 678 | information). |
| 679 | |
Rafael J. Wysocki | 1e2ef05 | 2011-07-06 10:51:58 +0200 | [diff] [blame] | 680 | The PM core does its best to reduce the probability of race conditions between |
| 681 | the runtime PM and system suspend/resume (and hibernation) callbacks by carrying |
| 682 | out the following operations: |
| 683 | |
Rafael J. Wysocki | 4ec6a9c | 2014-05-16 13:05:59 +0200 | [diff] [blame] | 684 | * During system suspend pm_runtime_get_noresume() is called for every device |
| 685 | right before executing the subsystem-level .prepare() callback for it and |
| 686 | pm_runtime_barrier() is called for every device right before executing the |
| 687 | subsystem-level .suspend() callback for it. In addition to that the PM core |
| 688 | calls __pm_runtime_disable() with 'false' as the second argument for every |
| 689 | device right before executing the subsystem-level .suspend_late() callback |
| 690 | for it. |
Rafael J. Wysocki | 1e2ef05 | 2011-07-06 10:51:58 +0200 | [diff] [blame] | 691 | |
Rafael J. Wysocki | 4ec6a9c | 2014-05-16 13:05:59 +0200 | [diff] [blame] | 692 | * During system resume pm_runtime_enable() and pm_runtime_put() are called for |
| 693 | every device right after executing the subsystem-level .resume_early() |
| 694 | callback and right after executing the subsystem-level .complete() callback |
Rafael J. Wysocki | 9f6d8f6 | 2012-12-22 23:59:01 +0100 | [diff] [blame] | 695 | for it, respectively. |
Rafael J. Wysocki | 1e2ef05 | 2011-07-06 10:51:58 +0200 | [diff] [blame] | 696 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 697 | 7. Generic subsystem callbacks |
| 698 | |
| 699 | Subsystems may wish to conserve code space by using the set of generic power |
| 700 | management callbacks provided by the PM core, defined in |
| 701 | driver/base/power/generic_ops.c: |
| 702 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 703 | int pm_generic_runtime_suspend(struct device *dev); |
| 704 | - invoke the ->runtime_suspend() callback provided by the driver of this |
Geert Uytterhoeven | 39c29f3 | 2014-03-24 21:31:29 +0100 | [diff] [blame] | 705 | device and return its result, or return 0 if not defined |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 706 | |
| 707 | int pm_generic_runtime_resume(struct device *dev); |
| 708 | - invoke the ->runtime_resume() callback provided by the driver of this |
Geert Uytterhoeven | 39c29f3 | 2014-03-24 21:31:29 +0100 | [diff] [blame] | 709 | device and return its result, or return 0 if not defined |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 710 | |
| 711 | int pm_generic_suspend(struct device *dev); |
| 712 | - if the device has not been suspended at run time, invoke the ->suspend() |
| 713 | callback provided by its driver and return its result, or return 0 if not |
| 714 | defined |
| 715 | |
Rafael J. Wysocki | e529192 | 2011-07-01 22:12:59 +0200 | [diff] [blame] | 716 | int pm_generic_suspend_noirq(struct device *dev); |
| 717 | - if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq() |
| 718 | callback provided by the device's driver and return its result, or return |
| 719 | 0 if not defined |
| 720 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 721 | int pm_generic_resume(struct device *dev); |
| 722 | - invoke the ->resume() callback provided by the driver of this device and, |
| 723 | if successful, change the device's runtime PM status to 'active' |
| 724 | |
Rafael J. Wysocki | e529192 | 2011-07-01 22:12:59 +0200 | [diff] [blame] | 725 | int pm_generic_resume_noirq(struct device *dev); |
| 726 | - invoke the ->resume_noirq() callback provided by the driver of this device |
| 727 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 728 | int pm_generic_freeze(struct device *dev); |
| 729 | - if the device has not been suspended at run time, invoke the ->freeze() |
| 730 | callback provided by its driver and return its result, or return 0 if not |
| 731 | defined |
| 732 | |
Rafael J. Wysocki | e529192 | 2011-07-01 22:12:59 +0200 | [diff] [blame] | 733 | int pm_generic_freeze_noirq(struct device *dev); |
| 734 | - if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq() |
| 735 | callback provided by the device's driver and return its result, or return |
| 736 | 0 if not defined |
| 737 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 738 | int pm_generic_thaw(struct device *dev); |
| 739 | - if the device has not been suspended at run time, invoke the ->thaw() |
| 740 | callback provided by its driver and return its result, or return 0 if not |
| 741 | defined |
| 742 | |
Rafael J. Wysocki | e529192 | 2011-07-01 22:12:59 +0200 | [diff] [blame] | 743 | int pm_generic_thaw_noirq(struct device *dev); |
| 744 | - if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq() |
| 745 | callback provided by the device's driver and return its result, or return |
| 746 | 0 if not defined |
| 747 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 748 | int pm_generic_poweroff(struct device *dev); |
| 749 | - if the device has not been suspended at run time, invoke the ->poweroff() |
| 750 | callback provided by its driver and return its result, or return 0 if not |
| 751 | defined |
| 752 | |
Rafael J. Wysocki | e529192 | 2011-07-01 22:12:59 +0200 | [diff] [blame] | 753 | int pm_generic_poweroff_noirq(struct device *dev); |
| 754 | - if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq() |
| 755 | callback provided by the device's driver and return its result, or return |
| 756 | 0 if not defined |
| 757 | |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 758 | int pm_generic_restore(struct device *dev); |
| 759 | - invoke the ->restore() callback provided by the driver of this device and, |
| 760 | if successful, change the device's runtime PM status to 'active' |
| 761 | |
Rafael J. Wysocki | e529192 | 2011-07-01 22:12:59 +0200 | [diff] [blame] | 762 | int pm_generic_restore_noirq(struct device *dev); |
| 763 | - invoke the ->restore_noirq() callback provided by the device's driver |
| 764 | |
Geert Uytterhoeven | fd6fe82 | 2014-03-24 21:31:30 +0100 | [diff] [blame] | 765 | These functions are the defaults used by the PM core, if a subsystem doesn't |
| 766 | provide its own callbacks for ->runtime_idle(), ->runtime_suspend(), |
Rafael J. Wysocki | e529192 | 2011-07-01 22:12:59 +0200 | [diff] [blame] | 767 | ->runtime_resume(), ->suspend(), ->suspend_noirq(), ->resume(), |
| 768 | ->resume_noirq(), ->freeze(), ->freeze_noirq(), ->thaw(), ->thaw_noirq(), |
Geert Uytterhoeven | fd6fe82 | 2014-03-24 21:31:30 +0100 | [diff] [blame] | 769 | ->poweroff(), ->poweroff_noirq(), ->restore(), ->restore_noirq() in the |
| 770 | subsystem-level dev_pm_ops structure. |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 771 | |
| 772 | Device drivers that wish to use the same function as a system suspend, freeze, |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 773 | poweroff and runtime suspend callback, and similarly for system resume, thaw, |
| 774 | restore, and runtime resume, can achieve this with the help of the |
Rafael J. Wysocki | d690b2c | 2010-03-06 21:28:37 +0100 | [diff] [blame] | 775 | UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its |
| 776 | last argument to NULL). |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 777 | |
| 778 | 8. "No-Callback" Devices |
| 779 | |
| 780 | Some "devices" are only logical sub-devices of their parent and cannot be |
| 781 | power-managed on their own. (The prototype example is a USB interface. Entire |
| 782 | USB devices can go into low-power mode or send wake-up requests, but neither is |
| 783 | possible for individual interfaces.) The drivers for these devices have no |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 784 | need of runtime PM callbacks; if the callbacks did exist, ->runtime_suspend() |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 785 | and ->runtime_resume() would always return 0 without doing anything else and |
| 786 | ->runtime_idle() would always call pm_runtime_suspend(). |
| 787 | |
| 788 | Subsystems can tell the PM core about these devices by calling |
| 789 | pm_runtime_no_callbacks(). This should be done after the device structure is |
| 790 | initialized and before it is registered (although after device registration is |
| 791 | also okay). The routine will set the device's power.no_callbacks flag and |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 792 | prevent the non-debugging runtime PM sysfs attributes from being created. |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 793 | |
| 794 | When power.no_callbacks is set, the PM core will not invoke the |
| 795 | ->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks. |
| 796 | Instead it will assume that suspends and resumes always succeed and that idle |
| 797 | devices should be suspended. |
| 798 | |
| 799 | As a consequence, the PM core will never directly inform the device's subsystem |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 800 | or driver about runtime power changes. Instead, the driver for the device's |
Alan Stern | 7490e44 | 2010-09-25 23:35:15 +0200 | [diff] [blame] | 801 | parent must take responsibility for telling the device's driver when the |
| 802 | parent's power state changes. |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 803 | |
| 804 | 9. Autosuspend, or automatically-delayed suspends |
| 805 | |
| 806 | Changing a device's power state isn't free; it requires both time and energy. |
| 807 | A device should be put in a low-power state only when there's some reason to |
| 808 | think it will remain in that state for a substantial time. A common heuristic |
| 809 | says that a device which hasn't been used for a while is liable to remain |
| 810 | unused; following this advice, drivers should not allow devices to be suspended |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 811 | at runtime until they have been inactive for some minimum period. Even when |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 812 | the heuristic ends up being non-optimal, it will still prevent devices from |
| 813 | "bouncing" too rapidly between low-power and full-power states. |
| 814 | |
| 815 | The term "autosuspend" is an historical remnant. It doesn't mean that the |
| 816 | device is automatically suspended (the subsystem or driver still has to call |
Rafael J. Wysocki | 62052ab | 2011-07-06 10:52:13 +0200 | [diff] [blame] | 817 | the appropriate PM routines); rather it means that runtime suspends will |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 818 | automatically be delayed until the desired period of inactivity has elapsed. |
| 819 | |
| 820 | Inactivity is determined based on the power.last_busy field. Drivers should |
| 821 | call pm_runtime_mark_last_busy() to update this field after carrying out I/O, |
| 822 | typically just before calling pm_runtime_put_autosuspend(). The desired length |
| 823 | of the inactivity period is a matter of policy. Subsystems can set this length |
| 824 | initially by calling pm_runtime_set_autosuspend_delay(), but after device |
| 825 | registration the length should be controlled by user space, using the |
| 826 | /sys/devices/.../power/autosuspend_delay_ms attribute. |
| 827 | |
| 828 | In order to use autosuspend, subsystems or drivers must call |
| 829 | pm_runtime_use_autosuspend() (preferably before registering the device), and |
| 830 | thereafter they should use the various *_autosuspend() helper functions instead |
| 831 | of the non-autosuspend counterparts: |
| 832 | |
| 833 | Instead of: pm_runtime_suspend use: pm_runtime_autosuspend; |
| 834 | Instead of: pm_schedule_suspend use: pm_request_autosuspend; |
| 835 | Instead of: pm_runtime_put use: pm_runtime_put_autosuspend; |
| 836 | Instead of: pm_runtime_put_sync use: pm_runtime_put_sync_autosuspend. |
| 837 | |
| 838 | Drivers may also continue to use the non-autosuspend helper functions; they |
| 839 | will behave normally, not taking the autosuspend delay into account. |
| 840 | Similarly, if the power.use_autosuspend field isn't set then the autosuspend |
| 841 | helper functions will behave just like the non-autosuspend counterparts. |
| 842 | |
Alan Stern | 886486b | 2011-11-03 23:39:18 +0100 | [diff] [blame] | 843 | Under some circumstances a driver or subsystem may want to prevent a device |
| 844 | from autosuspending immediately, even though the usage counter is zero and the |
| 845 | autosuspend delay time has expired. If the ->runtime_suspend() callback |
| 846 | returns -EAGAIN or -EBUSY, and if the next autosuspend delay expiration time is |
| 847 | in the future (as it normally would be if the callback invoked |
| 848 | pm_runtime_mark_last_busy()), the PM core will automatically reschedule the |
| 849 | autosuspend. The ->runtime_suspend() callback can't do this rescheduling |
| 850 | itself because no suspend requests of any kind are accepted while the device is |
| 851 | suspending (i.e., while the callback is running). |
| 852 | |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 853 | The implementation is well suited for asynchronous use in interrupt contexts. |
| 854 | However such use inevitably involves races, because the PM core can't |
| 855 | synchronize ->runtime_suspend() callbacks with the arrival of I/O requests. |
| 856 | This synchronization must be handled by the driver, using its private lock. |
| 857 | Here is a schematic pseudo-code example: |
| 858 | |
| 859 | foo_read_or_write(struct foo_priv *foo, void *data) |
| 860 | { |
| 861 | lock(&foo->private_lock); |
| 862 | add_request_to_io_queue(foo, data); |
| 863 | if (foo->num_pending_requests++ == 0) |
| 864 | pm_runtime_get(&foo->dev); |
| 865 | if (!foo->is_suspended) |
| 866 | foo_process_next_request(foo); |
| 867 | unlock(&foo->private_lock); |
| 868 | } |
| 869 | |
| 870 | foo_io_completion(struct foo_priv *foo, void *req) |
| 871 | { |
| 872 | lock(&foo->private_lock); |
| 873 | if (--foo->num_pending_requests == 0) { |
| 874 | pm_runtime_mark_last_busy(&foo->dev); |
| 875 | pm_runtime_put_autosuspend(&foo->dev); |
| 876 | } else { |
| 877 | foo_process_next_request(foo); |
| 878 | } |
| 879 | unlock(&foo->private_lock); |
| 880 | /* Send req result back to the user ... */ |
| 881 | } |
| 882 | |
| 883 | int foo_runtime_suspend(struct device *dev) |
| 884 | { |
| 885 | struct foo_priv foo = container_of(dev, ...); |
| 886 | int ret = 0; |
| 887 | |
| 888 | lock(&foo->private_lock); |
| 889 | if (foo->num_pending_requests > 0) { |
| 890 | ret = -EBUSY; |
| 891 | } else { |
| 892 | /* ... suspend the device ... */ |
| 893 | foo->is_suspended = 1; |
| 894 | } |
| 895 | unlock(&foo->private_lock); |
| 896 | return ret; |
| 897 | } |
| 898 | |
| 899 | int foo_runtime_resume(struct device *dev) |
| 900 | { |
| 901 | struct foo_priv foo = container_of(dev, ...); |
| 902 | |
| 903 | lock(&foo->private_lock); |
| 904 | /* ... resume the device ... */ |
| 905 | foo->is_suspended = 0; |
| 906 | pm_runtime_mark_last_busy(&foo->dev); |
| 907 | if (foo->num_pending_requests > 0) |
Geert Uytterhoeven | fe98245 | 2014-03-24 21:31:31 +0100 | [diff] [blame] | 908 | foo_process_next_request(foo); |
Alan Stern | 15bcb91d | 2010-09-25 23:35:21 +0200 | [diff] [blame] | 909 | unlock(&foo->private_lock); |
| 910 | return 0; |
| 911 | } |
| 912 | |
| 913 | The important point is that after foo_io_completion() asks for an autosuspend, |
| 914 | the foo_runtime_suspend() callback may race with foo_read_or_write(). |
| 915 | Therefore foo_runtime_suspend() has to check whether there are any pending I/O |
| 916 | requests (while holding the private lock) before allowing the suspend to |
| 917 | proceed. |
| 918 | |
| 919 | In addition, the power.autosuspend_delay field can be changed by user space at |
| 920 | any time. If a driver cares about this, it can call |
| 921 | pm_runtime_autosuspend_expiration() from within the ->runtime_suspend() |
| 922 | callback while holding its private lock. If the function returns a nonzero |
| 923 | value then the delay has not yet expired and the callback should return |
| 924 | -EAGAIN. |