Information in PM messages

Information in PM messages

[Alan Stern]

Right now the pm_message structure contains only one member: event.  It 
tells, in rather generic form, the action a driver is supposed to take 
upon receiving the message.

It seems to me that when runtime PM is fully supported, drivers will also
want to know the source of a message.  So there will have to be two pieces
of information:

	The source, or the reason for the message;

	The target, or the desired state or power-level change.

For the messages produced by system sleep transitions (PM_EVENT_FREEZE, 
PM_EVENT_PRETHAW, PM_EVENT_SUSPEND, and PM_EVENT_ON) the source is simply 
"the system".

For messages produced by userspace writing to a sysfs attribute file, the 
source is "the user".

When drivers start supporting autosuspend and autoresume, they will want 
to create PM messages whose source is "the driver".

When a device sends a remote wakeup request, the source could be taken as
"the device".  However since it will always be a driver that generates the
PM message in response to the device request, the source could just as
well be "the driver", as with autoresume.

For system sources, we already have a set of target states.  For user
sources, the target states should be defined by the individual bus or
device driver.  The best way to represent them might be as pointers to
character strings, since strings are easily passed through sysfs.  For
driver sources, the target states are purely a driver-internal matter.  
They could be pointers to data structures containing operating-point
parameters, for instance.

This suggests that a pm_message_t should include (or should be accompanied 
by) an integer or enum that takes on one of these values:

	PM_SOURCE_SYSTEM, PM_SOURCE_USER, PM_SOURCE_DRIVER

The "event" member could be changed to a void * with very little trouble;  
this would allow it to represent all sorts of target states.  (It also
could be renamed "target", but this would be a lot of trouble!)  This
could help embedded platforms, which would then find it easy to add new
target states to represent different varieties of system sleep.

Currently hardly any drivers have implemented any serious runtime PM.  
When more start doing so, we might want to make explicit the following 
policy:

	A message whose source is USER or DRIVER should not be
	allowed to resume a device that was suspended by a message
	whose source was SYSTEM.  In other words, runtime PM and
	autoresume should not interfere with a system sleep transition.

