[RFC] Driver States

[RFC] Driver States

[Adam Belay]

Dynamic power management may require devices and drivers to transition
between various physical and logical states.  I would like to start a
discussion on how these might be defined at the bus, driver, and class
levels.

Bus Level
=========
At the bus level, there are two state attributes, power and
enable/disable.  Enable/disable may mean different things on different
buses, but they generally refer to resource decoding.  A device can only
be enabled during a non-off power state.

A possible API:

struct bus_type {
	char			* name;

	struct subsystem	subsys;
	struct kset		drivers;
	struct kset		devices;

	struct bus_attribute	* bus_attrs;
	struct device_attribute	* dev_attrs;
	struct driver_attribute	* drv_attrs;

	int		(*match)(struct device * dev, struct device_driver * drv);
	int		(*hotplug) (struct device *dev, char **envp, 
				    int num_envp, char *buffer, int buffer_size);
	int		(*suspend)(struct device * dev, pm_message_t state);
	int		(*resume)(struct device * dev);
	int		(*enable)(struct device * dev);
	int		(*disable)(struct device * dev);
};

Driver Level
============
At the driver level there are two areas of interest, physical and
logical state.  There is an additional concern of transitioning between
these states multiple times.  Because a driver acts as a bridge between
physical and logical components, I think separating these steps seems
natural.

A possible API:

struct device_driver {
	char			* name;
	struct bus_type		* bus;

	struct semaphore	unload_sem;
	struct kobject		kobj;
	struct list_head	devices;

	struct module 		* owner;

	int	(*attach)	(struct device * dev);
	int	(*start)	(struct device * dev);
	int	(*open)		(struct device * dev);
	int	(*close)	(struct device * dev);
	void 	(*stop)		(struct device * dev);
	void	(*detach)	(struct device * dev);
	void	(*shutdown)	(struct device * dev);
	int	(*suspend)	(struct device * dev, u32 state, u32 level);
	int	(*resume)	(struct device * dev, u32 level);
};

*attach - allocates data structures, creates sysfs entries, prepares driver
       to handle the hardware.
 
*start -  Sets up device resources and configures the hardware.  Loads
firmware, etc.
(physical)
 
*open -   engages the hardware, and makes it usable by the class device.
(logical and physical)
 
*close -  disengages the hardware, and stops class level access
(logical and physical)
 
*stop -   physically disables the hardware
(physical)
 
*detach - tears down the driver and releases it from the "struct device"

The idea behind *attach and *detach is to move code that would only need
to be called once out of *probe and *remove.

A table could be defined that indicates what should be called for each
power level transition.  *suspend and *resume could handle any extra
steps (ex. saving state).  As an example, *start and *stop may only be
called when power is going to be lost entirely.

Additional states are class specific and would only be used after *open
is called.

Class Level
===========
At the class level, we could have a simple start/stop mechanism.

A possible API:

struct class_device {
	struct list_head	node;

	struct kobject		kobj;
	struct class		* class;
	struct device		* dev;
	void			* class_data;

	char	class_id[BUS_ID_SIZE];

	int	(*attach)	(struct device * dev);
	int	(*start)	(struct device * dev);
	void 	(*stop)		(struct device * dev);
	void	(*detach)	(struct device * dev);
};

*attach - allocates data structures, creates sysfs entries, prepares
class to handle the device.

*start - start the logical class device, accept userspace interaction

*stop - stop the logical class device, deny userspace interaction

*detach - tear down the class driver's bindings with this class device


These are just rough ideas.  I look forward to any comments or
alternative approaches.

Thanks,
Adam

Re: [RFC] Driver States

[Patrick Mochel]

On Sun, 27 Mar 2005, Adam Belay wrote:

> Dynamic power management may require devices and drivers to transition
> between various physical and logical states.  I would like to start a
> discussion on how these might be defined at the bus, driver, and class
> levels.

<snip>

> Bus Level
> =========
> At the bus level, there are two state attributes, power and
> enable/disable.  Enable/disable may mean different things on different
> buses, but they generally refer to resource decoding.  A device can only
> be enabled during a non-off power state.

<...>

> Driver Level
> ============
> At the driver level there are two areas of interest, physical and
> logical state.  There is an additional concern of transitioning between
> these states multiple times.  Because a driver acts as a bridge between
> physical and logical components, I think separating these steps seems
> natural.

<...>

