<commit_before>Run-time Power Management Framework for I/O Devices

(C) 2009 <NAME> <<EMAIL>>, Novell Inc.

1. Introduction

Support for run-time power management (run-time PM) of I/O devices is provided
at the power management core (PM core) level by means of:

* The power management workqueue pm_wq in which bus types and device drivers can
  put their PM-related work items.  It is strongly recommended that pm_wq be
  used for queuing all work items related to run-time PM, because this allows
  them to be synchronized with system-wide power transitions (suspend to RAM,
  hibernation and resume from system sleep states).  pm_wq is declared in
  include/linux/pm_runtime.h and defined in kernel/power/main.c.

* A number of run-time PM fields in the 'power' member of 'struct device' (which
  is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can
  be used for synchronizing run-time PM operations with one another.

* Three device run-time PM callbacks in 'struct dev_pm_ops' (defined in
  include/linux/pm.h).

* A set of helper functions defined in drivers/base/power/runtime.c that can be
  used for carrying out run-time PM operations in such a way that the
  synchronization between them is taken care of by the PM core.  Bus types and
  device drivers are encouraged to use these functions.

The run-time PM callbacks present in 'struct dev_pm_ops', the device run-time PM
fields of 'struct dev_pm_info' and the core helper functions provided for
run-time PM are described below.

2. Device Run-time PM Callbacks

There are three device run-time PM callbacks defined in 'struct dev_pm_ops':

struct dev_pm_ops {
	...
	int (*runtime_suspend)(struct device *dev);
	int (*runtime_resume)(struct device *dev);
	void (*runtime_idle)(struct device *dev);
	...
};

The ->runtime_suspend() callback is executed by the PM core for the bus type of
the device being suspended.  The bus type's callback is then _entirely_
_responsible_ for handling the device as appropriate, which may, but need not
include executing the device driver's own ->runtime_suspend() callback (from the
PM core's point of view it is not necessary to implement a ->runtime_suspend()
callback in a device driver as long as the bus type's ->runtime_suspend() knows
what to do to handle the device).

  * Once the bus type's ->runtime_suspend() callback has completed successfully
    for given device, the PM core regards the device as suspended, which need
    not mean that the device has been put into a low power state.  It is
    supposed to mean, however, that the device will not process data and will
    not communicate with the CPU(s) and RAM until its bus type's
    ->runtime_resume() callback is executed for it.  The run-time PM status of
    a device after successful execution of its bus type's ->runtime_suspend()
    callback is 'suspended'.

  * If the bus type's ->runtime_suspend() callback returns -EBUSY or -EAGAIN,
    the device's run-time PM status is supposed to be 'active', which means that
    the device _must_ be fully operational afterwards.

  * If the bus type's ->runtime_suspend() callback returns an error code
    different from -EBUSY or -EAGAIN, the PM core regards this as a fatal
    error and will refuse to run the helper functions described in Section 4
    for the device, until the status of it is directly set either to 'active'
    or to 'suspended' (the PM core provides special helper functions for this
    purpose).

In particular, if the driver requires remote wakeup capability for proper
functioning and device_may_wakeup() returns 'false' for the device, then
->runtime_suspend() should return -EBUSY.  On the other hand, if
device_may_wakeup() returns 'true' for the device and the device is put
into a low power state during the execution of its bus type's
->runtime_suspend(), it is expected that remote wake-up (i.e. hardware mechanism
allowing the device to request a change of its power state, such as PCI PME)
will be enabled for the device.  Generally, remote wake-up should be enabled
for all input devices put into a low power state at run time.

The ->runtime_resume() callback is executed by the PM core for the bus type of
the device being woken up.  The bus type's callback is then _entirely_
_responsible_ for handling the device as appropriate, which may, but need not
include executing the device driver's own ->runtime_resume() callback (from the
PM core's point of view it is not necessary to implement a ->runtime_resume()
callback in a device driver as long as the bus type's ->runtime_resume() knows
what to do to handle the device).

  * Once the bus type's ->runtime_resume() callback has completed successfully,
    the PM core regards the device as fully operational, which means that the
    device _must_ be able to complete I/O operations as needed.  The run-time
    PM status of the device is then 'active'.

  * If the bus type's ->runtime_resume() callback returns an error code, the PM
    core regards this as a fatal error and will refuse to run the helper
    functions described in Section 4 for the device, until its status is
    directly set either to 'active' or to 'suspended' (the PM core provides
    special helper functions for this purpose).

