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

["Rafael J. Wysocki" <rjw@sisk.pl>]

On Tuesday, November 22, 2011, Ming Lei wrote:
> Hi,
> 
> On Mon, Nov 21, 2011 at 7:38 AM, Rafael J. Wysocki <rjw@sisk.pl> wrote:
> > From: Rafael J. Wysocki <rjw@sisk.pl>
> 
> >  * @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.

That's kind of complicated, see below.

> > + *     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().

That's correct, but at the same time it's not 100% clear what @resume should
do with devices that have been runtime-suspended before system suspend.

For example, it may depend on what power configuration the device is in
(it may be a member of a power domain that was off before the system suspend or
something like this).

I'm starting to think that it might be better to simply remove those comments
altogether. :-)

Thanks,
Rafael