Lines Matching full:device
17 * The power management workqueue pm_wq in which bus types and device drivers can
24 * A number of runtime PM fields in the 'power' member of 'struct device' (which
28 * Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in
34 device drivers are encouraged to use these functions.
36 The runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM
40 2. Device Runtime PM Callbacks
43 There are three device runtime PM callbacks defined in 'struct dev_pm_ops'::
47 int (*runtime_suspend)(struct device *dev);
48 int (*runtime_resume)(struct device *dev);
49 int (*runtime_idle)(struct device *dev);
54 are executed by the PM core for the device's subsystem that may be either of
57 1. PM domain of the device, if the device's PM domain object, dev->pm_domain,
60 2. Device type of the device, if both dev->type and dev->type->pm are present.
62 3. Device class of the device, if both dev->class and dev->class->pm are
65 4. Bus type of the device, if both dev->bus and dev->bus->pm are present.
72 priority order of callbacks from high to low is: PM domain, device type, class
74 a low-priority one. The PM domain, bus type, device type and class callbacks
80 and ->runtime_idle() callbacks for the given device in atomic context with
83 listed at the end of Section 4 may be used for that device within an interrupt
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
90 callback in a device driver as long as the subsystem-level suspend callback
91 knows what to do to handle the device).
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
97 device will not process data and will not communicate with the CPU(s) and
99 PM status of a device after successful execution of the suspend callback is
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
108 the helper functions described in Section 4 for the device until its status
113 mechanism allowing the device to request a change of its power state, such as
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
118 that remote wakeup will be enabled for the device. Generally, remote wakeup
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
125 callback in a device driver as long as the subsystem-level resume callback knows
126 what to do to handle the device).
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
136 4 for the device, until its status is directly set to either 'active', or
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.
148 idle callback with the device as its argument.
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,
158 device last busy mark, pm_runtime_mark_last_busy(), to control the delay under
165 one device:
169 instance of ->runtime_suspend() for the same device) with the exception that
172 of the other callbacks is being executed for the same device).
179 (3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device
192 to execute it, ->runtime_idle() will not be executed for the same device.
196 device.
199 to execute it, the other callbacks will not be executed for the same device.
202 scheduled requests to execute the other callbacks for the same device,
205 3. Runtime PM Device Fields
208 The following device runtime PM fields are present in 'struct dev_pm_info', as
230 - the usage counter of the device
233 - the count of 'active' children of the device
260 being executed for that device and it is not practical to wait for the
264 - the runtime PM status of the device; this field's initial value is
265 RPM_SUSPENDED, which means that each device is initially regarded by the
269 - the last runtime PM status of the device captured before disabling runtime
273 - if set, indicates that the user space has allowed the device driver to
274 power manage the device at run time via the /sys/devices/.../power/control
279 - indicates that the device does not use the runtime PM callbacks (see
288 - indicates that the device's driver supports delayed autosuspend (see
301 function was last called for this device; used in calculating inactivity
304 All of the above fields are members of the 'power' member of 'struct device'.
306 4. Runtime PM Device Helper Functions
312 `void pm_runtime_init(struct device *dev);`
313 - initialize the device runtime PM fields in 'struct dev_pm_info'
315 `void pm_runtime_remove(struct device *dev);`
316 - make sure that the runtime PM of the device will be disabled after
317 removing the device from device hierarchy
319 `int pm_runtime_idle(struct device *dev);`
320 - execute the subsystem-level idle callback for the device; returns an
325 `int pm_runtime_suspend(struct device *dev);`
326 - execute the subsystem-level suspend callback for the device; returns 0 on
327 success, 1 if the device's runtime PM status was already 'suspended', or
329 to suspend the device again in future and -EACCES means that
332 `int pm_runtime_autosuspend(struct device *dev);`
338 `int pm_runtime_resume(struct device *dev);`
339 - execute the subsystem-level resume callback for the device; returns 0 on
340 success, 1 if the device's runtime PM status is already 'active' (also if
343 be safe to attempt to resume the device again in future, but
348 `int pm_runtime_resume_and_get(struct device *dev);`
349 - run pm_runtime_resume(dev) and if successful, increment the device's
352 `int pm_request_idle(struct device *dev);`
354 device (the request is represented by a work item in pm_wq); returns 0 on
357 `int pm_request_autosuspend(struct device *dev);`
359 device when the autosuspend delay has expired; if the delay has already
362 `int pm_schedule_suspend(struct device *dev, unsigned int delay);`
364 device in future, where 'delay' is the time to wait before queuing up a
366 item is queued up immediately); returns 0 on success, 1 if the device's PM
372 `int pm_request_resume(struct device *dev);`
374 device (the request is represented by a work item in pm_wq); returns 0 on
375 success, 1 if the device's runtime PM status was already 'active', or
378 `void pm_runtime_get_noresume(struct device *dev);`
379 - increment the device's usage counter
381 `int pm_runtime_get(struct device *dev);`
382 - increment the device's usage counter, run pm_request_resume(dev) and
385 `int pm_runtime_get_sync(struct device *dev);`
386 - increment the device's usage counter, run pm_runtime_resume(dev) and
388 note that it does not drop the device's usage counter on errors, so
393 `int pm_runtime_get_if_in_use(struct device *dev);`
399 `int pm_runtime_get_if_active(struct device *dev, bool ign_usage_count);`
402 or the device's usage_count is non-zero, increment the counter and
405 `void pm_runtime_put_noidle(struct device *dev);`
406 - decrement the device's usage counter
408 `int pm_runtime_put(struct device *dev);`
409 - decrement the device's usage counter; if the result is 0 then run
412 `int pm_runtime_put_autosuspend(struct device *dev);`
413 - decrement the device's usage counter; if the result is 0 then run
416 `int pm_runtime_put_sync(struct device *dev);`
417 - decrement the device's usage counter; if the result is 0 then run
420 `int pm_runtime_put_sync_suspend(struct device *dev);`
421 - decrement the device's usage counter; if the result is 0 then run
424 `int pm_runtime_put_sync_autosuspend(struct device *dev);`
425 - decrement the device's usage counter; if the result is 0 then run
428 `void pm_runtime_enable(struct device *dev);`
429 - decrement the device's 'power.disable_depth' field; if that field is equal
431 callbacks described in Section 2 for the device
433 `int pm_runtime_disable(struct device *dev);`
434 - increment the device's 'power.disable_depth' field (if the value of that
436 callbacks from being run for the device), make sure that all of the
437 pending runtime PM operations on the device are either completed or
439 necessary to execute the subsystem-level resume callback for the device
442 `int pm_runtime_barrier(struct device *dev);`
443 - check if there's a resume request pending for the device and resume it
447 necessary to execute the subsystem-level resume callback for the device to
450 `void pm_suspend_ignore_children(struct device *dev, bool enable);`
451 - set/unset the power.ignore_children flag of the device
453 `int pm_runtime_set_active(struct device *dev);`
454 - clear the device's 'power.runtime_error' flag, set the device's runtime
458 zero); it will fail and return error code if the device has a parent
461 `void pm_runtime_set_suspended(struct device *dev);`
462 - clear the device's 'power.runtime_error' flag, set the device's runtime
468 `bool pm_runtime_active(struct device *dev);`
469 - return true if the device's runtime PM status is 'active' or its
472 `bool pm_runtime_suspended(struct device *dev);`
473 - return true if the device's runtime PM status is 'suspended' and its
476 `bool pm_runtime_status_suspended(struct device *dev);`
477 - return true if the device's runtime PM status is 'suspended'
479 `void pm_runtime_allow(struct device *dev);`
480 - set the power.runtime_auto flag for the device and decrease its usage
482 effectively allow the device to be power managed at run time)
484 `void pm_runtime_forbid(struct device *dev);`
485 - unset the power.runtime_auto flag for the device and increase its usage
487 effectively prevent the device from being power managed at run time)
489 `void pm_runtime_no_callbacks(struct device *dev);`
490 - set the power.no_callbacks flag for the device and remove the runtime
492 added when the device is registered)
494 `void pm_runtime_irq_safe(struct device *dev);`
495 - set the power.irq_safe flag for the device, causing the runtime-PM
498 `bool pm_runtime_is_irq_safe(struct device *dev);`
499 - return true if power.irq_safe flag was set for the device, causing
502 `void pm_runtime_mark_last_busy(struct device *dev);`
505 `void pm_runtime_use_autosuspend(struct device *dev);`
510 `void pm_runtime_dont_use_autosuspend(struct device *dev);`
512 decrement the device's usage counter if the flag was previously set and
515 `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
519 called or the device's usage counter may be decremented and
524 `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
551 If pm_runtime_irq_safe() has been called for a device then the following helper
563 5. Runtime PM Initialization, Device Probing and Removal
568 -EAGAIN until pm_runtime_enable() is called for the device.
571 'suspended', but it need not reflect the actual physical state of the device.
572 Thus, if the device is initially active (i.e. it is able to process I/O), its
574 pm_runtime_set_active(), before pm_runtime_enable() is called for the device.
576 However, if the device has a parent and the parent's runtime PM is enabled,
577 calling pm_runtime_set_active() for the device will affect the parent, unless
583 once pm_runtime_set_active() has been called for the device, pm_runtime_enable()
588 If the default initial runtime PM status of the device (i.e. 'suspended')
589 reflects the actual state of the device, its bus type's or its driver's
592 should be used. Of course, for this purpose the device's runtime PM has to be
595 Note, if the device may execute pm_runtime calls during the probe (such as
598 appropriate to ensure that the device is not put back to sleep during the
599 probe. This can happen with systems such as the network device layer.
601 It may be desirable to suspend the device once ->probe() has finished.
603 request to execute the subsystem-level idle callback for the device at that
612 resumes the device if it's in the suspended state and prevents it from
627 The user space can effectively disallow the driver of the device to power manage
631 runtime power management of the device until the user space turns it on.
633 status of the device is 'active' and call pm_runtime_forbid(). It should be
636 manage the device at run time, the driver may confuse it by using
644 ways. If a device is active when a system sleep starts, everything is
645 straightforward. But what should happen if the device is already suspended?
647 The device may have different wake-up settings for runtime PM and system sleep.
651 device's wake-up setting (it may leave that to the device driver's system
652 suspend routine). It may be necessary to resume the device and suspend it again
660 * The device might need to switch power levels, wake-up settings, etc.
664 * The device's children may need the device to be at full power in order
667 * The driver's idea of the device state may not agree with the device's
670 * The device might need to be reset.
672 * Even though the device was suspended, if its usage counter was > 0 then most
675 If the device had been suspended before the system suspend began and it's
704 different levels of device hierarchy. Namely, if a system suspend .prepare()
705 callback returns a positive number for a device, that indicates to the PM core
706 that the device appears to be runtime-suspended and its state is fine, so it
710 .complete() callback, which is then entirely responsible for handling the device
719 * During system suspend pm_runtime_get_noresume() is called for every device
721 pm_runtime_barrier() is called for every device right before executing the
724 device right before executing the subsystem-level .suspend_late() callback
728 every device right after executing the subsystem-level .resume_early()
738 `int pm_generic_runtime_suspend(struct device *dev);`
740 device and return its result, or return 0 if not defined
742 `int pm_generic_runtime_resume(struct device *dev);`
744 device and return its result, or return 0 if not defined
746 `int pm_generic_suspend(struct device *dev);`
747 - if the device has not been suspended at run time, invoke the ->suspend()
751 `int pm_generic_suspend_noirq(struct device *dev);`
753 callback provided by the device's driver and return its result, or return
756 `int pm_generic_resume(struct device *dev);`
757 - invoke the ->resume() callback provided by the driver of this device and,
758 if successful, change the device's runtime PM status to 'active'
760 `int pm_generic_resume_noirq(struct device *dev);`
761 - invoke the ->resume_noirq() callback provided by the driver of this device
763 `int pm_generic_freeze(struct device *dev);`
764 - if the device has not been suspended at run time, invoke the ->freeze()
768 `int pm_generic_freeze_noirq(struct device *dev);`
770 callback provided by the device's driver and return its result, or return
773 `int pm_generic_thaw(struct device *dev);`
774 - if the device has not been suspended at run time, invoke the ->thaw()
778 `int pm_generic_thaw_noirq(struct device *dev);`
780 callback provided by the device's driver and return its result, or return
783 `int pm_generic_poweroff(struct device *dev);`
784 - if the device has not been suspended at run time, invoke the ->poweroff()
788 `int pm_generic_poweroff_noirq(struct device *dev);`
790 callback provided by the device's driver and return its result, or return
793 `int pm_generic_restore(struct device *dev);`
794 - invoke the ->restore() callback provided by the driver of this device and,
795 if successful, change the device's runtime PM status to 'active'
797 `int pm_generic_restore_noirq(struct device *dev);`
798 - invoke the ->restore_noirq() callback provided by the device's driver
807 Device drivers that wish to use the same function as a system suspend, freeze,
825 pm_runtime_no_callbacks(). This should be done after the device structure is
826 initialized and before it is registered (although after device registration is
827 also okay). The routine will set the device's power.no_callbacks flag and
835 As a consequence, the PM core will never directly inform the device's subsystem
836 or driver about runtime power changes. Instead, the driver for the device's
837 parent must take responsibility for telling the device's driver when the
843 domain could get attached to the device or that the device is power managed
844 through a supplier device link. For these reasons and to avoid boilerplate code
852 Changing a device's power state isn't free; it requires both time and energy.
853 A device should be put in a low-power state only when there's some reason to
855 says that a device which hasn't been used for a while is liable to remain
862 device is automatically suspended (the subsystem or driver still has to call
870 initially by calling pm_runtime_set_autosuspend_delay(), but after device
875 pm_runtime_use_autosuspend() (preferably before registering the device), and
888 Under some circumstances a driver or subsystem may want to prevent a device
895 itself because no suspend requests of any kind are accepted while the device is
928 int foo_runtime_suspend(struct device *dev)
937 /* ... suspend the device ... */
944 int foo_runtime_resume(struct device *dev)
949 /* ... resume the device ... */