[UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[Liam Girdwood]

This patch adds a description of the regulator class sysfs ABI to the
testing directory.

Signed-off-by: Liam Girdwood <lg@opensource.wolfsonmicro.com>
---
 Documentation/ABI/testing/sysfs-class-regulator |  187 +++++++++++++++++++++++
 1 files changed, 187 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-class-regulator

diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator
new file mode 100644
index 0000000..3fe1f5a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -0,0 +1,187 @@
+What:		/sys/class/regulator/.../state
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		state. This holds the regulator output state.
+
+		This will be one of the following strings:
+
+		'enabled'
+		'disabled'
+		'unknown'
+
+		'enabled' means the regulator output is ON and is supplying
+		power to the system.
+
+		'disabled' means the regulator output is OFF and is not
+		supplying power to the system..
+
+		'unknown' means software cannot determine the state.
+
+		NOTE: this field can be used in conjunction with microvolts
+		and microamps to determine regulator output levels.
+
+
+What:		/sys/class/regulator/.../type
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		type. This holds the regulator type.
+
+		This will be one of the following strings:
+
+		'voltage'
+		'current'
+		'unknown'
+
+		'voltage' means the regulator output voltage can be controlled
+		by software.
+
+		'current' means the regulator output current limit can be
+		controlled by software.
+
+		'unknown' means software cannot control either voltage or
+		current limit.
+
+
+What:		/sys/class/regulator/.../microvolts
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		microvolts. This holds the regulator output voltage setting
+		measured in microvolts (i.e. E-6 Volts).
+
+		NOTE: This value should not be used to determine the regulator
+		output voltage level as this value is the same regardless of
+		whether the regulator is enabled or disabled.
+
+
+What:		/sys/class/regulator/.../microamps
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		microamps. This holds the regulator output current limit
+		setting measured in microamps (i.e. E-6 Amps).
+
+		NOTE: This value should not be used to determine the regulator
+		output current level as this value is the same regardless of
+		whether the regulator is enabled or disabled.
+
+
+What:		/sys/class/regulator/.../opmode
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		opmode. This holds the regulator operating mode setting.
+
+		The opmode value can be one of the following strings:
+
+		'fast'
+		'normal'
+		'idle'
+		'standby'
+		'unknown'
+
+		The modes are described in include/linux/regulator/regulator.h
+
+		NOTE: This value should not be used to determine the regulator
+		output operating mode as this value is the same regardless of
+		whether the regulator is enabled or disabled.
+
+
+What:		/sys/class/regulator/.../min_microvolts
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		min_microvolts. This holds the minimum safe working regulator
+		output voltage setting for this domain measured in microvolts.
+
+		NOTE: this will return the string 'constraint not defined' if
+		the power domain has no min microvolts constraint defined by
+		platform code.
+
+
+What:		/sys/class/regulator/.../max_microvolts
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		max_microvolts. This holds the maximum safe working regulator
+		output voltage setting for this domain measured in microvolts.
+
+		NOTE: this will return the string 'constraint not defined' if
+		the power domain has no max microvolts constraint defined by
+		platform code.
+
+
+What:		/sys/class/regulator/.../min_microamps
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		min_microamps. This holds the minimum safe working regulator
+		output current limit setting for this domain measured in
+		microamps.
+
+		NOTE: this will return the string 'constraint not defined' if
+		the power domain has no min microamps constraint defined by
+		platform code.
+
+
+What:		/sys/class/regulator/.../max_microamps
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		max_microamps. This holds the maximum safe working regulator
+		output current limit setting for this domain measured in
+		microamps.
+
+		NOTE: this will return the string 'constraint not defined' if
+		the power domain has no max microamps constraint defined by
+		platform code.
+
+
+What:		/sys/class/regulator/.../num_users
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		num_users. This holds the number of consumer devices that
+		have called regulator_enable() on this regulator.
+
+
+What:		/sys/class/regulator/.../requested_microamps
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Each regulator directory will contain a field called
+		requested_microamps. This holds the total requested load
+		current in microamps for this regulator from all its consumer
+		devices.
+
+
+What:		/sys/class/regulator/.../parent
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
+Description:
+		Some regulator directories will contain a link called parent.
+		This points to the parent or supply regulator if one exists.
-- 
1.5.4.3

Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[Greg KH]

On Thu, Mar 06, 2008 at 06:12:05PM +0000, Liam Girdwood wrote:
> This patch adds a description of the regulator class sysfs ABI to the
> testing directory.

Thanks for doing this, I appreciate it.

> +What:		/sys/class/regulator/.../parent
> +Date:		March 2008
> +KernelVersion:	2.6.25
> +Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>
> +Description:
> +		Some regulator directories will contain a link called parent.
> +		This points to the parent or supply regulator if one exists.

I don't think this is needed, why not just parent the device properly in
the device tree itself?

thanks,

greg k-h

Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[Mark Brown]

On Fri, Mar 07, 2008 at 08:12:12AM -0800, Greg KH wrote:
> On Thu, Mar 06, 2008 at 06:12:05PM +0000, Liam Girdwood wrote:

> > +		Some regulator directories will contain a link called parent.
> > +		This points to the parent or supply regulator if one exists.

> I don't think this is needed, why not just parent the device properly in
> the device tree itself?

The device tree would tend to show parent for the the control interfaces
for the regulators (typically I2C or SPI) but there is likely to be
little or no relationship between that and the power distribution in the
system.

Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[David Brownell]

On Friday 07 March 2008, Mark Brown wrote:
> On Fri, Mar 07, 2008 at 08:12:12AM -0800, Greg KH wrote:
> > On Thu, Mar 06, 2008 at 06:12:05PM +0000, Liam Girdwood wrote:
> 
> > > +		Some regulator directories will contain a link called parent.
> > > +		This points to the parent or supply regulator if one exists.
> 
> > I don't think this is needed, why not just parent the device properly in
> > the device tree itself?
> 
> The device tree would tend to show parent for the the control interfaces
> for the regulators (typically I2C or SPI) but there is likely to be
> little or no relationship between that and the power distribution in the
> system.

I find "parent" a bit awkward, and Greg won't be the only one to
be asking that question.  Maybe it'd be better named "supply"?

- Dave

Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[Greg KH]

On Fri, Mar 07, 2008 at 05:17:43PM -0800, David Brownell wrote:
> On Friday 07 March 2008, Mark Brown wrote:
> > On Fri, Mar 07, 2008 at 08:12:12AM -0800, Greg KH wrote:
> > > On Thu, Mar 06, 2008 at 06:12:05PM +0000, Liam Girdwood wrote:
> > 
> > > > +		Some regulator directories will contain a link called parent.
> > > > +		This points to the parent or supply regulator if one exists.
> > 
> > > I don't think this is needed, why not just parent the device properly in
> > > the device tree itself?
> > 
> > The device tree would tend to show parent for the the control interfaces
> > for the regulators (typically I2C or SPI) but there is likely to be
> > little or no relationship between that and the power distribution in the
> > system.
> 
> I find "parent" a bit awkward, and Greg won't be the only one to
> be asking that question.  Maybe it'd be better named "supply"?

Yes, "parent" means something in the driver model (the parent of the
device in the tree).  I agree with the different wording like "supply"
if that makes sense.  Or something else other than "parent".

thanks,

greg k-h

Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[Liam Girdwood]

On Fri, 2008-03-07 at 21:52 -0800, Greg KH wrote:
> On Fri, Mar 07, 2008 at 05:17:43PM -0800, David Brownell wrote:
> > On Friday 07 March 2008, Mark Brown wrote:
> > > On Fri, Mar 07, 2008 at 08:12:12AM -0800, Greg KH wrote:
> > > > On Thu, Mar 06, 2008 at 06:12:05PM +0000, Liam Girdwood wrote:
> > > 
> > > > > +		Some regulator directories will contain a link called parent.
> > > > > +		This points to the parent or supply regulator if one exists.
> > > 
> > > > I don't think this is needed, why not just parent the device properly in
> > > > the device tree itself?
> > > 
> > > The device tree would tend to show parent for the the control interfaces
> > > for the regulators (typically I2C or SPI) but there is likely to be
> > > little or no relationship between that and the power distribution in the
> > > system.
> > 
> > I find "parent" a bit awkward, and Greg won't be the only one to
> > be asking that question.  Maybe it'd be better named "supply"?
> 
> Yes, "parent" means something in the driver model (the parent of the
> device in the tree).  I agree with the different wording like "supply"
> if that makes sense.  Or something else other than "parent".
> 

"supply" sounds good to me.

Liam

Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[David Brownell]

On Thursday 06 March 2008, Liam Girdwood wrote:

> +What:		/sys/class/regulator/.../microvolts
> +	...
> +
> +What:		/sys/class/regulator/.../microamps
> +	...

Versus Documentation/hwmon/sysfs-interface which uses
millivolts and milliamperes respectively.

Why not adopt the same convention?  (This applies to
many attributes, not just these two.)


Also, I'm kind of curious what you've thought about
power budgeting.  Example, a power supply ("regulator")
may be able to supply a voltage within a given range,
but only up to a maximum of 200 mA worth.

The model visible through these sysfs attributes seems to
be an either/or thing ... either regulating voltage, or
current, but not addressing the corresponding constraints
on the other one.


> +               NOTE: this will return the string 'constraint not defined'

How about just "undefined" for all those min/max values?


> +What:		/sys/class/regulator/.../requested_microamps
> +	...

Ditto re "milli" vs "micro".  Also, "requested" seems a bit opaque.
As a sum, maybe "total_mi{lli,cro}amps" would be more explanatory.

- Dave

Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI

[Liam Girdwood]

On Fri, 2008-03-07 at 17:13 -0800, David Brownell wrote:
> On Thursday 06 March 2008, Liam Girdwood wrote:
> 
> > +What:		/sys/class/regulator/.../microvolts
> > +	...
> > +
> > +What:		/sys/class/regulator/.../microamps
> > +	...
> 
> Versus Documentation/hwmon/sysfs-interface which uses
> millivolts and milliamperes respectively.
> 
> Why not adopt the same convention?  (This applies to
> many attributes, not just these two.)
> 

I originally had milli but changed to micro to conform with
power_supply.h (as our PMIC uses this interface to export it input
supplies to userspace).

> 
> Also, I'm kind of curious what you've thought about
> power budgeting.  Example, a power supply ("regulator")
> may be able to supply a voltage within a given range,
> but only up to a maximum of 200 mA worth.
> 
> The model visible through these sysfs attributes seems to
> be an either/or thing ... either regulating voltage, or
> current, but not addressing the corresponding constraints
> on the other one.
> 

In general it's up to the system hardware designer to ensure each
regulator can supply all the consumers on the domain - hence we don't
have power budgeting in software atm. However, I don't think it would be
too difficult to add in the future.

I'll also add support for a regulator that will do both voltage and
current (although I'm not aware of any in the market atm).

> 
> > +               NOTE: this will return the string 'constraint not defined'
> 
> How about just "undefined" for all those min/max values?
> 

Agreed.

> 
> > +What:		/sys/class/regulator/.../requested_microamps
> > +	...
> 
> Ditto re "milli" vs "micro".  Also, "requested" seems a bit opaque.
> As a sum, maybe "total_mi{lli,cro}amps" would be more explanatory.
> 

Ok, total_ sounds good.

Liam