regulator: add get_status()

Based on previous LKML discussions:

 * Update docs for regulator sysfs class attributes to highlight
   the fact that all current attributes are intended to be control
   inputs, including notably "state" and "opmode" which previously
   implied otherwise.

 * Define a new regulator driver get_status() method, which is the
   first method reporting regulator outputs instead of inputs.
   It can report on/off and error status; or instead of simply
   "on", report the actual operating mode.

For the moment, this is a sysfs-only interface, not accessible to
regulator clients.  Such clients can use the current notification
interfaces to detect errors, if the regulator reports them.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Liam Girdwood <lrg@slimlogic.co.uk>

1 files changed, 48 insertions, 9 deletions

diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator
index 873ef1fc1569..e091fa873792 100644
--- a/Documentation/ABI/testing/sysfs-class-regulator
+++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -4,8 +4,8 @@ KernelVersion:	2.6.26
 Contact:        Liam Girdwood <lrg@slimlogic.co.uk>
 Description:
                 Some regulator directories will contain a field called
-                state. This reports the regulator enable status, for
-                regulators which can report that value.
+                state. This reports the regulator enable control, for
+                regulators which can report that input value.
 
                 This will be one of the following strings:
 
@@ -14,16 +14,54 @@ Description:
                 'unknown'
 
                 'enabled' means the regulator output is ON and is supplying
-                power to the system.
+                power to the system (assuming no error prevents it).
 
                 'disabled' means the regulator output is OFF and is not
-                supplying power to the system..
+                supplying power to the system (unless some non-Linux
+                control has enabled it).
 
                 'unknown' means software cannot determine the state, or
                 the reported state is invalid.
 
                 NOTE: this field can be used in conjunction with microvolts
-                and microamps to determine regulator output levels.
+                or microamps to determine configured regulator output levels.
+
+
+What:           /sys/class/regulator/.../status
+Description:
+                Some regulator directories will contain a field called
+                "status". This reports the current regulator status, for
+                regulators which can report that output value.
+
+                This will be one of the following strings:
+
+                        off
+                        on
+                        error
+                        fast
+                        normal
+                        idle
+                        standby
+
+                "off" means the regulator is not supplying power to the
+                system.
+
+                "on" means the regulator is supplying power to the system,
+                and the regulator can't report a detailed operation mode.
+
+                "error" indicates an out-of-regulation status such as being
+                disabled due to thermal shutdown, or voltage being unstable
+                because of problems with the input power supply.
+
+                "fast", "normal", "idle", and "standby" are all detailed
+                regulator operation modes (described elsewhere).  They
+                imply "on", but provide more detail.
+
+                Note that regulator status is a function of many inputs,
+                not limited to control inputs from Linux.  For example,
+                the actual load presented may trigger "error" status; or
+                a regulator may be enabled by another user, even though
+                Linux did not enable it.
 
 
 What:           /sys/class/regulator/.../type
@@ -58,7 +96,7 @@ Description:
                 Some regulator directories will contain a field called
                 microvolts. This holds the regulator output voltage setting
                 measured in microvolts (i.e. E-6 Volts), for regulators
-                which can report that voltage.
+                which can report the control input for voltage.
 
                 NOTE: This value should not be used to determine the regulator
                 output voltage level as this value is the same regardless of
@@ -73,7 +111,7 @@ Description:
                 Some regulator directories will contain a field called
                 microamps. This holds the regulator output current limit
                 setting measured in microamps (i.e. E-6 Amps), for regulators
-                which can report that current.
+                which can report the control input for a current limit.
 
                 NOTE: This value should not be used to determine the regulator
                 output current level as this value is the same regardless of
@@ -87,7 +125,7 @@ Contact:	Liam Girdwood <lrg@slimlogic.co.uk>
 Description:
                 Some regulator directories will contain a field called
                 opmode. This holds the current regulator operating mode,
-                for regulators which can report it.
+                for regulators which can report that control input value.
 
                 The opmode value can be one of the following strings:
 
@@ -101,7 +139,8 @@ Description:
 
                 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.
+                whether the regulator is enabled or disabled.  A "status"
+                attribute may be available to determine the actual mode.
 
 
 What:           /sys/class/regulator/.../min_microvolts