The ->runtime_idle() callback is executed by the PM core for the bus type of
given device whenever the device appears to be idle, which is indicated to the
PM core by two counters, the device's usage counter and the counter of 'active'
children of the device.

  * If any of these counters is decreased using a helper function provided by
    the PM core and it turns out to be equal to zero, the other counter is
    checked.  If that counter also is equal to zero, the PM core executes the
    device bus type's ->runtime_idle() callback (with the device as an
    argument).

The action performed by a bus type's ->runtime_idle() callback is totally
dependent on the bus type in question, but the expected and recommended action
is to check if the device can be suspended (i.e. if all of the conditions
necessary for suspending the device are satisfied) and to queue up a suspend
request for the device in that case.

The helper functions provided by the PM core, described in Section 4, guarantee
that the following constraints are met with respect to the bus type's run-time
PM callbacks:

(1) The callbacks are mutually exclusive (e.g. it is forbidden to execute
    ->runtime_suspend() in parallel with ->runtime_resume() or with another
    instance of ->runtime_suspend() for the same device) with the exception that
    ->runtime_suspend() or ->runtime_resume() can be executed in parallel with
    ->runtime_idle() (although ->runtime_idle() will not be started while any
    of the other callbacks is being executed for the same device).

(2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active'
    devices (i.e. the PM core will only execute ->runtime_idle() or
    ->runtime_suspend() for the devices the run-time PM status of which is
    'active').

(3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device
    the usage counter of which is equal to zero _and_ either the counter of
    'active' children of which is equal to zero, or the 'power.ignore_children'
    flag of which is set.

(4) ->runtime_resume() can only be executed for 'suspended' devices  (i.e. the
    PM core will only execute ->runtime_resume() for the devices the run-time
    PM status of which is 'suspended').<commit_msg>PM / Runtime: Make documentation of runtime_idle() agree with the code<commit_after>Run-time Power Management Framework for I/O Devices

(C) 2009 <NAME> <<EMAIL>>, Novell Inc.

1. Introduction

Support for run-time power management (run-time PM) of I/O devices is provided
at the power management core (PM core) level by means of:

* The power management workqueue pm_wq in which bus types and device drivers can
  put their PM-related work items.  It is strongly recommended that pm_wq be
  used for queuing all work items related to run-time PM, because this allows
  them to be synchronized with system-wide power transitions (suspend to RAM,
  hibernation and resume from system sleep states).  pm_wq is declared in
  include/linux/pm_runtime.h and defined in kernel/power/main.c.

* A number of run-time PM fields in the 'power' member of 'struct device' (which
  is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can
  be used for synchronizing run-time PM operations with one another.

* Three device run-time PM callbacks in 'struct dev_pm_ops' (defined in
  include/linux/pm.h).

* A set of helper functions defined in drivers/base/power/runtime.c that can be
  used for carrying out run-time PM operations in such a way that the
  synchronization between them is taken care of by the PM core.  Bus types and
  device drivers are encouraged to use these functions.

The run-time PM callbacks present in 'struct dev_pm_ops', the device run-time PM
fields of 'struct dev_pm_info' and the core helper functions provided for
run-time PM are described below.

2. Device Run-time PM Callbacks

There are three device run-time PM callbacks defined in 'struct dev_pm_ops':

struct dev_pm_ops {
	...
	int (*runtime_suspend)(struct device *dev);
	int (*runtime_resume)(struct device *dev);
	int (*runtime_idle)(struct device *dev);
	...
};

The ->runtime_suspend() callback is executed by the PM core for the bus type of
the device being suspended.  The bus type's callback is then _entirely_
_responsible_ for handling the device as appropriate, which may, but need not
include executing the device driver's own ->runtime_suspend() callback (from the
PM core's point of view it is not necessary to implement a ->runtime_suspend()
callback in a device driver as long as the bus type's ->runtime_suspend() knows
what to do to handle the device).

  * Once the bus type's ->runtime_suspend() callback has completed successfully
    for given device, the PM core regards the device as suspended, which need
    not mean that the device has been put into a low power state.  It is
    supposed to mean, however, that the device will not process data and will
    not communicate with the CPU(s) and RAM until its bus type's
    ->runtime_resume() callback is executed for it.  The run-time PM status of
    a device after successful execution of its bus type's ->runtime_suspend()
    callback is 'suspended'.

  * If the bus type's ->runtime_suspend() callback returns -EBUSY or -EAGAIN,
    the device's run-time PM status is supposed to be 'active', which means that
    the device _must_ be fully operational afterwards.

  * If the bus type's ->runtime_suspend() callback returns an error code
    different from -EBUSY or -EAGAIN, the PM core regards this as a fatal
    error and will refuse to run the helper functions described in Section 4
    for the device, until the status of it is directly set either to 'active'
    or to 'suspended' (the PM core provides special helper functions for this
    purpose).

In particular, if the driver requires remote wakeup capability for proper
functioning and device_may_wakeup() returns 'false' for the device, then
->runtime_suspend() should return -EBUSY.  On the other hand, if
device_may_wakeup() returns 'true' for the device and the device is put
into a low power state during the execution of its bus type's
->runtime_suspend(), it is expected that remote wake-up (i.e. hardware mechanism
allowing the device to request a change of its power state, such as PCI PME)
will be enabled for the device.  Generally, remote wake-up should be enabled
for all input devices put into a low power state at run time.

The ->runtime_resume() callback is executed by the PM core for the bus type of
the device being woken up.  The bus type's callback is then _entirely_
_responsible_ for handling the device as appropriate, which may, but need not
include executing the device driver's own ->runtime_resume() callback (from the
PM core's point of view it is not necessary to implement a ->runtime_resume()
callback in a device driver as long as the bus type's ->runtime_resume() knows
what to do to handle the device).

  * Once the bus type's ->runtime_resume() callback has completed successfully,
    the PM core regards the device as fully operational, which means that the
    device _must_ be able to complete I/O operations as needed.  The run-time
    PM status of the device is then 'active'.

  * If the bus type's ->runtime_resume() callback returns an error code, the PM
    core regards this as a fatal error and will refuse to run the helper
    functions described in Section 4 for the device, until its status is
    directly set either to 'active' or to 'suspended' (the PM core provides
    special helper functions for this purpose).

The ->runtime_idle() callback is executed by the PM core for the bus type of
given device whenever the device appears to be idle, which is indicated to the
PM core by two counters, the device's usage counter and the counter of 'active'
children of the device.

  * If any of these counters is decreased using a helper function provided by
    the PM core and it turns out to be equal to zero, the other counter is
    checked.  If that counter also is equal to zero, the PM core executes the
    device bus type's ->runtime_idle() callback (with the device as an
    argument).