> *attach - allocates data structures, creates sysfs entries, prepares driver
>        to handle the hardware.
>
> *start -  Sets up device resources and configures the hardware.  Loads
> firmware, etc.
> (physical)
>
> *open -   engages the hardware, and makes it usable by the class device.
> (logical and physical)
>
> *close -  disengages the hardware, and stops class level access
> (logical and physical)
>
> *stop -   physically disables the hardware
> (physical)
>
> *detach - tears down the driver and releases it from the "struct device"
>

You have a few things here that can easily conflict, and that will be
developed at different paces. I like the direction that it's going, but
how do you intend to do it gradually. I.e. what to do first?


	Pat

Re: [RFC] Driver States

[Adam Belay]

On Tue, 2005-03-29 at 21:57 -0800, Patrick Mochel wrote:
> On Sun, 27 Mar 2005, Adam Belay wrote:
> 
> > Dynamic power management may require devices and drivers to transition
> > between various physical and logical states.  I would like to start a
> > discussion on how these might be defined at the bus, driver, and class
> > levels.
> 
> <snip>
> 
> > Bus Level
> > =========
> > At the bus level, there are two state attributes, power and
> > enable/disable.  Enable/disable may mean different things on different
> > buses, but they generally refer to resource decoding.  A device can only
> > be enabled during a non-off power state.
> 
> <...>
> 
> > Driver Level
> > ============
> > At the driver level there are two areas of interest, physical and
> > logical state.  There is an additional concern of transitioning between
> > these states multiple times.  Because a driver acts as a bridge between
> > physical and logical components, I think separating these steps seems
> > natural.
> 
> <...>
> 
> > *attach - allocates data structures, creates sysfs entries, prepares driver
> >        to handle the hardware.
> >
> > *start -  Sets up device resources and configures the hardware.  Loads
> > firmware, etc.
> > (physical)
> >
> > *open -   engages the hardware, and makes it usable by the class device.
> > (logical and physical)
> >
> > *close -  disengages the hardware, and stops class level access
> > (logical and physical)
> >
> > *stop -   physically disables the hardware
> > (physical)
> >
> > *detach - tears down the driver and releases it from the "struct device"
> >
> 
> You have a few things here that can easily conflict, and that will be
> developed at different paces. I like the direction that it's going, but
> how do you intend to do it gradually. I.e. what to do first?

I think the first step would be for us to all agree on a design, whether
it be this one or another, so we can began planning for long term
changes.

My arguments for these changes are as follows:

     1. If a device has been powered off, powered on, and restored in
        state, it is identical to a device that the driver is
        configuring for the first time.  So calling "*start" as part of
        device resume seems like a logical course of action.
     2. Being able to start and stop a device is useful outside the
        realm of power management.  It's required for resource
        re-balancing.  Also, the user may want to disable a device, but
        the device must still be able to save state and react correctly
        during a suspend.  Allowing the user to start and stop drivers
        gives more flexibility to userspace utilities.  There may be
        sysfs configuration files that can only be changed when the
        device isn't active.  Resource configuration cannot be changed
        when the device is in use.
     3. *open and *close also might be a possibility.  When a device is
        put into a lower power state, we want to stop driver timers and
        prepare the hardware to be inactive, which is exactly the role
        of "*close".  See the existing code in most net drivers.  I
        would like to note, however, that this portion of the API is
        optional, and needs to be looked into further.  I'm considering
        dropping it in favor of having suspend and resume handle this.
     4. Having responsibilities at each driver level encourages a
        layered and object based design, reducing code duplication and
        complexity.

* "*start" and "*stop" might even be useful for device error detection.
(Ex. we currently have no notion of starting up a device over again
after a hardware failure)

I think the next step would be to look at each class subsystem, and
verify that our proposed API could work well with it.  If it's going to
change the design of many device drivers, we want to make sure we get it
right.

>From there, the bus level changes could be made, as they would affect
the least upstream code.  Things like PCI PM could also be improved
during this stage.  Greg, I know that adding *enable, and *disable to
"struct bus_type" would be nice for PCI, ACPI, etc, as it would control
whether resources are decoded and other device initialization
requirements.  What about external devices such as USB?  Would such as
interface be useful for other buses?

Next, we could make changes to "struct device_driver".  As to not break
things, (*start or *attach) and (*stop or *detach) could be temporarily
mapped to *probe and *remove until everything is fixed up.  This hack
could be made at the bus level, so the fixes could be applied one bus at
a time.

