1 Naming and data format standards for sysfs files
2 ================================================
4 The libsensors library offers an interface to the raw sensors data
5 through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
6 completely chip-independent. It assumes that all the kernel drivers
7 implement the standard sysfs interface described in this document.
8 This makes adding or updating support for any given chip very easy, as
9 libsensors, and applications using it, do not need to be modified.
10 This is a major improvement compared to lm-sensors 2.
12 Note that motherboards vary widely in the connections to sensor chips.
13 There is no standard that ensures, for example, that the second
14 temperature sensor is connected to the CPU, or that the second fan is on
15 the CPU. Also, some values reported by the chips need some computation
16 before they make full sense. For example, most chips can only measure
17 voltages between 0 and +4V. Other voltages are scaled back into that
18 range using external resistors. Since the values of these resistors
19 can change from motherboard to motherboard, the conversions cannot be
20 hard coded into the driver and have to be done in user space.
22 For this reason, even if we aim at a chip-independent libsensors, it will
23 still require a configuration file (e.g. /etc/sensors.conf) for proper
24 values conversion, labeling of inputs and hiding of unused inputs.
26 An alternative method that some programs use is to access the sysfs
27 files directly. This document briefly describes the standards that the
28 drivers follow, so that an application program can scan for entries and
29 access this data in a simple and consistent way. That said, such programs
30 will have to implement conversion, labeling and hiding of inputs. For
31 this reason, it is still not recommended to bypass the library.
33 Each chip gets its own directory in the sysfs /sys/devices tree. To
34 find all sensor chips, it is easier to follow the device symlinks from
35 `/sys/class/hwmon/hwmon*`.
37 Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
38 in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
39 in the hwmon "class" device directory are also supported. Complex drivers
40 (e.g. drivers for multifunction chips) may want to use this possibility to
41 avoid namespace pollution. The only drawback will be that older versions of
42 libsensors won't support the driver in question.
44 All sysfs values are fixed point numbers.
46 There is only one value per file, unlike the older /proc specification.
47 The common scheme for files naming is: <type><number>_<item>. Usual
48 types for sensor chips are "in" (voltage), "temp" (temperature) and
49 "fan" (fan). Usual items are "input" (measured value), "max" (high
50 threshold, "min" (low threshold). Numbering usually starts from 1,
51 except for voltages which start from 0 (because most data sheets use
52 this). A number is always used for elements that can be present more
53 than once, even if there is a single element of the given type on the
54 specific chip. Other files do not refer to a specific element, so
55 they have a simple name, and no number.
57 Alarms are direct indications read from the chips. The drivers do NOT
58 make comparisons of readings to thresholds. This allows violations
59 between readings to be caught and alarmed. The exact definition of an
60 alarm (for example, whether a threshold must be met or must be exceeded
61 to cause an alarm) is chip-dependent.
63 When setting values of hwmon sysfs attributes, the string representation of
64 the desired value must be written, note that strings which are not a number
65 are interpreted as 0! For more on how written strings are interpreted see the
66 "sysfs attribute writes interpretation" section at the end of this file.
71 Hardware monitoring sysfs attributes are displayed by unrestricted userspace
72 applications. For this reason, all standard ABI attributes shall be world
73 readable. Writeable standard ABI attributes shall be writeable only for
76 -------------------------------------------------------------------------
78 ======= ===========================================
79 `[0-*]` denotes any positive number starting from 0
80 `[1-*]` denotes any positive number starting from 1
84 ======= ===========================================
86 Read/write values may be read-only for some chips, depending on the
87 hardware implementation.
89 All entries (except name) are optional, and should only be created in a
90 given driver if the chip has the feature.
99 This should be a short, lowercase string, not containing
100 whitespace, dashes, or the wildcard character '*'.
101 This attribute represents the chip name. It is the only
103 I2C devices get this attribute created automatically.
108 The interval at which the chip will update readings.
113 Some devices have a variable update rate or interval.
114 This attribute can be used to change it to the desired value.
129 Voltage critical min value.
135 If voltage drops to or below this limit, the system may
136 take drastic action such as power down or reset. At the very
137 least, it should report a fault.
147 Voltage critical max value.
153 If voltage reaches or exceeds this limit, the system may
154 take drastic action such as power down or reset. At the very
155 least, it should report a fault.
164 Voltage measured on the chip pin.
166 Actual voltage depends on the scaling resistors on the
167 motherboard, as recommended in the chip datasheet.
169 This varies by chip and by motherboard.
170 Because of this variation, values are generally NOT scaled
171 by the chip driver, and must be done by the application.
172 However, some drivers (notably lm87 and via686a)
173 do scale, because of internal resistors built into a chip.
174 These drivers will output the actual voltage. Rule of
175 thumb: drivers should report the voltage values at the
186 Historical minimum voltage
193 Historical maximum voltage
199 `in[0-*]_reset_history`
200 Reset inX_lowest and inX_highest
205 Reset inX_lowest and inX_highest for all sensors
210 Suggested voltage channel label.
214 Should only be created if the driver has hints about what
215 this voltage channel is being used for, and user-space
216 doesn't. In all other cases, the label is provided by
222 Enable or disable the sensors.
224 When disabled the sensor read will return -ENODATA.
232 CPU core reference voltage.
241 Voltage Regulator Module version number.
243 RW (but changing it should no more be necessary)
245 Originally the VRM standard version multiplied by 10, but now
246 an arbitrary number, as not all standards have a version
249 Affects the way the driver calculates the CPU core reference
250 voltage from the vid pins.
253 Minimum rated voltage.
260 Maximum rated voltage.
266 Also see the Alarms section for status flags associated with voltages.
276 Unit: revolution/min (RPM)
283 Unit: revolution/min (RPM)
285 Only rarely supported by the hardware.
291 Unit: revolution/min (RPM)
298 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
302 Some chips only support values 1, 2, 4 and 8.
303 Note that this is actually an internal clock divisor, which
304 affects the measurable speed range, not the read value.
307 Number of tachometer pulses per fan revolution.
309 Integer value, typically between 1 and 4.
313 This value is a characteristic of the fan connected to the
314 device's input, so it has to be set in accordance with the fan
317 Should only be created if the chip has a register to configure
318 the number of pulses. In the absence of such a register (and
319 thus attribute) the value assumed by all devices is 2 pulses
325 Unit: revolution/min (RPM)
329 Only makes sense if the chip supports closed-loop fan speed
330 control based on the measured fan speed.
333 Suggested fan channel label.
337 Should only be created if the driver has hints about what
338 this fan channel is being used for, and user-space doesn't.
339 In all other cases, the label is provided by user-space.
344 Enable or disable the sensors.
346 When disabled the sensor read will return -ENODATA.
353 Also see the Alarms section for status flags associated with fans.
361 Pulse width modulation fan control.
363 Integer value in the range 0 to 255
370 Fan speed control method:
372 - 0: no fan speed control (i.e. fan at full speed)
373 - 1: manual fan speed control enabled (using `pwm[1-*]`)
374 - 2+: automatic fan speed control enabled
376 Check individual chip documentation files for automatic mode
382 - 0: DC mode (direct current)
383 - 1: PWM mode (pulse-width modulation)
388 Base PWM frequency in Hz.
390 Only possibly available when pwmN_mode is PWM, but not always
395 `pwm[1-*]_auto_channels_temp`
396 Select which temperature channels affect this PWM output in
399 Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
400 Which values are possible depend on the chip used.
404 `pwm[1-*]_auto_point[1-*]_pwm` / `pwm[1-*]_auto_point[1-*]_temp` / `pwm[1-*]_auto_point[1-*]_temp_hyst`
405 Define the PWM vs temperature curve.
407 Number of trip points is chip-dependent. Use this for chips
408 which associate trip points to PWM output channels.
412 `temp[1-*]_auto_point[1-*]_pwm` / `temp[1-*]_auto_point[1-*]_temp` / `temp[1-*]_auto_point[1-*]_temp_hyst`
413 Define the PWM vs temperature curve.
415 Number of trip points is chip-dependent. Use this for chips
416 which associate trip points to temperature channels.
420 There is a third case where trip points are associated to both PWM output
421 channels and temperature channels: the PWM values are associated to PWM
422 output channels while the temperature values are associated to temperature
423 channels. In that case, the result is determined by the mapping between
424 temperature inputs and PWM outputs. When several temperature inputs are
425 mapped to a given PWM output, this leads to several candidate PWM values.
426 The actual result is up to the chip, but in general the highest candidate
427 value (fastest fan speed) wins.
435 Sensor type selection.
441 - 1: CPU embedded diode
448 Not all types are supported by all chips
451 Temperature max value.
453 Unit: millidegree Celsius (or millivolt, see below)
458 Temperature min value.
460 Unit: millidegree Celsius
465 Temperature hysteresis value for max limit.
467 Unit: millidegree Celsius
469 Must be reported as an absolute temperature, NOT a delta
475 Temperature hysteresis value for min limit.
476 Unit: millidegree Celsius
478 Must be reported as an absolute temperature, NOT a delta
484 Temperature input value.
486 Unit: millidegree Celsius
491 Temperature critical max value, typically greater than
492 corresponding temp_max values.
494 Unit: millidegree Celsius
498 `temp[1-*]_crit_hyst`
499 Temperature hysteresis value for critical limit.
501 Unit: millidegree Celsius
503 Must be reported as an absolute temperature, NOT a delta
504 from the critical value.
508 `temp[1-*]_emergency`
509 Temperature emergency max value, for chips supporting more than
510 two upper temperature limits. Must be equal or greater than
511 corresponding temp_crit values.
513 Unit: millidegree Celsius
517 `temp[1-*]_emergency_hyst`
518 Temperature hysteresis value for emergency limit.
520 Unit: millidegree Celsius
522 Must be reported as an absolute temperature, NOT a delta
523 from the emergency value.
528 Temperature critical min value, typically lower than
529 corresponding temp_min values.
531 Unit: millidegree Celsius
535 `temp[1-*]_lcrit_hyst`
536 Temperature hysteresis value for critical min limit.
538 Unit: millidegree Celsius
540 Must be reported as an absolute temperature, NOT a delta
541 from the critical min value.
546 Temperature offset which is added to the temperature reading
549 Unit: millidegree Celsius
554 Suggested temperature channel label.
558 Should only be created if the driver has hints about what
559 this temperature channel is being used for, and user-space
560 doesn't. In all other cases, the label is provided by
566 Historical minimum temperature
568 Unit: millidegree Celsius
573 Historical maximum temperature
575 Unit: millidegree Celsius
579 `temp[1-*]_reset_history`
580 Reset temp_lowest and temp_highest
585 Reset temp_lowest and temp_highest for all sensors
590 Enable or disable the sensors.
592 When disabled the sensor read will return -ENODATA.
599 `temp[1-*]_rated_min`
600 Minimum rated temperature.
602 Unit: millidegree Celsius
606 `temp[1-*]_rated_max`
607 Maximum rated temperature.
609 Unit: millidegree Celsius
613 Some chips measure temperature using external thermistors and an ADC, and
614 report the temperature measurement as a voltage. Converting this voltage
615 back to a temperature (or the other way around for limits) requires
616 mathematical functions not available in the kernel, so the conversion
617 must occur in user space. For these chips, all temp* files described
618 above should contain values expressed in millivolt instead of millidegree
619 Celsius. In other words, such temperature channels are handled as voltage
620 channels by the driver.
622 Also see the Alarms section for status flags associated with temperatures.
644 Current critical low value
651 Current critical high value.
672 Historical minimum current
679 Historical maximum current
683 `curr[1-*]_reset_history`
684 Reset currX_lowest and currX_highest
689 Reset currX_lowest and currX_highest for all sensors
694 Enable or disable the sensors.
696 When disabled the sensor read will return -ENODATA.
703 `curr[1-*]_rated_min`
704 Minimum rated current.
710 `curr[1-*]_rated_max`
711 Maximum rated current.
717 Also see the Alarms section for status flags associated with currents.
730 `power[1-*]_average_interval`
731 Power use averaging interval. A poll
732 notification is sent to this file if the
733 hardware changes the averaging interval.
739 `power[1-*]_average_interval_max`
740 Maximum power use averaging interval
746 `power[1-*]_average_interval_min`
747 Minimum power use averaging interval
753 `power[1-*]_average_highest`
754 Historical average maximum power use
760 `power[1-*]_average_lowest`
761 Historical average minimum power use
767 `power[1-*]_average_max`
768 A poll notification is sent to
769 `power[1-*]_average` when power use
770 rises above this value.
776 `power[1-*]_average_min`
777 A poll notification is sent to
778 `power[1-*]_average` when power use
779 sinks below this value.
786 Instantaneous power use
792 `power[1-*]_input_highest`
793 Historical maximum power use
799 `power[1-*]_input_lowest`
800 Historical minimum power use
806 `power[1-*]_reset_history`
807 Reset input_highest, input_lowest,
808 average_highest and average_lowest.
812 `power[1-*]_accuracy`
813 Accuracy of the power meter.
820 If power use rises above this limit, the
821 system should take action to reduce power use.
822 A poll notification is sent to this file if the
823 cap is changed by the hardware. The `*_cap`
824 files only appear if the cap is known to be
825 enforced by hardware.
831 `power[1-*]_cap_hyst`
832 Margin of hysteresis built around capping and
840 Maximum cap that can be set.
847 Minimum cap that can be set.
861 Critical maximum power.
863 If power rises to or above this limit, the
864 system is expected take drastic action to reduce
865 power consumption, such as a system shutdown or
866 a forced powerdown of some devices.
873 Enable or disable the sensors.
875 When disabled the sensor read will return
883 `power[1-*]_rated_min`
890 `power[1-*]_rated_max`
897 Also see the Alarms section for status flags associated with power readings.
904 Cumulative energy use
911 Enable or disable the sensors.
913 When disabled the sensor read will return
925 `humidity[1-*]_input`
928 Unit: milli-percent (per cent mille, pcm)
933 `humidity[1-*]_enable`
934 Enable or disable the sensors
936 When disabled the sensor read will return
944 `humidity[1-*]_rated_min`
945 Minimum rated humidity.
947 Unit: milli-percent (per cent mille, pcm)
951 `humidity[1-*]_rated_max`
952 Maximum rated humidity.
954 Unit: milli-percent (per cent mille, pcm)
962 Each channel or limit may have an associated alarm file, containing a
963 boolean value. 1 means than an alarm condition exists, 0 means no alarm.
965 Usually a given chip will either use channel-related alarms, or
966 limit-related alarms, not both. The driver should just reflect the hardware
969 +-------------------------------+-----------------------+
970 | **`in[0-*]_alarm`, | Channel alarm |
971 | `curr[1-*]_alarm`, | |
972 | `power[1-*]_alarm`, | - 0: no alarm |
973 | `fan[1-*]_alarm`, | - 1: alarm |
974 | `temp[1-*]_alarm`** | |
976 +-------------------------------+-----------------------+
980 +-------------------------------+-----------------------+
981 | **`in[0-*]_min_alarm`, | Limit alarm |
982 | `in[0-*]_max_alarm`, | |
983 | `in[0-*]_lcrit_alarm`, | - 0: no alarm |
984 | `in[0-*]_crit_alarm`, | - 1: alarm |
985 | `curr[1-*]_min_alarm`, | |
986 | `curr[1-*]_max_alarm`, | RO |
987 | `curr[1-*]_lcrit_alarm`, | |
988 | `curr[1-*]_crit_alarm`, | |
989 | `power[1-*]_cap_alarm`, | |
990 | `power[1-*]_max_alarm`, | |
991 | `power[1-*]_crit_alarm`, | |
992 | `fan[1-*]_min_alarm`, | |
993 | `fan[1-*]_max_alarm`, | |
994 | `temp[1-*]_min_alarm`, | |
995 | `temp[1-*]_max_alarm`, | |
996 | `temp[1-*]_lcrit_alarm`, | |
997 | `temp[1-*]_crit_alarm`, | |
998 | `temp[1-*]_emergency_alarm`** | |
999 +-------------------------------+-----------------------+
1001 Each input channel may have an associated fault file. This can be used
1002 to notify open diodes, unconnected fans etc. where the hardware
1003 supports it. When this boolean has value 1, the measurement for that
1004 channel should not be trusted.
1006 `fan[1-*]_fault` / `temp[1-*]_fault`
1007 Input fault condition
1009 - 0: no fault occurred
1010 - 1: fault condition
1014 Some chips also offer the possibility to get beeped when an alarm occurs:
1024 `in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`,
1032 In theory, a chip could provide per-limit beep masking, but no such chip
1035 Old drivers provided a different, non-standard interface to alarms and
1036 beeps. These interface files are deprecated, but will be kept around
1037 for compatibility reasons:
1044 Integer representation of one to four bytes.
1046 A '1' bit means an alarm.
1048 Chips should be programmed for 'comparator' mode so that
1049 the alarm will 'come back' after you read the register
1050 if it is still valid.
1052 Generally a direct representation of a chip's internal
1053 alarm registers; there is no standard for the position
1054 of individual bits. For this reason, the use of this
1055 interface file for new drivers is discouraged. Use
1056 `individual *_alarm` and `*_fault` files instead.
1057 Bits are defined in kernel/include/sensors.h.
1061 Same format as 'alarms' with the same bit locations,
1062 use discouraged for the same reason. Use individual
1063 `*_beep` files instead.
1071 `intrusion[0-*]_alarm`
1072 Chassis intrusion detection
1075 - 1: intrusion detected
1079 Contrary to regular alarm flags which clear themselves
1080 automatically when read, this one sticks until cleared by
1081 the user. This is done by writing 0 to the file. Writing
1082 other values is unsupported.
1084 `intrusion[0-*]_beep`
1085 Chassis intrusion beep
1092 ****************************
1093 Average sample configuration
1094 ****************************
1096 Devices allowing for reading {in,power,curr,temp}_average values may export
1097 attributes for controlling number of samples used to compute average.
1099 +--------------+---------------------------------------------------------------+
1100 | samples | Sets number of average samples for all types of measurements. |
1103 +--------------+---------------------------------------------------------------+
1104 | in_samples | Sets number of average samples for specific type of |
1105 | power_samples| measurements. |
1107 | temp_samples | Note that on some devices it won't be possible to set all of |
1108 | | them to different values so changing one might also change |
1112 +--------------+---------------------------------------------------------------+
1114 sysfs attribute writes interpretation
1115 -------------------------------------
1117 hwmon sysfs attributes always contain numbers, so the first thing to do is to
1118 convert the input to a number, there are 2 ways todo this depending whether
1119 the number can be negative or not::
1121 unsigned long u = simple_strtoul(buf, NULL, 10);
1122 long s = simple_strtol(buf, NULL, 10);
1124 With buf being the buffer with the user input being passed by the kernel.
1125 Notice that we do not use the second argument of strto[u]l, and thus cannot
1126 tell when 0 is returned, if this was really 0 or is caused by invalid input.
1127 This is done deliberately as checking this everywhere would add a lot of
1130 Notice that it is important to always store the converted value in an
1131 unsigned long or long, so that no wrap around can happen before any further
1134 After the input string is converted to an (unsigned) long, the value should be
1135 checked if its acceptable. Be careful with further conversions on the value
1136 before checking it for validity, as these conversions could still cause a wrap
1137 around before the check. For example do not multiply the result, and only
1138 add/subtract if it has been divided before the add/subtract.
1140 What to do if a value is found to be invalid, depends on the type of the
1141 sysfs attribute that is being set. If it is a continuous setting like a
1142 tempX_max or inX_max attribute, then the value should be clamped to its
1143 limits using clamp_val(value, min_limit, max_limit). If it is not continuous
1144 like for example a tempX_type, then when an invalid value is written,
1145 -EINVAL should be returned.
1147 Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees)::
1149 long v = simple_strtol(buf, NULL, 10) / 1000;
1150 v = clamp_val(v, -128, 127);
1151 /* write v to register */
1153 Example2, fan divider setting, valid values 2, 4 and 8::
1155 unsigned long v = simple_strtoul(buf, NULL, 10);
1158 case 2: v = 1; break;
1159 case 4: v = 2; break;
1160 case 8: v = 3; break;
1164 /* write v to register */