Lines Matching +full:field +full:- +full:even +full:- +full:active
5 (C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
18 put their PM-related work items. It is strongly recommended that pm_wq be
20 them to be synchronized with system-wide power transitions (suspend to RAM,
53 The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks
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.
69 dev->driver->pm directly (if present).
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.
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
86 The subsystem-level suspend callback, if present, is _entirely_ _responsible_
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
93 * Once the subsystem-level suspend callback (or the driver suspend callback,
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
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
109 is directly set to either 'active', or 'suspended' (the PM core provides
115 device, then ->runtime_suspend() should return -EBUSY. On the other hand, if
117 low-power state during the execution of the suspend callback, it is expected
119 should be enabled for all input devices put into low-power states at run time.
121 The subsystem-level resume callback, if present, is **entirely responsible** for
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
128 * Once the subsystem-level resume callback (or the driver resume callback, if
132 'active'.
136 4 for the device, until its status is directly set to either 'active', or
140 The idle callback (a subsystem-level one, if present, or the driver one) is
143 counter of 'active' children of the device.
158 routine has started a delayed suspend), the routine must return a non-zero
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
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').
177 (3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device
179 'active' children of which is equal to zero, or the 'power.ignore_children'
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
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.
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
196 * If ->runtime_resume() is about to be executed or there's a pending request
199 * A request to execute ->runtime_resume() will cancel any pending or
210 - timer used for scheduling (delayed) suspend and autosuspend requests
213 - timer expiration time, in jiffies (if this is different from zero, the
218 - work structure used for queuing up requests (i.e. work items in pm_wq)
221 - wait queue used if any of the helper functions needs to wait for another
225 - lock used for synchronization
228 - the usage counter of the device
231 - the count of 'active' children of the device
234 - if set, the value of child_count is ignored (but still updated)
237 - used for disabling the helper functions (they work normally if this is
242 - if set, there was a fatal error (one of the callbacks returned error code
248 - if set, ->runtime_idle() is being executed
251 - if set, there's a pending request (i.e. a work item queued up into pm_wq)
254 - type of request that's pending (valid if request_pending is set)
257 - set if ->runtime_resume() is about to be run while ->runtime_suspend() is
262 - the runtime PM status of the device; this field's initial value is
267 - the last runtime PM status of the device captured before disabling runtime
271 - if set, indicates that the user space has allowed the device driver to
277 - indicates that the device does not use the runtime PM callbacks (see
282 - indicates that the ->runtime_suspend() and ->runtime_resume() callbacks
286 - indicates that the device's driver supports delayed autosuspend (see
291 - indicates that the PM core should attempt to carry out an autosuspend
295 - the delay time (in milliseconds) to be used for autosuspend
298 - the time (in jiffies) when the pm_runtime_mark_last_busy() helper
311 - initialize the device runtime PM fields in 'struct dev_pm_info'
314 - make sure that the runtime PM of the device will be disabled after
318 - execute the subsystem-level idle callback for the device; returns an
319 error code on failure, where -EINPROGRESS means that ->runtime_idle() is
324 - execute the subsystem-level suspend callback for the device; returns 0 on
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
331 - same as pm_runtime_suspend() except that a call to
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
341 'power.runtime_error' should be checked additionally, and -EACCES means
346 - run pm_runtime_resume(dev) and if successful, increment the device's
348 runtime PM status was already 'active') or the error code from
352 - submit a request to execute the subsystem-level idle callback for the
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
362 - schedule the execution of the subsystem-level suspend callback for the
368 ->runtime_suspend() is already scheduled and not yet expired, the new
372 - submit a request to execute the subsystem-level resume callback for the
374 success, 1 if the device's runtime PM status was already 'active', or
378 - increment the device's usage counter
381 - increment the device's usage counter, run pm_request_resume(dev) and
385 - increment the device's usage counter, run pm_runtime_resume(dev) and
393 - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
399 - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
404 - decrement the device's usage counter
407 - decrement the device's usage counter; if the result is 0 then run
411 - set the power.last_busy field to the current time and decrement the
416 - decrement the device's usage counter; if the result is 0 then run
420 - decrement the device's usage counter; if the result is 0 then run
424 - decrement the device's usage counter; if the result is 0 then run
428 - set the power.last_busy field to the current time and decrement the
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
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
443 necessary to execute the subsystem-level resume callback for the device
447 - check if there's a resume request pending for the device and resume it
451 necessary to execute the subsystem-level resume callback for the device to
455 - set/unset the power.ignore_children flag of the device
458 - clear the device's 'power.runtime_error' flag, set the device's runtime
459 PM status to 'active' and update its parent's counter of 'active'
463 which is not active and the 'power.ignore_children' flag of which is unset
466 - clear the device's 'power.runtime_error' flag, set the device's runtime
467 PM status to 'suspended' and update its parent's counter of 'active'
473 - return true if the device's runtime PM status is 'active' or its
474 'power.disable_depth' field is not equal to zero, or false otherwise
477 - return true if the device's runtime PM status is 'suspended' and its
478 'power.disable_depth' field is equal to zero, or false otherwise
481 - return true if the device's runtime PM status is 'suspended'
484 - set the power.runtime_auto flag for the device and decrease its usage
489 - unset the power.runtime_auto flag for the device and increase its usage
494 - set the power.no_callbacks flag for the device and remove the runtime
499 - set the power.irq_safe flag for the device, causing the runtime-PM
503 - return true if power.irq_safe flag was set for the device, causing
504 the runtime-PM callbacks to be invoked with interrupts off
507 - set the power.last_busy field to the current time
510 - set the power.use_autosuspend flag, enabling autosuspend delays; call
515 - clear the power.use_autosuspend flag, disabling autosuspend delays;
520 - set the power.autosuspend_delay value to 'delay' (expressed in
529 - calculate the time when the current autosuspend delay period will expire,
538 - pm_request_idle()
539 - pm_request_autosuspend()
540 - pm_schedule_suspend()
541 - pm_request_resume()
542 - pm_runtime_get_noresume()
543 - pm_runtime_get()
544 - pm_runtime_put_noidle()
545 - pm_runtime_put()
546 - pm_runtime_put_autosuspend()
547 - __pm_runtime_put_autosuspend()
548 - pm_runtime_enable()
549 - pm_suspend_ignore_children()
550 - pm_runtime_set_active()
551 - pm_runtime_set_suspended()
552 - pm_runtime_suspended()
553 - pm_runtime_mark_last_busy()
554 - pm_runtime_autosuspend_expiration()
559 - pm_runtime_idle()
560 - pm_runtime_suspend()
561 - pm_runtime_autosuspend()
562 - pm_runtime_resume()
563 - pm_runtime_get_sync()
564 - pm_runtime_put_sync()
565 - pm_runtime_put_sync_suspend()
566 - pm_runtime_put_sync_autosuspend()
573 -EAGAIN until pm_runtime_enable() is called for the device.
577 Thus, if the device is initially active (i.e. it is able to process I/O), its
578 runtime PM status must be changed to 'active', with the help of
585 functions, as long as the child's status is 'active', even if the child's
595 ->probe() callback will likely need to wake it up using one of the PM core's
606 It may be desirable to suspend the device once ->probe() has finished.
608 request to execute the subsystem-level idle callback for the device at that
610 update the last busy mark before returning from ->probe().
621 calling pm_runtime_suspend() from their ->remove() routines, the driver core
624 drivers to make their ->remove() callbacks avoid races with runtime PM directly,
628 Drivers in ->remove() callback should undo the runtime PM changes done
629 in ->probe(). Usually this means calling pm_runtime_disable(),
638 status of the device is 'active' and call pm_runtime_forbid(). It should be
648 as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of
649 ways. If a device is active when a system sleep starts, everything is
652 The device may have different wake-up settings for runtime PM and system sleep.
653 For example, remote wake-up may be enabled for runtime suspend but disallowed
655 the subsystem-level system suspend callback is responsible for changing the
656 device's wake-up setting (it may leave that to the device driver's system
662 power, even if they had been suspended before the system suspend began. There
665 * The device might need to switch power levels, wake-up settings, etc.
667 * Remote wake-up events might have been lost by the firmware.
677 * Even though the device was suspended, if its usage counter was > 0 then most
682 to be updated to reflect the actual post-system sleep status. The way to do
685 - pm_runtime_disable(dev);
686 - pm_runtime_set_active(dev);
687 - pm_runtime_enable(dev);
690 ->suspend() callback and decrements it after calling the ->resume() callback.
693 following the return of the ->resume() callback, the ->runtime_idle() callback
697 or hardware operation. Instead, all hardware components are put into low-power
711 that the device appears to be runtime-suspended and its state is fine, so it
717 related to hibernation (see Documentation/driver-api/pm/devices.rst for more
725 right before executing the subsystem-level .prepare() callback for it and
727 subsystem-level .suspend() callback for it. In addition to that the PM core
729 device right before executing the subsystem-level .suspend_late() callback
733 every device right after executing the subsystem-level .resume_early()
734 callback and right after executing the subsystem-level .complete() callback
745 - invoke the ->runtime_suspend() callback provided by the driver of this
749 - invoke the ->runtime_resume() callback provided by the driver of this
753 - if the device has not been suspended at run time, invoke the ->suspend()
758 - if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq()
763 - invoke the ->resume() callback provided by the driver of this device and,
764 if successful, change the device's runtime PM status to 'active'
767 - invoke the ->resume_noirq() callback provided by the driver of this device
770 - if the device has not been suspended at run time, invoke the ->freeze()
775 - if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq()
780 - if the device has not been suspended at run time, invoke the ->thaw()
785 - if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq()
790 - if the device has not been suspended at run time, invoke the ->poweroff()
795 - if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq()
800 - invoke the ->restore() callback provided by the driver of this device and,
801 if successful, change the device's runtime PM status to 'active'
804 - invoke the ->restore_noirq() callback provided by the device's driver
807 provide its own callbacks for ->runtime_idle(), ->runtime_suspend(),
808 ->runtime_resume(), ->suspend(), ->suspend_noirq(), ->resume(),
809 ->resume_noirq(), ->freeze(), ->freeze_noirq(), ->thaw(), ->thaw_noirq(),
810 ->poweroff(), ->poweroff_noirq(), ->restore(), ->restore_noirq() in the
811 subsystem-level dev_pm_ops structure.
819 8. "No-Callback" Devices
822 Some "devices" are only logical sub-devices of their parent and cannot be
823 power-managed on their own. (The prototype example is a USB interface. Entire
824 USB devices can go into low-power mode or send wake-up requests, but neither is
826 need of runtime PM callbacks; if the callbacks did exist, ->runtime_suspend()
827 and ->runtime_resume() would always return 0 without doing anything else and
828 ->runtime_idle() would always call pm_runtime_suspend().
834 prevent the non-debugging runtime PM sysfs attributes from being created.
837 ->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks.
855 9. Autosuspend, or automatically-delayed suspends
859 A device should be put in a low-power state only when there's some reason to
863 at runtime until they have been inactive for some minimum period. Even when
864 the heuristic ends up being non-optimal, it will still prevent devices from
865 "bouncing" too rapidly between low-power and full-power states.
872 Inactivity is determined based on the power.last_busy field. The desired length
881 instead of the non-autosuspend counterparts::
888 Drivers may also continue to use the non-autosuspend helper functions; they
894 from autosuspending immediately, even though the usage counter is zero and the
895 autosuspend delay time has expired. If the ->runtime_suspend() callback
896 returns -EAGAIN or -EBUSY, and if the next autosuspend delay expiration time is
899 autosuspend. The ->runtime_suspend() callback can't do this rescheduling
905 synchronize ->runtime_suspend() callbacks with the arrival of I/O requests.
907 Here is a schematic pseudo-code example::
911 lock(&foo->private_lock);
913 if (foo->num_pending_requests++ == 0)
914 pm_runtime_get(&foo->dev);
915 if (!foo->is_suspended)
917 unlock(&foo->private_lock);
922 lock(&foo->private_lock);
923 if (--foo->num_pending_requests == 0)
924 pm_runtime_put_autosuspend(&foo->dev);
927 unlock(&foo->private_lock);
936 lock(&foo->private_lock);
937 if (foo->num_pending_requests > 0) {
938 ret = -EBUSY;
941 foo->is_suspended = 1;
943 unlock(&foo->private_lock);
951 lock(&foo->private_lock);
953 foo->is_suspended = 0;
954 pm_runtime_mark_last_busy(&foo->dev);
955 if (foo->num_pending_requests > 0)
957 unlock(&foo->private_lock);
967 In addition, the power.autosuspend_delay field can be changed by user space at
969 pm_runtime_autosuspend_expiration() from within the ->runtime_suspend()
972 -EAGAIN.