aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Documentation/hwmon/sysfs-interface58
1 files changed, 58 insertions, 0 deletions
diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface
index db7bb4a659c4..a2153c4616ad 100644
--- 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
67alarm (for example, whether a threshold must be met or must be exceeded 67alarm (for example, whether a threshold must be met or must be exceeded
68to cause an alarm) is chip-dependent. 68to cause an alarm) is chip-dependent.
69 69
70When setting values of hwmon sysfs attributes, the string representation of
71the desired value must be written, note that strings which are not a number
72are interpreted as 0! For more on how written strings are interpreted see the
73"sysfs attribute writes interpretation" section at the end of this file.
70 74
71------------------------------------------------------------------------- 75-------------------------------------------------------------------------
72 76
@@ -411,3 +415,57 @@ beep_mask Bitmask for beep.
411 use discouraged for the same reason. Use individual 415 use discouraged for the same reason. Use individual
412 *_beep files instead. 416 *_beep files instead.
413 RW 417 RW
418
419
420sysfs attribute writes interpretation
421-------------------------------------
422
423hwmon sysfs attributes always contain numbers, so the first thing to do is to
424convert the input to a number, there are 2 ways todo this depending whether
425the number can be negative or not:
426unsigned long u = simple_strtoul(buf, NULL, 10);
427long s = simple_strtol(buf, NULL, 10);
428
429With buf being the buffer with the user input being passed by the kernel.
430Notice that we do not use the second argument of strto[u]l, and thus cannot
431tell when 0 is returned, if this was really 0 or is caused by invalid input.
432This is done deliberately as checking this everywhere would add a lot of
433code to the kernel.
434
435Notice that it is important to always store the converted value in an
436unsigned long or long, so that no wrap around can happen before any further
437checking.
438
439After the input string is converted to an (unsigned) long, the value should be
440checked if its acceptable. Be careful with further conversions on the value
441before checking it for validity, as these conversions could still cause a wrap
442around before the check. For example do not multiply the result, and only
443add/subtract if it has been divided before the add/subtract.
444
445What to do if a value is found to be invalid, depends on the type of the
446sysfs attribute that is being set. If it is a continuous setting like a
447tempX_max or inX_max attribute, then the value should be clamped to its
448limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
449continuous like for example a tempX_type, then when an invalid value is
450written, -EINVAL should be returned.
451
452Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
453--- begin code ---
454long v = simple_strtol(buf, NULL, 10) / 1000;
455SENSORS_LIMIT(v, -128, 127);
456/* write v to register */
457--- end code ---
458
459Example2, fan divider setting, valid values 2, 4 and 8:
460--- begin code ---
461unsigned long v = simple_strtoul(buf, NULL, 10);
462
463switch (v) {
464 case 2: v = 1; break;
465 case 4: v = 2; break;
466 case 8: v = 3; break;
467 default:
468 return -EINVAL;
469}
470/* write v to register */
471--- end code ---