nfs: rewrap NFS/RDMA documentation to 80 lines

[linux-2.6] / Documentation / hwmon / sysfs-interface

diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface
index db7bb4a659c4b7465fcb1ff9f0b6a4c95c7cd151..f4a8ebc1ef1acc11ae4bdd22c9299f4b84467c73 100644 (file)
--- a/Documentation/hwmon/sysfs-interface
+++ b/Documentation/hwmon/sysfs-interface
@@ -67,6 +67,10 @@ between readings to be caught and alarmed. The exact definition of an
 alarm (for example, whether a threshold must be met or must be exceeded
 to cause an alarm) is chip-dependent.
 
+When setting values of hwmon sysfs attributes, the string representation of
+the desired value must be written, note that strings which are not a number
+are interpreted as 0! For more on how written strings are interpreted see the
+"sysfs attribute writes interpretation" section at the end of this file.
 
 -------------------------------------------------------------------------
 
@@ -324,6 +328,37 @@ curr[1-*]_input    Current input value
                Unit: milliampere
                RO
 
+*********
+* Power *
+*********
+
+power[1-*]_average             Average power use
+                               Unit: microWatt
+                               RO
+
+power[1-*]_average_highest     Historical average maximum power use
+                               Unit: microWatt
+                               RO
+
+power[1-*]_average_lowest      Historical average minimum power use
+                               Unit: microWatt
+                               RO
+
+power[1-*]_input               Instantaneous power use
+                               Unit: microWatt
+                               RO
+
+power[1-*]_input_highest       Historical maximum power use
+                               Unit: microWatt
+                               RO
+
+power[1-*]_input_lowest                Historical minimum power use
+                               Unit: microWatt
+                               RO
+
+power[1-*]_reset_history       Reset input_highest, input_lowest,
+                               average_highest and average_lowest.
+                               WO
 
 **********
 * Alarms *
@@ -411,3 +446,55 @@ beep_mask  Bitmask for beep.
                use discouraged for the same reason. Use individual
                *_beep files instead.
                RW
+
+
+sysfs attribute writes interpretation
+-------------------------------------
+
+hwmon sysfs attributes always contain numbers, so the first thing to do is to
+convert the input to a number, there are 2 ways todo this depending whether
+the number can be negative or not:
+unsigned long u = simple_strtoul(buf, NULL, 10);
+long s = simple_strtol(buf, NULL, 10);
+
+With buf being the buffer with the user input being passed by the kernel.
+Notice that we do not use the second argument of strto[u]l, and thus cannot
+tell when 0 is returned, if this was really 0 or is caused by invalid input.
+This is done deliberately as checking this everywhere would add a lot of
+code to the kernel.
+
+Notice that it is important to always store the converted value in an
+unsigned long or long, so that no wrap around can happen before any further
+checking.
+
+After the input string is converted to an (unsigned) long, the value should be
+checked if its acceptable. Be careful with further conversions on the value
+before checking it for validity, as these conversions could still cause a wrap
+around before the check. For example do not multiply the result, and only
+add/subtract if it has been divided before the add/subtract.
+
+What to do if a value is found to be invalid, depends on the type of the
+sysfs attribute that is being set. If it is a continuous setting like a
+tempX_max or inX_max attribute, then the value should be clamped to its
+limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
+continuous like for example a tempX_type, then when an invalid value is
+written, -EINVAL should be returned.
+
+Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
+
+       long v = simple_strtol(buf, NULL, 10) / 1000;
+       v = SENSORS_LIMIT(v, -128, 127);
+       /* write v to register */
+
+Example2, fan divider setting, valid values 2, 4 and 8:
+
+       unsigned long v = simple_strtoul(buf, NULL, 10);
+
+       switch (v) {
+       case 2: v = 1; break;
+       case 4: v = 2; break;
+       case 8: v = 3; break;
+       default:
+               return -EINVAL;
+       }
+       /* write v to register */