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