lkml.org 
[lkml]   [2011]   [Nov]   [20]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH 5] PM: Update comments describing device power management callbacks
    On Mon, 21 Nov 2011, Rafael J. Wysocki wrote:

    > From: Rafael J. Wysocki <rjw@sisk.pl>
    >
    > The comments describing device power management callbacks in
    > include/pm.h are outdated and somewhat confusing, so make them
    > reflect the reality more accurately.

    A few comments below...

    > * @freeze: Hibernation-specific, executed before creating a hibernation image.
    > - * Quiesce operations so that a consistent image can be created, but do NOT
    > - * otherwise put the device into a low power device state and do NOT emit
    > - * system wakeup events. Save in main memory the device settings to be
    > - * used by @restore() during the subsequent resume from hibernation or by
    > - * the subsequent @thaw(), if the creation of the image or the restoration
    > - * of main memory contents from it fails.
    > + * Analogous to @suspend(), but it should not enable the device to signal
    > + * wakeup events. The majority of subsystems (with the notable exception
    > + * of the PCI bus type) expect the driver-level @freeze() to save the
    > + * device settings in memory to be used by @restore() during the subsequent
    > + * resume from hibernation.
    > + * Subsystem-level @freeze() is executed for all devices after invoking
    > + * subsystem-level @prepare() for all of them.

    The first three lines you removed contain some important points which I
    think should be retained.

    > @@ -174,29 +198,32 @@ typedef struct pm_message {
    > * their children.
    > *
    > * It is allowed to unregister devices while the above callbacks are being
    > - * executed. However, it is not allowed to unregister a device from within any
    > - * of its own callbacks.
    > + * executed. However, it is NOT allowed to unregister a device from within any
    > + * of its driver's callbacks.

    Please be a little more precise here. If driver D manages two devices,
    A and B, then D _is_ allowed to unregister A from within a callback for
    B (except if A is an ancestor of B or something like that). It's just
    not allowed to unregister B from within a callback for B.

    > - * There also are the following callbacks related to run-time power management
    > - * of devices:
    > + * There also are callbacks related to runtime power management of devices.
    > + * Again, these callbacks are executed by the PM core only for subsystems
    > + * (PM domains, device types, classes and bus types) and the subsystem-level
    > + * callbacks are supposed to invoke the driver callbacks. Moreover, the exact
    > + * actions to be performed by a device driver's callbacks generally depend on
    > + * the platform and subsystem the device belongs to.
    > *
    > * @runtime_suspend: Prepare the device for a condition in which it won't be
    > * able to communicate with the CPU(s) and RAM due to power management.
    > - * This need not mean that the device should be put into a low power state.
    > + * This need not mean that the device should be put into a low-power state.
    > * For example, if the device is behind a link which is about to be turned
    > * off, the device may remain at full power. If the device does go to low
    > - * power and is capable of generating run-time wake-up events, remote
    > - * wake-up (i.e., a hardware mechanism allowing the device to request a
    > - * change of its power state via a wake-up event, such as PCI PME) should
    > - * be enabled for it.
    > + * power and is capable of generating runtime wakeup events, remote wakeup
    > + * (i.e., a hardware mechanism allowing the device to request a change of
    > + * its power state via an interrupt) should be enabled for it.
    > *
    > * @runtime_resume: Put the device into the fully active state in response to a
    > - * wake-up event generated by hardware or at the request of software. If
    > - * necessary, put the device into the full power state and restore its
    > + * wakeup event generated by hardware or at the request of software. If
    > + * necessary, put the device into the full-power state and restore its
    > * registers, so that it is fully operational.
    > *
    > - * @runtime_idle: Device appears to be inactive and it might be put into a low
    > - * power state if all of the necessary conditions are satisfied. Check
    > + * @runtime_idle: Device appears to be inactive and it might be put into a
    > + * low-power state if all of the necessary conditions are satisfied. Check
    > * these conditions and handle the device as appropriate, possibly queueing
    > * a suspend request for it. The return value is ignored by the PM core.
    > */

    Somewhere in here the text should tell people to find more information
    in Documentation/power/runtime_pm.txt. Likewise for .../devices.txt,
    although that should be added at the appropriate spot higher up.

    Alan Stern



    \
     
     \ /
      Last update: 2011-11-21 03:59    [W:2.707 / U:0.000 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site