The final step would be to introduce "*open and *close", if we decide to
use them, and also class device *start and *stop.  Pat, do you have any
comments on adding *start and *stop to class devices?  It seems like an
interesting possibility to me.

Thanks,
Adam

Re: [linux-pm] Re: [RFC] Driver States

[Pavel Machek]

Hi!

> > You have a few things here that can easily conflict, and that will be
> > developed at different paces. I like the direction that it's going, but
> > how do you intend to do it gradually. I.e. what to do first?
> 
> I think the first step would be for us to all agree on a design, whether
> it be this one or another, so we can began planning for long term
> changes.
> 
> My arguments for these changes are as follows:

0. I do not see how to gradually roll this in.

>      4. Having responsibilities at each driver level encourages a
>         layered and object based design, reducing code duplication and
>         complexity.

Unfortunately, you'll be retrofiting this to existing drivers. AFAICS,
trying to force existing driver to "layered and object based design"
can only result in mess.
								Pavel
-- 
People were complaining that M$ turns users into beta-testers...
...jr ghea gurz vagb qrirybcref, naq gurl frrz gb yvxr vg gung jnl!

Re: [linux-pm] Re: [RFC] Driver States

[Adam Belay]

On Tue, 2005-04-05 at 11:24 +0200, Pavel Machek wrote:
> Hi!
> 
> > > You have a few things here that can easily conflict, and that will be
> > > developed at different paces. I like the direction that it's going, but
> > > how do you intend to do it gradually. I.e. what to do first?
> > 
> > I think the first step would be for us to all agree on a design, whether
> > it be this one or another, so we can began planning for long term
> > changes.
> > 
> > My arguments for these changes are as follows:
> 
> 0. I do not see how to gradually roll this in.
> 
> >      4. Having responsibilities at each driver level encourages a
> >         layered and object based design, reducing code duplication and
> >         complexity.
> 
> Unfortunately, you'll be retrofiting this to existing drivers. AFAICS,
> trying to force existing driver to "layered and object based design"
> can only result in mess.
> 								Pavel

Fair enough.  How does this sound?  I'd like to add "*attach" and
"*detach" to "struct device_driver".  These functions would act as one
time initializers and decontructors.  Then we could rename "*probe" to
"*start", and "*remove" to "*stop", which should be rather trivial to
fix up.  From there drivers could slowly be converted to use "*attach"
and "*detach", but will not be broken along the way.

So the basic flow would be like this:

1.) a driver is bound to a device
2.) *attach is called to allocate data structures
3.) *start when it's time to probe the device
4.) *stop when the user disables the device
5.) repeat steps 3 and 4 any number of times
6.) *detach is called when unbinding the driver

The driver layering stuff could come later, but just implementing these
specific components would have immediate benefits.

In this early stage in development, I'd like to at least be able to
start and stop drivers for reasons outside of power management (ex. user
preference or resource re-balancing).  If a "*resume" function can also
utilize this functionality, then all the better.

Thanks,
Adam

Re: [linux-pm] Re: [RFC] Driver States

[Pavel Machek]

Hi!

> > > > You have a few things here that can easily conflict, and that will be
> > > > developed at different paces. I like the direction that it's going, but
> > > > how do you intend to do it gradually. I.e. what to do first?
> > > 
> > > I think the first step would be for us to all agree on a design, whether
> > > it be this one or another, so we can began planning for long term
> > > changes.
> > > 
> > > My arguments for these changes are as follows:
> > 
> > 0. I do not see how to gradually roll this in.
> > 
> > >      4. Having responsibilities at each driver level encourages a
> > >         layered and object based design, reducing code duplication and
> > >         complexity.
> > 
> > Unfortunately, you'll be retrofiting this to existing drivers. AFAICS,
> > trying to force existing driver to "layered and object based design"
> > can only result in mess.
> > 								Pavel
> 
> Fair enough.  How does this sound?  I'd like to add "*attach" and
> "*detach" to "struct device_driver".  These functions would act as one
> time initializers and decontructors.  Then we could rename "*probe" to
> "*start", and "*remove" to "*stop", which should be rather trivial to

I do not think you'll find rename across all the drivers easy. You
could get away with "I create start, and if it does not exist, probe
is called instead", but you need pretty good justification for that, too.

								Pavel
-- 
Boycott Kodak -- for their patent abuse against Java.