diff options
Diffstat (limited to 'Documentation/hwmon/sysfs-interface')
| -rw-r--r-- | Documentation/hwmon/sysfs-interface | 131 |
1 files changed, 97 insertions, 34 deletions
diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index b3a9e1b9dbda..a17b692d2679 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 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. ------------------------------------------------------------------------- @@ -78,8 +82,21 @@ RW read/write value Read/write values may be read-only for some chips, depending on the hardware implementation. -All entries are optional, and should only be created in a given driver -if the chip has the feature. +All entries (except name) are optional, and should only be created in a +given driver if the chip has the feature. + + +******** +* Name * +******** + +name The chip name. + This should be a short, lowercase string, not containing + spaces nor dashes, representing the chip name. This is + the only mandatory attribute. + I2C devices get this attribute created automatically. + RO + ************ * Voltages * @@ -104,18 +121,17 @@ in[0-*]_input Voltage input value. by the chip driver, and must be done by the application. However, some drivers (notably lm87 and via686a) do scale, because of internal resistors built into a chip. - These drivers will output the actual voltage. - - Typical usage: - in0_* CPU #1 voltage (not scaled) - in1_* CPU #2 voltage (not scaled) - in2_* 3.3V nominal (not scaled) - in3_* 5.0V nominal (scaled) - in4_* 12.0V nominal (scaled) - in5_* -12.0V nominal (scaled) - in6_* -5.0V nominal (scaled) - in7_* varies - in8_* varies + These drivers will output the actual voltage. Rule of + thumb: drivers should report the voltage values at the + "pins" of the chip. + +in[0-*]_label Suggested voltage channel label. + Text string + Should only be created if the driver has hints about what + this voltage channel is being used for, and user-space + doesn't. In all other cases, the label is provided by + user-space. + RO cpu[0-*]_vid CPU core reference voltage. Unit: millivolt @@ -159,6 +175,13 @@ fan[1-*]_target Only makes sense if the chip supports closed-loop fan speed control based on the measured fan speed. +fan[1-*]_label Suggested fan channel label. + Text string + Should only be created if the driver has hints about what + this fan channel is being used for, and user-space doesn't. + In all other cases, the label is provided by user-space. + RO + Also see the Alarms section for status flags associated with fans. @@ -219,12 +242,12 @@ temp[1-*]_auto_point[1-*]_temp_hyst **************** temp[1-*]_type Sensor type selection. - Integers 1 to 6 or thermistor Beta value (typically 3435) + Integers 1 to 6 RW 1: PII/Celeron Diode 2: 3904 transistor 3: thermal diode - 4: thermistor (default/unknown Beta) + 4: thermistor 5: AMD AMDSI 6: Intel PECI Not all types are supported by all chips @@ -260,18 +283,19 @@ temp[1-*]_crit_hyst from the critical value. RW -temp[1-4]_offset +temp[1-*]_offset Temperature offset which is added to the temperature reading by the chip. Unit: millidegree Celsius Read/Write value. - If there are multiple temperature sensors, temp1_* is - generally the sensor inside the chip itself, - reported as "motherboard temperature". temp2_* to - temp4_* are generally sensors external to the chip - itself, for example the thermal diode inside the CPU or - a thermistor nearby. +temp[1-*]_label Suggested temperature channel label. + Text string + Should only be created if the driver has hints about what + this temperature channel is being used for, and user-space + doesn't. In all other cases, the label is provided by + user-space. + RO Some chips measure temperature using external thermistors and an ADC, and report the temperature measurement as a voltage. Converting this voltage @@ -393,14 +417,53 @@ beep_mask Bitmask for beep. RW -********* -* Other * -********* - -eeprom Raw EEPROM data in binary form. - RO - -pec Enable or disable PEC (SMBus only) - 0: disable - 1: enable - 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 */ |