The action performed by a bus type's ->runtime_idle() callback is totally
dependent on the bus type in question, but the expected and recommended action
is to check if the device can be suspended (i.e. if all of the conditions
necessary for suspending the device are satisfied) and to queue up a suspend
request for the device in that case.  The value returned by this callback is
ignored by the PM core.

The helper functions provided by the PM core, described in Section 4, guarantee
that the following constraints are met with respect to the bus type's run-time
PM callbacks:

(1) The callbacks are mutually exclusive (e.g. it is forbidden to execute
    ->runtime_suspend() in parallel with ->runtime_resume() or with another
    instance of ->runtime_suspend() for the same device) with the exception that
    ->runtime_suspend() or ->runtime_resume() can be executed in parallel with
    ->runtime_idle() (although ->runtime_idle() will not be started while any
    of the other callbacks is being executed for the same device).

(2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active'
    devices (i.e. the PM core will only execute ->runtime_idle() or
    ->runtime_suspend() for the devices the run-time PM status of which is
    'active').

(3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device
    the usage counter of which is equal to zero _and_ either the counter of
    'active' children of which is equal to zero, or the 'power.ignore_children'
    flag of which is set.

(4) ->runtime_resume() can only be executed for 'suspended' devices  (i.e. the
    PM core will only execute ->runtime_resume() for the devices the run-time
    PM status of which is 'suspended').
{'fraction_non_alphanumeric': 0.05767706131078224, 'fraction_numerical': 0.0017177589852008456, 'mean_word_length': 3.9499672988881622, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 79, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '649622', 'n_tokens_mistral': 3939, 'n_tokens_neox': 3929, 'n_words': 2300}