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 - if set, indicates that the user space has allowed the device driver to
270 power manage the device at run time via the /sys/devices/.../power/control
275 - indicates that the device does not use the runtime PM callbacks (see
284 - indicates that the device's driver supports delayed autosuspend (see
297 function was last called for this device; used in calculating inactivity
300 All of the above fields are members of the 'power' member of 'struct device'.
302 4. Runtime PM Device Helper Functions
308 `void pm_runtime_init(struct device *dev);`
309 - initialize the device runtime PM fields in 'struct dev_pm_info'
311 `void pm_runtime_remove(struct device *dev);`
312 - make sure that the runtime PM of the device will be disabled after
313 removing the device from device hierarchy
315 `int pm_runtime_idle(struct device *dev);`
316 - execute the subsystem-level idle callback for the device; returns an
321 `int pm_runtime_suspend(struct device *dev);`
322 - execute the subsystem-level suspend callback for the device; returns 0 on
323 success, 1 if the device's runtime PM status was already 'suspended', or
325 to suspend the device again in future and -EACCES means that
328 `int pm_runtime_autosuspend(struct device *dev);`
334 `int pm_runtime_resume(struct device *dev);`
335 - execute the subsystem-level resume callback for the device; returns 0 on
336 success, 1 if the device's runtime PM status was already 'active' or
338 resume the device again in future, but 'power.runtime_error' should be
342 `int pm_request_idle(struct device *dev);`
344 device (the request is represented by a work item in pm_wq); returns 0 on
347 `int pm_request_autosuspend(struct device *dev);`
349 device when the autosuspend delay has expired; if the delay has already
352 `int pm_schedule_suspend(struct device *dev, unsigned int delay);`
354 device in future, where 'delay' is the time to wait before queuing up a
356 item is queued up immediately); returns 0 on success, 1 if the device's PM
362 `int pm_request_resume(struct device *dev);`
364 device (the request is represented by a work item in pm_wq); returns 0 on
365 success, 1 if the device's runtime PM status was already 'active', or
368 `void pm_runtime_get_noresume(struct device *dev);`
369 - increment the device's usage counter
371 `int pm_runtime_get(struct device *dev);`
372 - increment the device's usage counter, run pm_request_resume(dev) and
375 `int pm_runtime_get_sync(struct device *dev);`
376 - increment the device's usage counter, run pm_runtime_resume(dev) and
379 `int pm_runtime_get_if_in_use(struct device *dev);`
385 `int pm_runtime_get_if_active(struct device *dev, bool ign_usage_count);`
388 or the device's usage_count is non-zero, increment the counter and
391 `void pm_runtime_put_noidle(struct device *dev);`
392 - decrement the device's usage counter
394 `int pm_runtime_put(struct device *dev);`
395 - decrement the device's usage counter; if the result is 0 then run
398 `int pm_runtime_put_autosuspend(struct device *dev);`
399 - decrement the device's usage counter; if the result is 0 then run
402 `int pm_runtime_put_sync(struct device *dev);`
403 - decrement the device's usage counter; if the result is 0 then run
406 `int pm_runtime_put_sync_suspend(struct device *dev);`
407 - decrement the device's usage counter; if the result is 0 then run
410 `int pm_runtime_put_sync_autosuspend(struct device *dev);`
411 - decrement the device's usage counter; if the result is 0 then run
414 `void pm_runtime_enable(struct device *dev);`
415 - decrement the device's 'power.disable_depth' field; if that field is equal
417 callbacks described in Section 2 for the device
419 `int pm_runtime_disable(struct device *dev);`
420 - increment the device's 'power.disable_depth' field (if the value of that
422 callbacks from being run for the device), make sure that all of the
423 pending runtime PM operations on the device are either completed or
425 necessary to execute the subsystem-level resume callback for the device
428 `int pm_runtime_barrier(struct device *dev);`
429 - check if there's a resume request pending for the device and resume it
433 necessary to execute the subsystem-level resume callback for the device to
436 `void pm_suspend_ignore_children(struct device *dev, bool enable);`
437 - set/unset the power.ignore_children flag of the device
439 `int pm_runtime_set_active(struct device *dev);`
440 - clear the device's 'power.runtime_error' flag, set the device's runtime
444 zero); it will fail and return error code if the device has a parent
447 `void pm_runtime_set_suspended(struct device *dev);`
448 - clear the device's 'power.runtime_error' flag, set the device's runtime
454 `bool pm_runtime_active(struct device *dev);`
455 - return true if the device's runtime PM status is 'active' or its
458 `bool pm_runtime_suspended(struct device *dev);`
459 - return true if the device's runtime PM status is 'suspended' and its
462 `bool pm_runtime_status_suspended(struct device *dev);`
463 - return true if the device's runtime PM status is 'suspended'
465 `void pm_runtime_allow(struct device *dev);`
466 - set the power.runtime_auto flag for the device and decrease its usage
468 effectively allow the device to be power managed at run time)
470 `void pm_runtime_forbid(struct device *dev);`
471 - unset the power.runtime_auto flag for the device and increase its usage
473 effectively prevent the device from being power managed at run time)
475 `void pm_runtime_no_callbacks(struct device *dev);`
476 - set the power.no_callbacks flag for the device and remove the runtime
478 added when the device is registered)
480 `void pm_runtime_irq_safe(struct device *dev);`
481 - set the power.irq_safe flag for the device, causing the runtime-PM
484 `bool pm_runtime_is_irq_safe(struct device *dev);`
485 - return true if power.irq_safe flag was set for the device, causing
488 `void pm_runtime_mark_last_busy(struct device *dev);`
491 `void pm_runtime_use_autosuspend(struct device *dev);`
496 `void pm_runtime_dont_use_autosuspend(struct device *dev);`
498 decrement the device's usage counter if the flag was previously set and
501 `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
505 called or the device's usage counter may be decremented and
510 `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
537 If pm_runtime_irq_safe() has been called for a device then the following helper
549 5. Runtime PM Initialization, Device Probing and Removal
554 -EAGAIN until pm_runtime_enable() is called for the device.
557 'suspended', but it need not reflect the actual physical state of the device.
558 Thus, if the device is initially active (i.e. it is able to process I/O), its
560 pm_runtime_set_active(), before pm_runtime_enable() is called for the device.
562 However, if the device has a parent and the parent's runtime PM is enabled,
563 calling pm_runtime_set_active() for the device will affect the parent, unless
569 once pm_runtime_set_active() has been called for the device, pm_runtime_enable()
574 If the default initial runtime PM status of the device (i.e. 'suspended')
575 reflects the actual state of the device, its bus type's or its driver's
578 should be used. Of course, for this purpose the device's runtime PM has to be
581 Note, if the device may execute pm_runtime calls during the probe (such as
584 appropriate to ensure that the device is not put back to sleep during the
585 probe. This can happen with systems such as the network device layer.
587 It may be desirable to suspend the device once ->probe() has finished.
589 request to execute the subsystem-level idle callback for the device at that
598 resumes the device if it's in the suspended state and prevents it from
613 The user space can effectively disallow the driver of the device to power manage
617 runtime power management of the device until the user space turns it on.
619 status of the device is 'active' and call pm_runtime_forbid(). It should be
622 manage the device at run time, the driver may confuse it by using
630 ways. If a device is active when a system sleep starts, everything is
631 straightforward. But what should happen if the device is already suspended?
633 The device may have different wake-up settings for runtime PM and system sleep.
637 device's wake-up setting (it may leave that to the device driver's system
638 suspend routine). It may be necessary to resume the device and suspend it again
646 * The device might need to switch power levels, wake-up settings, etc.
650 * The device's children may need the device to be at full power in order
653 * The driver's idea of the device state may not agree with the device's
656 * The device might need to be reset.
658 * Even though the device was suspended, if its usage counter was > 0 then most
661 If the device had been suspended before the system suspend began and it's
690 different levels of device hierarchy. Namely, if a system suspend .prepare()
691 callback returns a positive number for a device, that indicates to the PM core
692 that the device appears to be runtime-suspended and its state is fine, so it
696 complete callback, which is then entirely responsible for handling the device
705 * During system suspend pm_runtime_get_noresume() is called for every device
707 pm_runtime_barrier() is called for every device right before executing the
710 device right before executing the subsystem-level .suspend_late() callback
714 every device right after executing the subsystem-level .resume_early()
724 `int pm_generic_runtime_suspend(struct device *dev);`
726 device and return its result, or return 0 if not defined
728 `int pm_generic_runtime_resume(struct device *dev);`
730 device and return its result, or return 0 if not defined
732 `int pm_generic_suspend(struct device *dev);`
733 - if the device has not been suspended at run time, invoke the ->suspend()
737 `int pm_generic_suspend_noirq(struct device *dev);`
739 callback provided by the device's driver and return its result, or return
742 `int pm_generic_resume(struct device *dev);`
743 - invoke the ->resume() callback provided by the driver of this device and,
744 if successful, change the device's runtime PM status to 'active'
746 `int pm_generic_resume_noirq(struct device *dev);`
747 - invoke the ->resume_noirq() callback provided by the driver of this device
749 `int pm_generic_freeze(struct device *dev);`
750 - if the device has not been suspended at run time, invoke the ->freeze()
754 `int pm_generic_freeze_noirq(struct device *dev);`
756 callback provided by the device's driver and return its result, or return
759 `int pm_generic_thaw(struct device *dev);`
760 - if the device has not been suspended at run time, invoke the ->thaw()
764 `int pm_generic_thaw_noirq(struct device *dev);`
766 callback provided by the device's driver and return its result, or return
769 `int pm_generic_poweroff(struct device *dev);`
770 - if the device has not been suspended at run time, invoke the ->poweroff()
774 `int pm_generic_poweroff_noirq(struct device *dev);`
776 callback provided by the device's driver and return its result, or return
779 `int pm_generic_restore(struct device *dev);`
780 - invoke the ->restore() callback provided by the driver of this device and,
781 if successful, change the device's runtime PM status to 'active'
783 `int pm_generic_restore_noirq(struct device *dev);`
784 - invoke the ->restore_noirq() callback provided by the device's driver
793 Device drivers that wish to use the same function as a system suspend, freeze,
811 pm_runtime_no_callbacks(). This should be done after the device structure is
812 initialized and before it is registered (although after device registration is
813 also okay). The routine will set the device's power.no_callbacks flag and
821 As a consequence, the PM core will never directly inform the device's subsystem
822 or driver about runtime power changes. Instead, the driver for the device's
823 parent must take responsibility for telling the device's driver when the
829 Changing a device's power state isn't free; it requires both time and energy.
830 A device should be put in a low-power state only when there's some reason to
832 says that a device which hasn't been used for a while is liable to remain
839 device is automatically suspended (the subsystem or driver still has to call
847 initially by calling pm_runtime_set_autosuspend_delay(), but after device
852 pm_runtime_use_autosuspend() (preferably before registering the device), and
865 Under some circumstances a driver or subsystem may want to prevent a device
872 itself because no suspend requests of any kind are accepted while the device is
905 int foo_runtime_suspend(struct device *dev)
914 /* ... suspend the device ... */
921 int foo_runtime_resume(struct device *dev)
926 /* ... resume the device ... */