(Mostly this can't happen, because such messages have to be created by 
tasks that normally will be frozen during a system sleep transition.  But 
some transitions don't freeze tasks, such as STR on powermac.)

Individual drivers might have requirements of their own, such as this one:

	A DRIVER suspend message should fail if the device's remote
	wakeup facility is not enabled.

(Obviously some devices, such as USB hubs, shouldn't autosuspend if they 
are unable or not permitted to autoresume.  For other devices, such as 
printers, this wouldn't matter.)

I think it makes sense to keep track of the reason behind a PM message.  
Although there hasn't been much reason to do so up 'til now, in the future 
it will become more important.  Think of this as a proposal for upcoming 
development.

Alan Stern

Re: Information in PM messages

[David Brownell]

On Wednesday 07 June 2006 2:53 pm, Alan Stern wrote:
> Right now the pm_message structure contains only one member: event.  It 
> tells, in rather generic form, the action a driver is supposed to take 
> upon receiving the message.

I look at it a bit differently.  Drivers have internal state machines,
and the event code is one of the things they use to distinguish which
of the potential "next" states to enter.

(Other factors include which system clocks will be available, what
voltage domains will be active and the specific parameters available
in those domains, what other drivers will be active, state like "is
this network interface marked UP", is this devices allowed to be a
wakeup event source, and so on.)


> It seems to me that when runtime PM is fully supported, drivers will also
> want to know the source of a message.

I don't like this model.  It's like that old programming language joke
idiom "comefrom", which was paired with "goto" in an effort to make
BASIC (or pre-f77 FORTRAN?) code even more cryptic, and highlight the
apple-pie-goodness of Structured Code.


> So there will have to be two pieces 
> of information:
> 
> 	The source, or the reason for the message;
> 
> 	The target, or the desired state or power-level change.

I don't agree that the source should matter.  The target of the
pm_message_t is clearly the device.  But it's the driver which will
take all the facts in hand and deduce the next state ... and like
the available device states, that logic is not knowable outside of
that driver.


> For messages produced by userspace writing to a sysfs attribute file, the 
> source is "the user".

But why should that make a difference?  If it matters, I'd contend
that the reason isn't specifically source, but some other issue.

Also, when a collection of drivers collaborate to manage some aspect
of power (like with USB OTG:  host, peripheral, OTG, and transceiver
drivers may be distinct), I don't think any individual driver should
care whether a request came from userspace or one if its peers.

(And for that matter, I'm fairly sure that userspace should not be
able to bypass/invalidate the agreements such drivers have made with
each other.  I still have truckloads of doubts about this notion that
any userspace power management should think about drivers, rather than
the functionality they expose.)


> When drivers start supporting autosuspend and autoresume, they will want 
> to create PM messages whose source is "the driver".

I don't see why they would...
 

> Currently hardly any drivers have implemented any serious runtime PM.

Depends what you mean by that term, and what domains you look at.

Lots of drivers for embedded hardware do things like clocking off
everything unless it's in active use.  Or minimizing/eliminating
use of timers, lessening the number of irqs to process.  Or making
"hot" code paths shorter, reducing CPU power demands.  (Etc.)

Agreed that with USB at least we know some good things to do which
we have not yet done ... like autosuspending devices, and thereby
reducing VBUS consumption by factors on the order of 100.  (And
because the functionality is associated with interfaces not devices,
achieving some of those things calls for USB framework updates.)
But this is another case where USB has PM needs that the rest of
the kernel hasn't yet thought about yet.


> When more start doing so, we might want to make explicit the following 
> policy:
> 
> 	A message whose source is USER or DRIVER should not be
> 	allowed to resume a device that was suspended by a message
> 	whose source was SYSTEM.  In other words, runtime PM and
> 	autoresume should not interfere with a system sleep transition.

Why wouldn't that be entirely the driver's responsibility, and
something they don't need API changes to achieve?

A device is in an autosuspend state, ok ... basically, this is
invisible to all code outside the driver.  Then it's told to
suspend(), entering some _different_ state than that autosuspend
state.  A state where autoresume is invalid.  QED, no interference,
just because the driver is written correctly.


> Individual drivers might have requirements of their own, such as this one:
> 
> 	A DRIVER suspend message should fail if the device's remote
> 	wakeup facility is not enabled.
> 
> (Obviously some devices, such as USB hubs, shouldn't autosuspend if they 
> are unable or not permitted to autoresume.  For other devices, such as 
> printers, this wouldn't matter.)

Again, all this can be part of the driver-internal state machine;
you've not shown why it would need to be visible at the pm-core
level (which includes pm_message_t event codes).

- Dave

Re: Information in PM messages

[Alan Stern]

On Thu, 8 Jun 2006, David Brownell wrote:

> On Wednesday 07 June 2006 2:53 pm, Alan Stern wrote:
> > Right now the pm_message structure contains only one member: event.  It 
> > tells, in rather generic form, the action a driver is supposed to take 
> > upon receiving the message.
> 
> I look at it a bit differently.  Drivers have internal state machines,
> and the event code is one of the things they use to distinguish which
> of the potential "next" states to enter.

That's pretty much the same as what I said.  Granted, the message sent by 
the PM core is subject to interpretation by the driver.  It has to be, 
given that it is generic.

> > It seems to me that when runtime PM is fully supported, drivers will also
> > want to know the source of a message.
> 
> I don't like this model.  It's like that old programming language joke
> idiom "comefrom", which was paired with "goto" in an effort to make
> BASIC (or pre-f77 FORTRAN?) code even more cryptic, and highlight the
> apple-pie-goodness of Structured Code.

I don't think your analogy is valid.  There are many situations where 
requests are accompanied by priority codes; this is not very different.  
System-sleep transitions are high-priority requests; runtime-PM requests 
are lower priority.


> > So there will have to be two pieces 
> > of information:
> > 
> > 	The source, or the reason for the message;
> > 
> > 	The target, or the desired state or power-level change.
> 
> I don't agree that the source should matter.  The target of the
> pm_message_t is clearly the device.  But it's the driver which will
> take all the facts in hand and deduce the next state ... and like
> the available device states, that logic is not knowable outside of
> that driver.

Parts of that logic _should_ be knowable outside of the driver.  For
instance, all drivers should obey this rule: "When a device has been
suspended as part of a system-sleep transition, its driver should not
resume the device before the system starts to wake up."


> > For messages produced by userspace writing to a sysfs attribute file, the 
> > source is "the user".
> 
> But why should that make a difference?  If it matters, I'd contend
> that the reason isn't specifically source, but some other issue.

Perhaps you'd prefer to call it the priority?

In particular, here is an important difference: Autoresume _is not_
allowed when a device has been suspended for a system-sleep transition.  
It _is_ allowed when a device has been suspended because of a runtime-PM
request from userspace.  Drivers cannot obey this rule unless they can
tell apart system-sleep suspend requests from runtime-PM suspend requests.


> (And for that matter, I'm fairly sure that userspace should not be
> able to bypass/invalidate the agreements such drivers have made with
> each other.

I never said it should.

>  I still have truckloads of doubts about this notion that
> any userspace power management should think about drivers, rather than
> the functionality they expose.)

I haven't said anything about userspace PM tools thinking about drivers.  
All I said was that the information exported/imported through sysfs should
be defined by the individual bus and device drivers.  How can you disagree
with that?


> > When drivers start supporting autosuspend and autoresume, they will want 
> > to create PM messages whose source is "the driver".
> 
> I don't see why they would...

For internal use.  At some point in the code, most or all of the resume 
pathways in a driver will converge.  Beyond that point, the driver might 
still want to know whether a particular resume request is part of a system 
wake-up transition as opposed to an autoresume.  Packaging that 
information within the PM message itself is a very convenient way of 
presenting it.


> > When more start doing so, we might want to make explicit the following 
> > policy:
> > 
> > 	A message whose source is USER or DRIVER should not be
> > 	allowed to resume a device that was suspended by a message
> > 	whose source was SYSTEM.  In other words, runtime PM and
> > 	autoresume should not interfere with a system sleep transition.
> 
> Why wouldn't that be entirely the driver's responsibility, and
> something they don't need API changes to achieve?
> 
> A device is in an autosuspend state, ok ... basically, this is
> invisible to all code outside the driver.  Then it's told to
> suspend(), entering some _different_ state than that autosuspend
> state.  A state where autoresume is invalid.  QED, no interference,
> just because the driver is written correctly.

It sounds like you did not understand what I wrote.  You talk about a
situation where a device in autosuspend is told to enter system-sleep.  
But I was talking about the situation where a device in system-sleep is
told to autoresume.  No driver should allow such an autoresume to succeed.  
On the other hand, when a device in runtime suspend is told to autoresume
the request _should_ succeed.  How is the driver supposed to know whether
a suspended device is in system sleep vs. runtime suspend?

Or suppose a suspended device receives a runtime-PM resume request.  
Should the request succeed?  Yes if the device was suspended via 
runtime PM, no if the device was suspended via system sleep.  How does the 
driver know which?


> > Individual drivers might have requirements of their own, such as this one:
> > 
> > 	A DRIVER suspend message should fail if the device's remote
> > 	wakeup facility is not enabled.
> > 
> > (Obviously some devices, such as USB hubs, shouldn't autosuspend if they 
> > are unable or not permitted to autoresume.  For other devices, such as 
> > printers, this wouldn't matter.)
> 
> Again, all this can be part of the driver-internal state machine;
> you've not shown why it would need to be visible at the pm-core
> level (which includes pm_message_t event codes).

All right, I admit that drivers can tell on their own which requests are 
auto-generated and which come from outside.  This doesn't alter the fact 
that drivers do need to be able to distinguish system-level 
state-transition requests from runtime-PM user requests.  Currently they 
can't.

Once you agree that this distinction is necessary, there's no reason not 
to allow also the ability to distinguish auto-generated requests.

Alan Stern

Re: Information in PM messages

[Alan Stern]

On Thu, 8 Jun 2006, David Brownell wrote:

> > 	A message whose source is USER or DRIVER should not be
> > 	allowed to resume a device that was suspended by a message
> > 	whose source was SYSTEM.  In other words, runtime PM and
> > 	autoresume should not interfere with a system sleep transition.
> 
> Why wouldn't that be entirely the driver's responsibility, and
> something they don't need API changes to achieve?

Perhaps we don't need to worry about this.

After all, in most cases it's impossible for a device which is suspended
as part of a system-sleep transition to get either a runtime-PM resume or
an autoresume request.  It can only happen in situations where the
system-sleep did not first freeze all tasks.  In those situations people
may agree that it is acceptable for the sleep transition to be aborted by
a user request or an autoresume.

If that is so then yes, we don't need to alter the PM message structures
in this way.

Alan Stern

Re: Information in PM messages

[David Brownell]

On Friday 09 June 2006 7:24 am, Alan Stern wrote:
> On Thu, 8 Jun 2006, David Brownell wrote:
> 
> > > 	A message whose source is USER or DRIVER should not be
> > > 	allowed to resume a device that was suspended by a message
> > > 	whose source was SYSTEM.  In other words, runtime PM and
> > > 	autoresume should not interfere with a system sleep transition.
> > 
> > Why wouldn't that be entirely the driver's responsibility, and
> > something they don't need API changes to achieve?
> 
> Perhaps we don't need to worry about this.
> 
> After all, in most cases it's impossible for a device which is suspended
> as part of a system-sleep transition to get either a runtime-PM resume or
> an autoresume request.  It can only happen in situations where the
> system-sleep did not first freeze all tasks.  In those situations people
> may agree that it is acceptable for the sleep transition to be aborted by
> a user request or an autoresume.
> 
> If that is so then yes, we don't need to alter the PM message structures
> in this way.

I think that's pretty much what I was saying by insisting that the driver's
PM state transitions have to be correct... invalid transtions will always
be invalid, regardless of whether or not the API gets complexified!  :)

- Dave