| blob | 2b9e1005d88b7b14f6725437a5e77b870797bbe4 |
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.
68 -------------------------------------------------------------------------
70 [0-*] denotes any positive number starting from 0
71 [1-*] denotes any positive number starting from 1
72 RO read only value
73 WO write only value
74 RW read/write value
76 Read/write values may be read-only for some chips, depending on the
77 hardware implementation.
79 All entries (except name) are optional, and should only be created in a
80 given driver if the chip has the feature.
83 *********************
84 * Global attributes *
85 *********************
87 name The chip name.
88 This should be a short, lowercase string, not containing
89 whitespace, dashes, or the wildcard character '*'.
90 This attribute represents the chip name. It is the only
91 mandatory attribute.
92 I2C devices get this attribute created automatically.
93 RO
95 update_interval The interval at which the chip will update readings.
96 Unit: millisecond
97 RW
98 Some devices have a variable update rate or interval.
99 This attribute can be used to change it to the desired value.
102 ************
103 * Voltages *
104 ************
106 in[0-*]_min Voltage min value.
107 Unit: millivolt
108 RW
110 in[0-*]_lcrit Voltage critical min value.
111 Unit: millivolt
112 RW
113 If voltage drops to or below this limit, the system may
114 take drastic action such as power down or reset. At the very
115 least, it should report a fault.
117 in[0-*]_max Voltage max value.
118 Unit: millivolt
119 RW
121 in[0-*]_crit Voltage critical max value.
122 Unit: millivolt
123 RW
124 If voltage reaches or exceeds this limit, the system may
125 take drastic action such as power down or reset. At the very
126 least, it should report a fault.
128 in[0-*]_input Voltage input value.
129 Unit: millivolt
130 RO
131 Voltage measured on the chip pin.
132 Actual voltage depends on the scaling resistors on the
133 motherboard, as recommended in the chip datasheet.
134 This varies by chip and by motherboard.
135 Because of this variation, values are generally NOT scaled
136 by the chip driver, and must be done by the application.
137 However, some drivers (notably lm87 and via686a)
138 do scale, because of internal resistors built into a chip.
139 These drivers will output the actual voltage. Rule of
140 thumb: drivers should report the voltage values at the
141 "pins" of the chip.
143 in[0-*]_average
144 Average voltage
145 Unit: millivolt
146 RO
148 in[0-*]_lowest
149 Historical minimum voltage
150 Unit: millivolt
151 RO
153 in[0-*]_highest
154 Historical maximum voltage
155 Unit: millivolt
156 RO
158 in[0-*]_reset_history
159 Reset inX_lowest and inX_highest
160 WO
162 in_reset_history
163 Reset inX_lowest and inX_highest for all sensors
164 WO
166 in[0-*]_label Suggested voltage channel label.
167 Text string
168 Should only be created if the driver has hints about what
169 this voltage channel is being used for, and user-space
170 doesn't. In all other cases, the label is provided by
171 user-space.
172 RO
174 in[0-*]_enable
175 Enable or disable the sensors.
176 When disabled the sensor read will return -ENODATA.
177 1: Enable
178 0: Disable
179 RW
181 cpu[0-*]_vid CPU core reference voltage.
182 Unit: millivolt
183 RO
184 Not always correct.
186 vrm Voltage Regulator Module version number.
187 RW (but changing it should no more be necessary)
188 Originally the VRM standard version multiplied by 10, but now
189 an arbitrary number, as not all standards have a version
190 number.
191 Affects the way the driver calculates the CPU core reference
192 voltage from the vid pins.
194 Also see the Alarms section for status flags associated with voltages.
197 ********
198 * Fans *
199 ********
201 fan[1-*]_min Fan minimum value
202 Unit: revolution/min (RPM)
203 RW
205 fan[1-*]_max Fan maximum value
206 Unit: revolution/min (RPM)
207 Only rarely supported by the hardware.
208 RW
210 fan[1-*]_input Fan input value.
211 Unit: revolution/min (RPM)
212 RO
214 fan[1-*]_div Fan divisor.
215 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
216 RW
217 Some chips only support values 1, 2, 4 and 8.
218 Note that this is actually an internal clock divisor, which
219 affects the measurable speed range, not the read value.
221 fan[1-*]_pulses Number of tachometer pulses per fan revolution.
222 Integer value, typically between 1 and 4.
223 RW
224 This value is a characteristic of the fan connected to the
225 device's input, so it has to be set in accordance with the fan
226 model.
227 Should only be created if the chip has a register to configure
228 the number of pulses. In the absence of such a register (and
229 thus attribute) the value assumed by all devices is 2 pulses
230 per fan revolution.
232 fan[1-*]_target
233 Desired fan speed
234 Unit: revolution/min (RPM)
235 RW
236 Only makes sense if the chip supports closed-loop fan speed
237 control based on the measured fan speed.
239 fan[1-*]_label Suggested fan channel label.
240 Text string
241 Should only be created if the driver has hints about what
242 this fan channel is being used for, and user-space doesn't.
243 In all other cases, the label is provided by user-space.
244 RO
246 fan[1-*]_enable
247 Enable or disable the sensors.
248 When disabled the sensor read will return -ENODATA.
249 1: Enable
250 0: Disable
251 RW
253 Also see the Alarms section for status flags associated with fans.
256 *******
257 * PWM *
258 *******
260 pwm[1-*] Pulse width modulation fan control.
261 Integer value in the range 0 to 255
262 RW
263 255 is max or 100%.
265 pwm[1-*]_enable
266 Fan speed control method:
267 0: no fan speed control (i.e. fan at full speed)
268 1: manual fan speed control enabled (using pwm[1-*])
269 2+: automatic fan speed control enabled
270 Check individual chip documentation files for automatic mode
271 details.
272 RW
274 pwm[1-*]_mode 0: DC mode (direct current)
275 1: PWM mode (pulse-width modulation)
276 RW
278 pwm[1-*]_freq Base PWM frequency in Hz.
279 Only possibly available when pwmN_mode is PWM, but not always
280 present even then.
281 RW
283 pwm[1-*]_auto_channels_temp
284 Select which temperature channels affect this PWM output in
285 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
286 Which values are possible depend on the chip used.
287 RW
289 pwm[1-*]_auto_point[1-*]_pwm
290 pwm[1-*]_auto_point[1-*]_temp
291 pwm[1-*]_auto_point[1-*]_temp_hyst
292 Define the PWM vs temperature curve. Number of trip points is
293 chip-dependent. Use this for chips which associate trip points
294 to PWM output channels.
295 RW
297 temp[1-*]_auto_point[1-*]_pwm
298 temp[1-*]_auto_point[1-*]_temp
299 temp[1-*]_auto_point[1-*]_temp_hyst
300 Define the PWM vs temperature curve. Number of trip points is
301 chip-dependent. Use this for chips which associate trip points
302 to temperature channels.
303 RW
305 There is a third case where trip points are associated to both PWM output
306 channels and temperature channels: the PWM values are associated to PWM
307 output channels while the temperature values are associated to temperature
308 channels. In that case, the result is determined by the mapping between
309 temperature inputs and PWM outputs. When several temperature inputs are
310 mapped to a given PWM output, this leads to several candidate PWM values.
311 The actual result is up to the chip, but in general the highest candidate
312 value (fastest fan speed) wins.
315 ****************
316 * Temperatures *
317 ****************
319 temp[1-*]_type Sensor type selection.
320 Integers 1 to 6
321 RW
322 1: CPU embedded diode
323 2: 3904 transistor
324 3: thermal diode
325 4: thermistor
326 5: AMD AMDSI
327 6: Intel PECI
328 Not all types are supported by all chips
330 temp[1-*]_max Temperature max value.
331 Unit: millidegree Celsius (or millivolt, see below)
332 RW
334 temp[1-*]_min Temperature min value.
335 Unit: millidegree Celsius
336 RW
338 temp[1-*]_max_hyst
339 Temperature hysteresis value for max limit.
340 Unit: millidegree Celsius
341 Must be reported as an absolute temperature, NOT a delta
342 from the max value.
343 RW
345 temp[1-*]_min_hyst
346 Temperature hysteresis value for min limit.
347 Unit: millidegree Celsius
348 Must be reported as an absolute temperature, NOT a delta
349 from the min value.
350 RW
352 temp[1-*]_input Temperature input value.
353 Unit: millidegree Celsius
354 RO
356 temp[1-*]_crit Temperature critical max value, typically greater than
357 corresponding temp_max values.
358 Unit: millidegree Celsius
359 RW
361 temp[1-*]_crit_hyst
362 Temperature hysteresis value for critical limit.
363 Unit: millidegree Celsius
364 Must be reported as an absolute temperature, NOT a delta
365 from the critical value.
366 RW
368 temp[1-*]_emergency
369 Temperature emergency max value, for chips supporting more than
370 two upper temperature limits. Must be equal or greater than
371 corresponding temp_crit values.
372 Unit: millidegree Celsius
373 RW
375 temp[1-*]_emergency_hyst
376 Temperature hysteresis value for emergency limit.
377 Unit: millidegree Celsius
378 Must be reported as an absolute temperature, NOT a delta
379 from the emergency value.
380 RW
382 temp[1-*]_lcrit Temperature critical min value, typically lower than
383 corresponding temp_min values.
384 Unit: millidegree Celsius
385 RW
387 temp[1-*]_lcrit_hyst
388 Temperature hysteresis value for critical min limit.
389 Unit: millidegree Celsius
390 Must be reported as an absolute temperature, NOT a delta
391 from the critical min value.
392 RW
394 temp[1-*]_offset
395 Temperature offset which is added to the temperature reading
396 by the chip.
397 Unit: millidegree Celsius
398 Read/Write value.
400 temp[1-*]_label Suggested temperature channel label.
401 Text string
402 Should only be created if the driver has hints about what
403 this temperature channel is being used for, and user-space
404 doesn't. In all other cases, the label is provided by
405 user-space.
406 RO
408 temp[1-*]_lowest
409 Historical minimum temperature
410 Unit: millidegree Celsius
411 RO
413 temp[1-*]_highest
414 Historical maximum temperature
415 Unit: millidegree Celsius
416 RO
418 temp[1-*]_reset_history
419 Reset temp_lowest and temp_highest
420 WO
422 temp_reset_history
423 Reset temp_lowest and temp_highest for all sensors
424 WO
426 temp[1-*]_enable
427 Enable or disable the sensors.
428 When disabled the sensor read will return -ENODATA.
429 1: Enable
430 0: Disable
431 RW
433 Some chips measure temperature using external thermistors and an ADC, and
434 report the temperature measurement as a voltage. Converting this voltage
435 back to a temperature (or the other way around for limits) requires
436 mathematical functions not available in the kernel, so the conversion
437 must occur in user space. For these chips, all temp* files described
438 above should contain values expressed in millivolt instead of millidegree
439 Celsius. In other words, such temperature channels are handled as voltage
440 channels by the driver.
442 Also see the Alarms section for status flags associated with temperatures.
445 ************
446 * Currents *
447 ************
449 curr[1-*]_max Current max value
450 Unit: milliampere
451 RW
453 curr[1-*]_min Current min value.
454 Unit: milliampere
455 RW
457 curr[1-*]_lcrit Current critical low value
458 Unit: milliampere
459 RW
461 curr[1-*]_crit Current critical high value.
462 Unit: milliampere
463 RW
465 curr[1-*]_input Current input value
466 Unit: milliampere
467 RO
469 curr[1-*]_average
470 Average current use
471 Unit: milliampere
472 RO
474 curr[1-*]_lowest
475 Historical minimum current
476 Unit: milliampere
477 RO
479 curr[1-*]_highest
480 Historical maximum current
481 Unit: milliampere
482 RO
484 curr[1-*]_reset_history
485 Reset currX_lowest and currX_highest
486 WO
488 curr_reset_history
489 Reset currX_lowest and currX_highest for all sensors
490 WO
492 curr[1-*]_enable
493 Enable or disable the sensors.
494 When disabled the sensor read will return -ENODATA.
495 1: Enable
496 0: Disable
497 RW
499 Also see the Alarms section for status flags associated with currents.
501 *********
502 * Power *
503 *********
505 power[1-*]_average Average power use
506 Unit: microWatt
507 RO
509 power[1-*]_average_interval Power use averaging interval. A poll
510 notification is sent to this file if the
511 hardware changes the averaging interval.
512 Unit: milliseconds
513 RW
515 power[1-*]_average_interval_max Maximum power use averaging interval
516 Unit: milliseconds
517 RO
519 power[1-*]_average_interval_min Minimum power use averaging interval
520 Unit: milliseconds
521 RO
523 power[1-*]_average_highest Historical average maximum power use
524 Unit: microWatt
525 RO
527 power[1-*]_average_lowest Historical average minimum power use
528 Unit: microWatt
529 RO
531 power[1-*]_average_max A poll notification is sent to
532 power[1-*]_average when power use
533 rises above this value.
534 Unit: microWatt
535 RW
537 power[1-*]_average_min A poll notification is sent to
538 power[1-*]_average when power use
539 sinks below this value.
540 Unit: microWatt
541 RW
543 power[1-*]_input Instantaneous power use
544 Unit: microWatt
545 RO
547 power[1-*]_input_highest Historical maximum power use
548 Unit: microWatt
549 RO
551 power[1-*]_input_lowest Historical minimum power use
552 Unit: microWatt
553 RO
555 power[1-*]_reset_history Reset input_highest, input_lowest,
556 average_highest and average_lowest.
557 WO
559 power[1-*]_accuracy Accuracy of the power meter.
560 Unit: Percent
561 RO
563 power[1-*]_cap If power use rises above this limit, the
564 system should take action to reduce power use.
565 A poll notification is sent to this file if the
566 cap is changed by the hardware. The *_cap
567 files only appear if the cap is known to be
568 enforced by hardware.
569 Unit: microWatt
570 RW
572 power[1-*]_cap_hyst Margin of hysteresis built around capping and
573 notification.
574 Unit: microWatt
575 RW
577 power[1-*]_cap_max Maximum cap that can be set.
578 Unit: microWatt
579 RO
581 power[1-*]_cap_min Minimum cap that can be set.
582 Unit: microWatt
583 RO
585 power[1-*]_max Maximum power.
586 Unit: microWatt
587 RW
589 power[1-*]_crit Critical maximum power.
590 If power rises to or above this limit, the
591 system is expected take drastic action to reduce
592 power consumption, such as a system shutdown or
593 a forced powerdown of some devices.
594 Unit: microWatt
595 RW
597 power[1-*]_enable Enable or disable the sensors.
598 When disabled the sensor read will return
599 -ENODATA.
600 1: Enable
601 0: Disable
602 RW
604 Also see the Alarms section for status flags associated with power readings.
606 **********
607 * Energy *
608 **********
610 energy[1-*]_input Cumulative energy use
611 Unit: microJoule
612 RO
614 energy[1-*]_enable Enable or disable the sensors.
615 When disabled the sensor read will return
616 -ENODATA.
617 1: Enable
618 0: Disable
619 RW
621 ************
622 * Humidity *
623 ************
625 humidity[1-*]_input Humidity
626 Unit: milli-percent (per cent mille, pcm)
627 RO
630 humidity[1-*]_enable Enable or disable the sensors
631 When disabled the sensor read will return
632 -ENODATA.
633 1: Enable
634 0: Disable
635 RW
637 **********
638 * Alarms *
639 **********
641 Each channel or limit may have an associated alarm file, containing a
642 boolean value. 1 means than an alarm condition exists, 0 means no alarm.
644 Usually a given chip will either use channel-related alarms, or
645 limit-related alarms, not both. The driver should just reflect the hardware
646 implementation.
648 in[0-*]_alarm
649 curr[1-*]_alarm
650 power[1-*]_alarm
651 fan[1-*]_alarm
652 temp[1-*]_alarm
653 Channel alarm
654 0: no alarm
655 1: alarm
656 RO
658 OR
660 in[0-*]_min_alarm
661 in[0-*]_max_alarm
662 in[0-*]_lcrit_alarm
663 in[0-*]_crit_alarm
664 curr[1-*]_min_alarm
665 curr[1-*]_max_alarm
666 curr[1-*]_lcrit_alarm
667 curr[1-*]_crit_alarm
668 power[1-*]_cap_alarm
669 power[1-*]_max_alarm
670 power[1-*]_crit_alarm
671 fan[1-*]_min_alarm
672 fan[1-*]_max_alarm
673 temp[1-*]_min_alarm
674 temp[1-*]_max_alarm
675 temp[1-*]_lcrit_alarm
676 temp[1-*]_crit_alarm
677 temp[1-*]_emergency_alarm
678 Limit alarm
679 0: no alarm
680 1: alarm
681 RO
683 Each input channel may have an associated fault file. This can be used
684 to notify open diodes, unconnected fans etc. where the hardware
685 supports it. When this boolean has value 1, the measurement for that
686 channel should not be trusted.
688 fan[1-*]_fault
689 temp[1-*]_fault
690 Input fault condition
691 0: no fault occurred
692 1: fault condition
693 RO
695 Some chips also offer the possibility to get beeped when an alarm occurs:
697 beep_enable Master beep enable
698 0: no beeps
699 1: beeps
700 RW
702 in[0-*]_beep
703 curr[1-*]_beep
704 fan[1-*]_beep
705 temp[1-*]_beep
706 Channel beep
707 0: disable
708 1: enable
709 RW
711 In theory, a chip could provide per-limit beep masking, but no such chip
712 was seen so far.
714 Old drivers provided a different, non-standard interface to alarms and
715 beeps. These interface files are deprecated, but will be kept around
716 for compatibility reasons:
718 alarms Alarm bitmask.
719 RO
720 Integer representation of one to four bytes.
721 A '1' bit means an alarm.
722 Chips should be programmed for 'comparator' mode so that
723 the alarm will 'come back' after you read the register
724 if it is still valid.
725 Generally a direct representation of a chip's internal
726 alarm registers; there is no standard for the position
727 of individual bits. For this reason, the use of this
728 interface file for new drivers is discouraged. Use
729 individual *_alarm and *_fault files instead.
730 Bits are defined in kernel/include/sensors.h.
732 beep_mask Bitmask for beep.
733 Same format as 'alarms' with the same bit locations,
734 use discouraged for the same reason. Use individual
735 *_beep files instead.
736 RW
739 ***********************
740 * Intrusion detection *
741 ***********************
743 intrusion[0-*]_alarm
744 Chassis intrusion detection
745 0: OK
746 1: intrusion detected
747 RW
748 Contrary to regular alarm flags which clear themselves
749 automatically when read, this one sticks until cleared by
750 the user. This is done by writing 0 to the file. Writing
751 other values is unsupported.
753 intrusion[0-*]_beep
754 Chassis intrusion beep
755 0: disable
756 1: enable
757 RW
760 sysfs attribute writes interpretation
761 -------------------------------------
763 hwmon sysfs attributes always contain numbers, so the first thing to do is to
764 convert the input to a number, there are 2 ways todo this depending whether
765 the number can be negative or not:
766 unsigned long u = simple_strtoul(buf, NULL, 10);
767 long s = simple_strtol(buf, NULL, 10);
769 With buf being the buffer with the user input being passed by the kernel.
770 Notice that we do not use the second argument of strto[u]l, and thus cannot
771 tell when 0 is returned, if this was really 0 or is caused by invalid input.
772 This is done deliberately as checking this everywhere would add a lot of
773 code to the kernel.
775 Notice that it is important to always store the converted value in an
776 unsigned long or long, so that no wrap around can happen before any further
777 checking.
779 After the input string is converted to an (unsigned) long, the value should be
780 checked if its acceptable. Be careful with further conversions on the value
781 before checking it for validity, as these conversions could still cause a wrap
782 around before the check. For example do not multiply the result, and only
783 add/subtract if it has been divided before the add/subtract.
785 What to do if a value is found to be invalid, depends on the type of the
786 sysfs attribute that is being set. If it is a continuous setting like a
787 tempX_max or inX_max attribute, then the value should be clamped to its
788 limits using clamp_val(value, min_limit, max_limit). If it is not continuous
789 like for example a tempX_type, then when an invalid value is written,
790 -EINVAL should be returned.
792 Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
794 long v = simple_strtol(buf, NULL, 10) / 1000;
795 v = clamp_val(v, -128, 127);
796 /* write v to register */
798 Example2, fan divider setting, valid values 2, 4 and 8:
800 unsigned long v = simple_strtoul(buf, NULL, 10);
802 switch (v) {
803 case 2: v = 1; break;
804 case 4: v = 2; break;
805 case 8: v = 3; break;
806 default:
807 return -EINVAL;
808 }
809 /* write v to register */