LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
* [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
@ 2008-03-06 18:12 Liam Girdwood
  2008-03-07 16:12 ` Greg KH
  2008-03-08  1:13 ` David Brownell
  0 siblings, 2 replies; 8+ messages in thread
From: Liam Girdwood @ 2008-03-06 18:12 UTC (permalink / raw)
  To: Andrew Morton; +Cc: linux-arm-kernel, linux-kernel, Mark Brown

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




^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
  2008-03-06 18:12 [UPDATED v3][PATCH 5/7] regulator: sysfs ABI Liam Girdwood
@ 2008-03-07 16:12 ` Greg KH
  2008-03-07 21:17   ` Mark Brown
  2008-03-08  1:13 ` David Brownell
  1 sibling, 1 reply; 8+ messages in thread
From: Greg KH @ 2008-03-07 16:12 UTC (permalink / raw)
  To: Liam Girdwood; +Cc: Andrew Morton, linux-arm-kernel, linux-kernel, Mark Brown

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
  2008-03-07 16:12 ` Greg KH
@ 2008-03-07 21:17   ` Mark Brown
  2008-03-08  1:17     ` David Brownell
  0 siblings, 1 reply; 8+ messages in thread
From: Mark Brown @ 2008-03-07 21:17 UTC (permalink / raw)
  To: Greg KH; +Cc: Liam Girdwood, Andrew Morton, linux-arm-kernel, linux-kernel

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.

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
  2008-03-06 18:12 [UPDATED v3][PATCH 5/7] regulator: sysfs ABI Liam Girdwood
  2008-03-07 16:12 ` Greg KH
@ 2008-03-08  1:13 ` David Brownell
  2008-03-08 21:13   ` Liam Girdwood
  1 sibling, 1 reply; 8+ messages in thread
From: David Brownell @ 2008-03-08  1:13 UTC (permalink / raw)
  To: linux-arm-kernel; +Cc: Liam Girdwood, Andrew Morton, linux-kernel

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


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
  2008-03-07 21:17   ` Mark Brown
@ 2008-03-08  1:17     ` David Brownell
  2008-03-08  5:52       ` Greg KH
  0 siblings, 1 reply; 8+ messages in thread
From: David Brownell @ 2008-03-08  1:17 UTC (permalink / raw)
  To: Mark Brown; +Cc: linux-arm-kernel, Greg KH, Andrew Morton, linux-kernel

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
  2008-03-08  1:17     ` David Brownell
@ 2008-03-08  5:52       ` Greg KH
  2008-03-08 17:26         ` Liam Girdwood
  0 siblings, 1 reply; 8+ messages in thread
From: Greg KH @ 2008-03-08  5:52 UTC (permalink / raw)
  To: David Brownell; +Cc: Mark Brown, linux-arm-kernel, Andrew Morton, linux-kernel

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
  2008-03-08  5:52       ` Greg KH
@ 2008-03-08 17:26         ` Liam Girdwood
  0 siblings, 0 replies; 8+ messages in thread
From: Liam Girdwood @ 2008-03-08 17:26 UTC (permalink / raw)
  To: Greg KH
  Cc: David Brownell, Mark Brown, linux-arm-kernel, Andrew Morton,
	linux-kernel

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


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [UPDATED v3][PATCH 5/7] regulator: sysfs ABI
  2008-03-08  1:13 ` David Brownell
@ 2008-03-08 21:13   ` Liam Girdwood
  0 siblings, 0 replies; 8+ messages in thread
From: Liam Girdwood @ 2008-03-08 21:13 UTC (permalink / raw)
  To: David Brownell; +Cc: linux-arm-kernel, Andrew Morton, linux-kernel

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


^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2008-03-08 21:14 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2008-03-06 18:12 [UPDATED v3][PATCH 5/7] regulator: sysfs ABI Liam Girdwood
2008-03-07 16:12 ` Greg KH
2008-03-07 21:17   ` Mark Brown
2008-03-08  1:17     ` David Brownell
2008-03-08  5:52       ` Greg KH
2008-03-08 17:26         ` Liam Girdwood
2008-03-08  1:13 ` David Brownell
2008-03-08 21:13   ` Liam Girdwood

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).