mirror of
https://github.com/torvalds/linux.git
synced 2026-11-07 06:17:02 +01:00
PM: runtime: Pull API docs from kerneldoc
This avoids staleness and duplication, as the same APIs were previously documented twice. Signed-off-by: Brian Norris <briannorris@chromium.org> Link: https://patch.msgid.link/20260904141215.4.I2cb2c43192ef46bd9dfad6699080d8a1d56756d5@changeid Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
This commit is contained in:
Brian Norris
Rafael J. Wysocki
parent
3baf1652fd
commit
3d6174fe30
|
|
@ -307,219 +307,10 @@ All of the above fields are members of the 'power' member of 'struct device'.
|
|||
The following runtime PM helper functions are defined in
|
||||
drivers/base/power/runtime.c and include/linux/pm_runtime.h:
|
||||
|
||||
`void pm_runtime_init(struct device *dev);`
|
||||
- initialize the device runtime PM fields in 'struct dev_pm_info'
|
||||
.. kernel-doc:: drivers/base/power/runtime.c
|
||||
:export:
|
||||
|
||||
`void pm_runtime_remove(struct device *dev);`
|
||||
- make sure that the runtime PM of the device will be disabled after
|
||||
removing the device from device hierarchy
|
||||
|
||||
`int pm_runtime_idle(struct device *dev);`
|
||||
- execute the subsystem-level idle callback for the device; returns an
|
||||
error code on failure, where -EINPROGRESS means that ->runtime_idle() is
|
||||
already being executed; if there is no callback or the callback returns 0
|
||||
then run pm_runtime_autosuspend(dev) and return its result
|
||||
|
||||
`int pm_runtime_suspend(struct device *dev);`
|
||||
- execute the subsystem-level suspend callback for the device; returns 0 on
|
||||
success, 1 if the device's runtime PM status was already 'suspended', or
|
||||
error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt
|
||||
to suspend the device again in future and -EACCES means that
|
||||
'power.disable_depth' is different from 0
|
||||
|
||||
`int pm_runtime_autosuspend(struct device *dev);`
|
||||
- same as pm_runtime_suspend() except that a call to
|
||||
pm_runtime_mark_last_busy() is made and an autosuspend is scheduled for
|
||||
the appropriate time and 0 is returned
|
||||
|
||||
`int pm_runtime_resume(struct device *dev);`
|
||||
- execute the subsystem-level resume callback for the device; returns 0 on
|
||||
success, 1 if the device's runtime PM status is already 'active' (also if
|
||||
'power.disable_depth' is nonzero, but the status was 'active' when it was
|
||||
changing from 0 to 1) or error code on failure, where -EAGAIN means it may
|
||||
be safe to attempt to resume the device again in future, but
|
||||
'power.runtime_error' should be checked additionally, and -EACCES means
|
||||
that the callback could not be run, because 'power.disable_depth' was
|
||||
different from 0
|
||||
|
||||
`int pm_runtime_resume_and_get(struct device *dev);`
|
||||
- run pm_runtime_resume(dev) and if successful, increment the device's
|
||||
usage counter; returns 0 on success (whether or not the device's
|
||||
runtime PM status was already 'active') or the error code from
|
||||
pm_runtime_resume() on failure.
|
||||
|
||||
`int pm_request_idle(struct device *dev);`
|
||||
- submit a request to execute the subsystem-level idle callback for the
|
||||
device (the request is represented by a work item in pm_wq); returns 0 on
|
||||
success or error code if the request has not been queued up
|
||||
|
||||
`int pm_request_autosuspend(struct device *dev);`
|
||||
- Call pm_runtime_mark_last_busy() and schedule the execution of the
|
||||
subsystem-level suspend callback for the device when the autosuspend delay
|
||||
expires
|
||||
|
||||
`int pm_schedule_suspend(struct device *dev, unsigned int delay);`
|
||||
- schedule the execution of the subsystem-level suspend callback for the
|
||||
device in future, where 'delay' is the time to wait before queuing up a
|
||||
suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work
|
||||
item is queued up immediately); returns 0 on success, 1 if the device's PM
|
||||
runtime status was already 'suspended', or error code if the request
|
||||
hasn't been scheduled (or queued up if 'delay' is 0); if the execution of
|
||||
->runtime_suspend() is already scheduled and not yet expired, the new
|
||||
value of 'delay' will be used as the time to wait
|
||||
|
||||
`int pm_request_resume(struct device *dev);`
|
||||
- submit a request to execute the subsystem-level resume callback for the
|
||||
device (the request is represented by a work item in pm_wq); returns 0 on
|
||||
success, 1 if the device's runtime PM status was already 'active', or
|
||||
error code if the request hasn't been queued up
|
||||
|
||||
`void pm_runtime_get_noresume(struct device *dev);`
|
||||
- increment the device's usage counter
|
||||
|
||||
`int pm_runtime_get(struct device *dev);`
|
||||
- increment the device's usage counter, run pm_request_resume(dev) and
|
||||
return its result
|
||||
|
||||
`int pm_runtime_get_sync(struct device *dev);`
|
||||
- increment the device's usage counter, run pm_runtime_resume(dev) and
|
||||
return its result;
|
||||
note that it does not drop the device's usage counter on errors, so
|
||||
consider using pm_runtime_resume_and_get() instead of it, especially
|
||||
if its return value is checked by the caller, as this is likely to
|
||||
result in cleaner code.
|
||||
|
||||
`int pm_runtime_get_if_in_use(struct device *dev);`
|
||||
- return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
|
||||
runtime PM status is RPM_ACTIVE and the runtime PM usage counter is
|
||||
nonzero, increment the counter and return 1; otherwise return 0 without
|
||||
changing the counter
|
||||
|
||||
`int pm_runtime_get_if_active(struct device *dev);`
|
||||
- return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
|
||||
runtime PM status is RPM_ACTIVE, increment the counter and
|
||||
return 1; otherwise return 0 without changing the counter
|
||||
|
||||
`void pm_runtime_put_noidle(struct device *dev);`
|
||||
- decrement the device's usage counter
|
||||
|
||||
`int pm_runtime_put(struct device *dev);`
|
||||
- decrement the device's usage counter; if the result is 0 then run
|
||||
pm_request_idle(dev) and return its result
|
||||
|
||||
`int pm_runtime_put_autosuspend(struct device *dev);`
|
||||
- set the power.last_busy field to the current time and decrement the
|
||||
device's usage counter; if the result is 0 then run
|
||||
pm_request_autosuspend(dev) and return its result
|
||||
|
||||
`int __pm_runtime_put_autosuspend(struct device *dev);`
|
||||
- decrement the device's usage counter; if the result is 0 then run
|
||||
pm_request_autosuspend(dev) and return its result
|
||||
|
||||
`int pm_runtime_put_sync(struct device *dev);`
|
||||
- decrement the device's usage counter; if the result is 0 then run
|
||||
pm_runtime_idle(dev) and return its result
|
||||
|
||||
`int pm_runtime_put_sync_suspend(struct device *dev);`
|
||||
- decrement the device's usage counter; if the result is 0 then run
|
||||
pm_runtime_suspend(dev) and return its result
|
||||
|
||||
`int pm_runtime_put_sync_autosuspend(struct device *dev);`
|
||||
- set the power.last_busy field to the current time and decrement the
|
||||
device's usage counter; if the result is 0 then run
|
||||
pm_runtime_autosuspend(dev) and return its result
|
||||
|
||||
`void pm_runtime_enable(struct device *dev);`
|
||||
- decrement the device's 'power.disable_depth' field; if that field is equal
|
||||
to zero, the runtime PM helper functions can execute subsystem-level
|
||||
callbacks described in Section 2 for the device
|
||||
|
||||
`int pm_runtime_disable(struct device *dev);`
|
||||
- increment the device's 'power.disable_depth' field (if the value of that
|
||||
field was previously zero, this prevents subsystem-level runtime PM
|
||||
callbacks from being run for the device), make sure that all of the
|
||||
pending runtime PM operations on the device are either completed or
|
||||
canceled; returns 1 if there was a resume request pending and it was
|
||||
necessary to execute the subsystem-level resume callback for the device
|
||||
to satisfy that request, otherwise 0 is returned
|
||||
|
||||
`void pm_runtime_barrier(struct device *dev);`
|
||||
- check if there's a resume request pending for the device and resume it
|
||||
(synchronously) in that case, cancel any other pending runtime PM requests
|
||||
regarding it and wait for all runtime PM operations on it in progress to
|
||||
complete
|
||||
|
||||
`void pm_suspend_ignore_children(struct device *dev, bool enable);`
|
||||
- set/unset the power.ignore_children flag of the device
|
||||
|
||||
`int pm_runtime_set_active(struct device *dev);`
|
||||
- clear the device's 'power.runtime_error' flag, set the device's runtime
|
||||
PM status to 'active' and update its parent's counter of 'active'
|
||||
children as appropriate (it is only valid to use this function if
|
||||
'power.runtime_error' is set or 'power.disable_depth' is greater than
|
||||
zero); it will fail and return error code if the device has a parent
|
||||
which is not active and the 'power.ignore_children' flag of which is unset
|
||||
|
||||
`void pm_runtime_set_suspended(struct device *dev);`
|
||||
- clear the device's 'power.runtime_error' flag, set the device's runtime
|
||||
PM status to 'suspended' and update its parent's counter of 'active'
|
||||
children as appropriate (it is only valid to use this function if
|
||||
'power.runtime_error' is set or 'power.disable_depth' is greater than
|
||||
zero)
|
||||
|
||||
`bool pm_runtime_active(struct device *dev);`
|
||||
- return true if the device's runtime PM status is 'active' or its
|
||||
'power.disable_depth' field is not equal to zero, or false otherwise
|
||||
|
||||
`bool pm_runtime_suspended(struct device *dev);`
|
||||
- return true if the device's runtime PM status is 'suspended' and its
|
||||
'power.disable_depth' field is equal to zero, or false otherwise
|
||||
|
||||
`bool pm_runtime_status_suspended(struct device *dev);`
|
||||
- return true if the device's runtime PM status is 'suspended'
|
||||
|
||||
`void pm_runtime_no_callbacks(struct device *dev);`
|
||||
- set the power.no_callbacks flag for the device and remove the runtime
|
||||
PM attributes from /sys/devices/.../power (or prevent them from being
|
||||
added when the device is registered)
|
||||
|
||||
`void pm_runtime_irq_safe(struct device *dev);`
|
||||
- set the power.irq_safe flag for the device, causing the runtime-PM
|
||||
callbacks to be invoked with interrupts off
|
||||
|
||||
`bool pm_runtime_is_irq_safe(struct device *dev);`
|
||||
- return true if power.irq_safe flag was set for the device, causing
|
||||
the runtime-PM callbacks to be invoked with interrupts off
|
||||
|
||||
`void pm_runtime_mark_last_busy(struct device *dev);`
|
||||
- set the power.last_busy field to the current time
|
||||
|
||||
`void pm_runtime_use_autosuspend(struct device *dev);`
|
||||
- set the power.use_autosuspend flag, enabling autosuspend delays; call
|
||||
pm_runtime_get_sync if the flag was previously cleared and
|
||||
power.autosuspend_delay is negative
|
||||
|
||||
`void pm_runtime_dont_use_autosuspend(struct device *dev);`
|
||||
- clear the power.use_autosuspend flag, disabling autosuspend delays;
|
||||
decrement the device's usage counter if the flag was previously set and
|
||||
power.autosuspend_delay is negative; call pm_runtime_idle
|
||||
|
||||
`void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
|
||||
- set the power.autosuspend_delay value to 'delay' (expressed in
|
||||
milliseconds); if 'delay' is negative then runtime suspends are
|
||||
prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be
|
||||
called or the device's usage counter may be decremented and
|
||||
pm_runtime_idle called depending on if power.autosuspend_delay is
|
||||
changed to or from a negative value; if power.use_autosuspend is clear,
|
||||
pm_runtime_idle is called
|
||||
|
||||
`unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
|
||||
- calculate the time when the current autosuspend delay period will expire,
|
||||
based on power.last_busy and power.autosuspend_delay; if the delay time
|
||||
is 1000 ms or larger then the expiration time is rounded up to the
|
||||
nearest second; returns 0 if the delay period has already expired or
|
||||
power.use_autosuspend isn't set, otherwise returns the expiration time
|
||||
in jiffies
|
||||
.. kernel-doc:: include/linux/pm_runtime.h
|
||||
|
||||
It is safe to execute the following helper functions from interrupt context:
|
||||
|
||||
|
|
@ -728,67 +519,8 @@ Subsystems may wish to conserve code space by using the set of generic power
|
|||
management callbacks provided by the PM core, defined in
|
||||
driver/base/power/generic_ops.c:
|
||||
|
||||
`int pm_generic_runtime_suspend(struct device *dev);`
|
||||
- invoke the ->runtime_suspend() callback provided by the driver of this
|
||||
device and return its result, or return 0 if not defined
|
||||
|
||||
`int pm_generic_runtime_resume(struct device *dev);`
|
||||
- invoke the ->runtime_resume() callback provided by the driver of this
|
||||
device and return its result, or return 0 if not defined
|
||||
|
||||
`int pm_generic_suspend(struct device *dev);`
|
||||
- if the device has not been suspended at run time, invoke the ->suspend()
|
||||
callback provided by its driver and return its result, or return 0 if not
|
||||
defined
|
||||
|
||||
`int pm_generic_suspend_noirq(struct device *dev);`
|
||||
- if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq()
|
||||
callback provided by the device's driver and return its result, or return
|
||||
0 if not defined
|
||||
|
||||
`int pm_generic_resume(struct device *dev);`
|
||||
- invoke the ->resume() callback provided by the driver of this device and,
|
||||
if successful, change the device's runtime PM status to 'active'
|
||||
|
||||
`int pm_generic_resume_noirq(struct device *dev);`
|
||||
- invoke the ->resume_noirq() callback provided by the driver of this device
|
||||
|
||||
`int pm_generic_freeze(struct device *dev);`
|
||||
- if the device has not been suspended at run time, invoke the ->freeze()
|
||||
callback provided by its driver and return its result, or return 0 if not
|
||||
defined
|
||||
|
||||
`int pm_generic_freeze_noirq(struct device *dev);`
|
||||
- if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq()
|
||||
callback provided by the device's driver and return its result, or return
|
||||
0 if not defined
|
||||
|
||||
`int pm_generic_thaw(struct device *dev);`
|
||||
- if the device has not been suspended at run time, invoke the ->thaw()
|
||||
callback provided by its driver and return its result, or return 0 if not
|
||||
defined
|
||||
|
||||
`int pm_generic_thaw_noirq(struct device *dev);`
|
||||
- if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq()
|
||||
callback provided by the device's driver and return its result, or return
|
||||
0 if not defined
|
||||
|
||||
`int pm_generic_poweroff(struct device *dev);`
|
||||
- if the device has not been suspended at run time, invoke the ->poweroff()
|
||||
callback provided by its driver and return its result, or return 0 if not
|
||||
defined
|
||||
|
||||
`int pm_generic_poweroff_noirq(struct device *dev);`
|
||||
- if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq()
|
||||
callback provided by the device's driver and return its result, or return
|
||||
0 if not defined
|
||||
|
||||
`int pm_generic_restore(struct device *dev);`
|
||||
- invoke the ->restore() callback provided by the driver of this device and,
|
||||
if successful, change the device's runtime PM status to 'active'
|
||||
|
||||
`int pm_generic_restore_noirq(struct device *dev);`
|
||||
- invoke the ->restore_noirq() callback provided by the device's driver
|
||||
.. kernel-doc:: drivers/base/power/generic_ops.c
|
||||
:export:
|
||||
|
||||
These functions are the defaults used by the PM core if a subsystem doesn't
|
||||
provide its own callbacks for ->runtime_idle(), ->runtime_suspend(),
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user