Skip to contentSkip to conversation

regulator: sysfs ABI

PATCH In review Liam Girdwood 4 participants 8 messages Mar 6, 2008 – Mar 8, 2008

lore
Share & tools
lore
#0 lore raw

PATCH v3 5/7 regulator: sysfs ABI

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

---
 Documentation/ABI/testing/sysfs-class-regulator |  187 +++++++++++++++++++++++
 1 files changed, 187 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-class-regulator
Documentation/ABI/testing/sysfs-class-regulator new file +187 -0
new file mode 100644
index 0000000..3fe1f5a
@@ -0,0 +1,187 @@
+What:		/sys/class/regulator/.../state
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+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 <[email protected]>
+Description:
+		Some regulator directories will contain a link called parent.
+		This points to the parent or supply regulator if one exists.
Signature · 1 line
1.5.4.3
#1 lore raw
Quoted 2 lines · Liam Girdwood

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

Thanks for doing this, I appreciate it.

Documentation/ABI/testing/sysfs-class-regulator line 187

Quoted 7 lines
Documentation/ABI/testing/sysfs-class-regulator new file +7 -0
+What:		/sys/class/regulator/.../parent
+Date:		March 2008
+KernelVersion:	2.6.25
+Contact:	Liam Girdwood <[email protected]>
+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

#2 lore raw
Quoted 7 lines · Greg KH

Documentation/ABI/testing/sysfs-class-regulator line 187

Quoted 2 lines · Liam Girdwood
Documentation/ABI/testing/sysfs-class-regulator new file +2 -0
+		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.

#3 lore raw
Quoted 9 lines · Mark Brown
Quoted 7 lines · Greg KH

Documentation/ABI/testing/sysfs-class-regulator line 187

Quoted 2 lines · Liam Girdwood
Documentation/ABI/testing/sysfs-class-regulator new file +2 -0
+		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?

Quoted 4 lines

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

#4 lore raw
Quoted 10 lines · David Brownell
Quoted 9 lines · Mark Brown
Quoted 7 lines · Greg KH

Documentation/ABI/testing/sysfs-class-regulator line 187

Quoted 2 lines · Liam Girdwood
Documentation/ABI/testing/sysfs-class-regulator new file +2 -0
+		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?

Quoted 7 lines
Quoted 4 lines

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

#5 lore raw
Quoted 16 lines · Greg KH
Quoted 15 lines · David Brownell
Quoted 13 lines · Mark Brown
Quoted 7 lines · Greg KH

Documentation/ABI/testing/sysfs-class-regulator line 187

Quoted 2 lines · Liam Girdwood
Documentation/ABI/testing/sysfs-class-regulator new file +2 -0
+		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.

Quoted 7 lines
Quoted 2 lines

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

#6 lore raw
In reply to Liam Girdwood

Documentation/ABI/testing/sysfs-class-regulator

Quoted 5 lines · Liam Girdwood
Documentation/ABI/testing/sysfs-class-regulator new file +5 -0
+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.

Quoted 1 line

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

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

Review

Quoted 2 lines
(quoted diff) +2 -0
+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

#7 lore raw
Quoted 11 lines · David Brownell

Documentation/ABI/testing/sysfs-class-regulator

Quoted 5 lines · Liam Girdwood
Documentation/ABI/testing/sysfs-class-regulator new file +5 -0
+What:		/sys/class/regulator/.../microvolts
+	...
+
+What:		/sys/class/regulator/.../microamps
+	...

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

Quoted 3 lines

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).

Quoted 11 lines

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).

Quoted 5 lines
Quoted 2 lines

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

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

Agreed.

Quoted 7 lines

Review

Quoted 3 lines
(quoted diff) +2 -0
+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