Re: [PATCH 5] PM: Update comments describing device power management callbacks

[Ming Lei]

Hi,

On Mon, Nov 21, 2011 at 7:38 AM, Rafael J. Wysocki <rjw@xxxxxxx> wrote:
> From: Rafael J. Wysocki <rjw@xxxxxxx>

>  * @prepare: Prepare the device for the upcoming transition, but do NOT change
>  *     its hardware state.  Prevent new children of the device from being
> @@ -71,101 +78,118 @@ typedef struct pm_message {
>  *     probe method from being made too once @prepare() has succeeded).  If
>  *     @prepare() detects a situation it cannot handle (e.g. registration of a
>  *     child already in progress), it may return -EAGAIN, so that the PM core
> - *     can execute it once again (e.g. after the new child has been registered)
> + *     can execute it once again (e.g. after a new child has been registered)
>  *     to recover from the race condition.  This method is executed for all
>  *     kinds of suspend transitions and is followed by one of the suspend
>  *     callbacks: @suspend(), @freeze(), or @poweroff().
> - *     The PM core executes @prepare() for all devices before starting to
> - *     execute suspend callbacks for any of them, so drivers may assume all of
> - *     the other devices to be present and functional while @prepare() is being
> - *     executed.  In particular, it is safe to make GFP_KERNEL memory
> - *     allocations from within @prepare().  However, drivers may NOT assume
> - *     anything about the availability of the user space at that time and it
> - *     is not correct to request firmware from within @prepare() (it's too
> - *     late to do that).  [To work around this limitation, drivers may
> - *     register suspend and hibernation notifiers that are executed before the
> + *     The PM core executes subsystem-level @prepare() for all devices before
> + *     starting to execute suspend callbacks for any of them, so all devices
> + *     may be assumed to be present and functional while @prepare() is being

Devices aren't functional in runtime suspend state, so maybe the word of
'functional' should be removed.

> + *     executed.  However, device drivers may NOT assume anything about the
> + *     availability of user space at that time and it is NOT valid to request
> + *     firmware from within @prepare() (it's too late to do that).  It also is
> + *     NOT valid to allocate substantial amounts of memory from @prepare() in
> + *     the GFP_KERNEL mode.  [To work around these limitations, drivers may
> + *     register suspend and hibernation notifiers to be executed before the
>  *     freezing of tasks.]


>  * @resume: Executed after waking the system up from a sleep state in which the
> - *     contents of main memory were preserved.  Put the device into the
> - *     appropriate state, according to the information saved in memory by the
> - *     preceding @suspend().  The driver starts working again, responding to
> - *     hardware events and software requests.  The hardware may have gone
> - *     through a power-off reset, or it may have maintained state from the
> - *     previous suspend() which the driver may rely on while resuming.  On most
> - *     platforms, there are no restrictions on availability of resources like
> - *     clocks during @resume().
> + *     contents of main memory were preserved.  Undo the changes made by
> + *     the preceding @suspend() and cause the device to become operational

The device may still not be operational if it was runtime suspended
before running
@suspend().

> + *     (the exact action to perform depends on the device's subsystem).
> + *     The driver starts working again, responding to hardware events and
> + *     software requests.  The state of the device at the time its driver's
> + *     @resume() callback is run depends on the platform and subsystem the
> + *     device belongs to.  On most platforms, there are no restrictions on
> + *     availability of resources like clocks during @resume().
> + *     Subsystem-level @resume() is executed for all devices after invoking
> + *     subsystem-level @resume_noirq() for all of them.


thanks,
-- 
Ming Lei
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/