[linux-pm] [RFC][PATCH 1/3] PM: Introduce new top level suspend and hibernation callbacks

[Alan Stern]

On Tue, 18 Mar 2008, Pavel Machek wrote:

> > + * @complete: Undo the changes made by @prepare().  This method is executed for
> > + *	all kinds of resume transitions, immediately following one of the resume
> > + *	callbacks: @resume(), @thaw(), @restore(), or @recover().  Also executed
> > + *	if a suspend callback (@suspend(), @freeze(), @poweroff(), @quiesce())
> > + *	immediately following a successful @prepare() fails OR if a new child
> > + *	of the device has been registered during @prepare().

"during a successful call to @prepare()"?

> So... we do prepare() but it detects new child, so it returns -EAGAIN.
>   so we call complete() based on description above
> ...and then we call prepare() to suspend again?

You misunderstood (maybe the comment needs to be clarified as above).  

If prepare() returns any error (including -EAGAIN) then complete() does
not get called.  If prepare() returns successfully but the PM core
detects that a new child was added while prepare() was running, then we
call complete(), suspend the child, and call prepare() again.

> > + * @suspend: Executed before putting the system into a sleep state in which the
> > + *	contents of main memory are preserved.  Quiesce the device, put it into
> 
> content....is?

It's okay to use "contents" -- analogous to the table of contents in a
book.  It's one of those weird corner cases where either alternative is
acceptable.

Alan Stern