1Naming and data format standards for sysfs files
2================================================
3
4The libsensors library offers an interface to the raw sensors data
5through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
6completely chip-independent. It assumes that all the kernel drivers
7implement the standard sysfs interface described in this document.
8This makes adding or updating support for any given chip very easy, as
9libsensors, and applications using it, do not need to be modified.
10This is a major improvement compared to lm-sensors 2.
11
12Note that motherboards vary widely in the connections to sensor chips.
13There is no standard that ensures, for example, that the second
14temperature sensor is connected to the CPU, or that the second fan is on
15the CPU. Also, some values reported by the chips need some computation
16before they make full sense. For example, most chips can only measure
17voltages between 0 and +4V. Other voltages are scaled back into that
18range using external resistors. Since the values of these resistors
19can change from motherboard to motherboard, the conversions cannot be
20hard coded into the driver and have to be done in user space.
21
22For this reason, even if we aim at a chip-independent libsensors, it will
23still require a configuration file (e.g. /etc/sensors.conf) for proper
24values conversion, labeling of inputs and hiding of unused inputs.
25
26An alternative method that some programs use is to access the sysfs
27files directly. This document briefly describes the standards that the
28drivers follow, so that an application program can scan for entries and
29access this data in a simple and consistent way. That said, such programs
30will have to implement conversion, labeling and hiding of inputs. For
31this reason, it is still not recommended to bypass the library.
32
33Each chip gets its own directory in the sysfs /sys/devices tree.  To
34find all sensor chips, it is easier to follow the device symlinks from
35`/sys/class/hwmon/hwmon*`.
36
37Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
38in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
39in the hwmon "class" device directory are also supported. Complex drivers
40(e.g. drivers for multifunction chips) may want to use this possibility to
41avoid namespace pollution. The only drawback will be that older versions of
42libsensors won't support the driver in question.
43
44All sysfs values are fixed point numbers.
45
46There is only one value per file, unlike the older /proc specification.
47The common scheme for files naming is: <type><number>_<item>. Usual
48types for sensor chips are "in" (voltage), "temp" (temperature) and
49"fan" (fan). Usual items are "input" (measured value), "max" (high
50threshold, "min" (low threshold). Numbering usually starts from 1,
51except for voltages which start from 0 (because most data sheets use
52this). A number is always used for elements that can be present more
53than once, even if there is a single element of the given type on the
54specific chip. Other files do not refer to a specific element, so
55they have a simple name, and no number.
56
57Alarms are direct indications read from the chips. The drivers do NOT
58make comparisons of readings to thresholds. This allows violations
59between readings to be caught and alarmed. The exact definition of an
60alarm (for example, whether a threshold must be met or must be exceeded
61to cause an alarm) is chip-dependent.
62
63When setting values of hwmon sysfs attributes, the string representation of
64the desired value must be written, note that strings which are not a number
65are 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.
67
68Attribute access
69----------------
70
71Hardware monitoring sysfs attributes are displayed by unrestricted userspace
72applications. For this reason, all standard ABI attributes shall be world
73readable. Writeable standard ABI attributes shall be writeable only for
74privileged users.
75
76-------------------------------------------------------------------------
77
78======= ===========================================
79`[0-*]`	denotes any positive number starting from 0
80`[1-*]`	denotes any positive number starting from 1
81RO	read only value
82WO	write only value
83RW	read/write value
84======= ===========================================
85
86Read/write values may be read-only for some chips, depending on the
87hardware implementation.
88
89All entries (except name) are optional, and should only be created in a
90given driver if the chip has the feature.
91
92See Documentation/ABI/testing/sysfs-class-hwmon for a complete description
93of the attributes.
94
95*****************
96Global attributes
97*****************
98
99`name`
100		The chip name.
101
102`update_interval`
103		The interval at which the chip will update readings.
104
105
106********
107Voltages
108********
109
110`in[0-*]_min`
111		Voltage min value.
112
113`in[0-*]_lcrit`
114		Voltage critical min value.
115
116`in[0-*]_max`
117		Voltage max value.
118
119`in[0-*]_crit`
120		Voltage critical max value.
121
122`in[0-*]_input`
123		Voltage input value.
124
125`in[0-*]_average`
126		Average voltage
127
128`in[0-*]_lowest`
129		Historical minimum voltage
130
131`in[0-*]_highest`
132		Historical maximum voltage
133
134`in[0-*]_reset_history`
135		Reset inX_lowest and inX_highest
136
137`in_reset_history`
138		Reset inX_lowest and inX_highest for all sensors
139
140`in[0-*]_label`
141		Suggested voltage channel label.
142
143`in[0-*]_enable`
144		Enable or disable the sensors.
145
146`cpu[0-*]_vid`
147		CPU core reference voltage.
148
149`vrm`
150		Voltage Regulator Module version number.
151
152`in[0-*]_rated_min`
153		Minimum rated voltage.
154
155`in[0-*]_rated_max`
156		Maximum rated voltage.
157
158Also see the Alarms section for status flags associated with voltages.
159
160
161****
162Fans
163****
164
165`fan[1-*]_min`
166		Fan minimum value
167
168`fan[1-*]_max`
169		Fan maximum value
170
171`fan[1-*]_input`
172		Fan input value.
173
174`fan[1-*]_div`
175		Fan divisor.
176
177`fan[1-*]_pulses`
178		Number of tachometer pulses per fan revolution.
179
180`fan[1-*]_target`
181		Desired fan speed
182
183`fan[1-*]_label`
184		Suggested fan channel label.
185
186`fan[1-*]_enable`
187		Enable or disable the sensors.
188
189Also see the Alarms section for status flags associated with fans.
190
191
192***
193PWM
194***
195
196`pwm[1-*]`
197		Pulse width modulation fan control.
198
199`pwm[1-*]_enable`
200		Fan speed control method:
201
202`pwm[1-*]_mode`
203		direct current or pulse-width modulation.
204
205`pwm[1-*]_freq`
206		Base PWM frequency in Hz.
207
208`pwm[1-*]_auto_channels_temp`
209		Select which temperature channels affect this PWM output in
210		auto mode.
211
212`pwm[1-*]_auto_point[1-*]_pwm` / `pwm[1-*]_auto_point[1-*]_temp` / `pwm[1-*]_auto_point[1-*]_temp_hyst`
213		Define the PWM vs temperature curve.
214
215`temp[1-*]_auto_point[1-*]_pwm` / `temp[1-*]_auto_point[1-*]_temp` / `temp[1-*]_auto_point[1-*]_temp_hyst`
216		Define the PWM vs temperature curve.
217
218There is a third case where trip points are associated to both PWM output
219channels and temperature channels: the PWM values are associated to PWM
220output channels while the temperature values are associated to temperature
221channels. In that case, the result is determined by the mapping between
222temperature inputs and PWM outputs. When several temperature inputs are
223mapped to a given PWM output, this leads to several candidate PWM values.
224The actual result is up to the chip, but in general the highest candidate
225value (fastest fan speed) wins.
226
227
228************
229Temperatures
230************
231
232`temp[1-*]_type`
233		Sensor type selection.
234
235`temp[1-*]_max`
236		Temperature max value.
237
238`temp[1-*]_min`
239		Temperature min value.
240
241`temp[1-*]_max_hyst`
242		Temperature hysteresis value for max limit.
243
244`temp[1-*]_min_hyst`
245		Temperature hysteresis value for min limit.
246
247`temp[1-*]_input`
248		Temperature input value.
249
250`temp[1-*]_crit`
251		Temperature critical max value, typically greater than
252		corresponding temp_max values.
253
254`temp[1-*]_crit_hyst`
255		Temperature hysteresis value for critical limit.
256
257`temp[1-*]_emergency`
258		Temperature emergency max value, for chips supporting more than
259		two upper temperature limits.
260
261`temp[1-*]_emergency_hyst`
262		Temperature hysteresis value for emergency limit.
263
264`temp[1-*]_lcrit`
265		Temperature critical min value, typically lower than
266		corresponding temp_min values.
267
268`temp[1-*]_lcrit_hyst`
269		Temperature hysteresis value for critical min limit.
270
271`temp[1-*]_offset`
272		Temperature offset which is added to the temperature reading
273		by the chip.
274
275`temp[1-*]_label`
276		Suggested temperature channel label.
277
278`temp[1-*]_lowest`
279		Historical minimum temperature
280
281`temp[1-*]_highest`
282		Historical maximum temperature
283
284`temp[1-*]_reset_history`
285		Reset temp_lowest and temp_highest
286
287`temp_reset_history`
288		Reset temp_lowest and temp_highest for all sensors
289
290`temp[1-*]_enable`
291		Enable or disable the sensors.
292
293`temp[1-*]_rated_min`
294		Minimum rated temperature.
295
296`temp[1-*]_rated_max`
297		Maximum rated temperature.
298
299Some chips measure temperature using external thermistors and an ADC, and
300report the temperature measurement as a voltage. Converting this voltage
301back to a temperature (or the other way around for limits) requires
302mathematical functions not available in the kernel, so the conversion
303must occur in user space. For these chips, all temp* files described
304above should contain values expressed in millivolt instead of millidegree
305Celsius. In other words, such temperature channels are handled as voltage
306channels by the driver.
307
308Also see the Alarms section for status flags associated with temperatures.
309
310
311********
312Currents
313********
314
315`curr[1-*]_max`
316		Current max value.
317
318`curr[1-*]_min`
319		Current min value.
320
321`curr[1-*]_lcrit`
322		Current critical low value
323
324`curr[1-*]_crit`
325		Current critical high value.
326
327`curr[1-*]_input`
328		Current input value.
329
330`curr[1-*]_average`
331		Average current use.
332
333`curr[1-*]_lowest`
334		Historical minimum current.
335
336`curr[1-*]_highest`
337		Historical maximum current.
338
339`curr[1-*]_reset_history`
340		Reset currX_lowest and currX_highest
341
342		WO
343
344`curr_reset_history`
345		Reset currX_lowest and currX_highest for all sensors.
346
347`curr[1-*]_enable`
348		Enable or disable the sensors.
349
350`curr[1-*]_rated_min`
351		Minimum rated current.
352
353`curr[1-*]_rated_max`
354		Maximum rated current.
355
356Also see the Alarms section for status flags associated with currents.
357
358*****
359Power
360*****
361
362`power[1-*]_average`
363		Average power use.
364
365`power[1-*]_average_interval`
366		Power use averaging interval.
367
368`power[1-*]_average_interval_max`
369		Maximum power use averaging interval.
370
371`power[1-*]_average_interval_min`
372		Minimum power use averaging interval.
373
374`power[1-*]_average_highest`
375		Historical average maximum power use
376
377`power[1-*]_average_lowest`
378		Historical average minimum power use
379
380`power[1-*]_average_max`
381		A poll notification is sent to `power[1-*]_average` when
382		power use rises above this value.
383
384`power[1-*]_average_min`
385		A poll notification is sent to `power[1-*]_average` when
386		power use sinks below this value.
387
388`power[1-*]_input`
389		Instantaneous power use.
390
391`power[1-*]_input_highest`
392		Historical maximum power use
393
394`power[1-*]_input_lowest`
395		Historical minimum power use.
396
397`power[1-*]_reset_history`
398		Reset input_highest, input_lowest, average_highest and
399		average_lowest.
400
401`power[1-*]_accuracy`
402		Accuracy of the power meter.
403
404`power[1-*]_cap`
405		If power use rises above this limit, the
406		system should take action to reduce power use.
407
408`power[1-*]_cap_hyst`
409		Margin of hysteresis built around capping and notification.
410
411`power[1-*]_cap_max`
412		Maximum cap that can be set.
413
414`power[1-*]_cap_min`
415		Minimum cap that can be set.
416
417`power[1-*]_max`
418		Maximum power.
419
420`power[1-*]_crit`
421				Critical maximum power.
422
423				If power rises to or above this limit, the
424				system is expected take drastic action to reduce
425				power consumption, such as a system shutdown or
426				a forced powerdown of some devices.
427
428				Unit: microWatt
429
430				RW
431
432`power[1-*]_enable`
433				Enable or disable the sensors.
434
435				When disabled the sensor read will return
436				-ENODATA.
437
438				- 1: Enable
439				- 0: Disable
440
441				RW
442
443`power[1-*]_rated_min`
444				Minimum rated power.
445
446				Unit: microWatt
447
448				RO
449
450`power[1-*]_rated_max`
451				Maximum rated power.
452
453				Unit: microWatt
454
455				RO
456
457Also see the Alarms section for status flags associated with power readings.
458
459******
460Energy
461******
462
463`energy[1-*]_input`
464				Cumulative energy use
465
466				Unit: microJoule
467
468				RO
469
470`energy[1-*]_enable`
471				Enable or disable the sensors.
472
473				When disabled the sensor read will return
474				-ENODATA.
475
476				- 1: Enable
477				- 0: Disable
478
479				RW
480
481********
482Humidity
483********
484
485`humidity[1-*]_input`
486		Humidity.
487
488`humidity[1-*]_enable`
489		Enable or disable the sensors.
490
491`humidity[1-*]_rated_min`
492		Minimum rated humidity.
493
494`humidity[1-*]_rated_max`
495		Maximum rated humidity.
496
497******
498Alarms
499******
500
501Each channel or limit may have an associated alarm file, containing a
502boolean value. 1 means than an alarm condition exists, 0 means no alarm.
503
504Usually a given chip will either use channel-related alarms, or
505limit-related alarms, not both. The driver should just reflect the hardware
506implementation.
507
508+-------------------------------+-----------------------+
509| **`in[0-*]_alarm`,		| Channel alarm		|
510| `curr[1-*]_alarm`,		|			|
511| `power[1-*]_alarm`,		|   - 0: no alarm	|
512| `fan[1-*]_alarm`,		|   - 1: alarm		|
513| `temp[1-*]_alarm`**		|			|
514|				|   RO			|
515+-------------------------------+-----------------------+
516
517**OR**
518
519+-------------------------------+-----------------------+
520| **`in[0-*]_min_alarm`,	| Limit alarm		|
521| `in[0-*]_max_alarm`,		|			|
522| `in[0-*]_lcrit_alarm`,	|   - 0: no alarm	|
523| `in[0-*]_crit_alarm`,		|   - 1: alarm		|
524| `curr[1-*]_min_alarm`,	|			|
525| `curr[1-*]_max_alarm`,	| RO			|
526| `curr[1-*]_lcrit_alarm`,	|			|
527| `curr[1-*]_crit_alarm`,	|			|
528| `power[1-*]_cap_alarm`,	|			|
529| `power[1-*]_max_alarm`,	|			|
530| `power[1-*]_crit_alarm`,	|			|
531| `fan[1-*]_min_alarm`,		|			|
532| `fan[1-*]_max_alarm`,		|			|
533| `temp[1-*]_min_alarm`,	|			|
534| `temp[1-*]_max_alarm`,	|			|
535| `temp[1-*]_lcrit_alarm`,	|			|
536| `temp[1-*]_crit_alarm`,	|			|
537| `temp[1-*]_emergency_alarm`**	|			|
538+-------------------------------+-----------------------+
539
540Each input channel may have an associated fault file. This can be used
541to notify open diodes, unconnected fans etc. where the hardware
542supports it. When this boolean has value 1, the measurement for that
543channel should not be trusted.
544
545`fan[1-*]_fault` / `temp[1-*]_fault`
546		Input fault condition.
547
548Some chips also offer the possibility to get beeped when an alarm occurs:
549
550`beep_enable`
551		Master beep enable.
552
553`in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`,
554		Channel beep.
555
556In theory, a chip could provide per-limit beep masking, but no such chip
557was seen so far.
558
559Old drivers provided a different, non-standard interface to alarms and
560beeps. These interface files are deprecated, but will be kept around
561for compatibility reasons:
562
563`alarms`
564		Alarm bitmask.
565
566`beep_mask`
567		Bitmask for beep.
568
569
570*******************
571Intrusion detection
572*******************
573
574`intrusion[0-*]_alarm`
575		Chassis intrusion detection.
576
577`intrusion[0-*]_beep`
578		Chassis intrusion beep.
579
580****************************
581Average sample configuration
582****************************
583
584Devices allowing for reading {in,power,curr,temp}_average values may export
585attributes for controlling number of samples used to compute average.
586
587+--------------+---------------------------------------------------------------+
588| samples      | Sets number of average samples for all types of measurements. |
589|	       |							       |
590|	       | RW							       |
591+--------------+---------------------------------------------------------------+
592| in_samples   | Sets number of average samples for specific type of	       |
593| power_samples| measurements.						       |
594| curr_samples |							       |
595| temp_samples | Note that on some devices it won't be possible to set all of  |
596|	       | them to different values so changing one might also change    |
597|	       | some others.						       |
598|	       |							       |
599|	       | RW							       |
600+--------------+---------------------------------------------------------------+
601
602sysfs attribute writes interpretation
603-------------------------------------
604
605hwmon sysfs attributes always contain numbers, so the first thing to do is to
606convert the input to a number, there are 2 ways todo this depending whether
607the number can be negative or not::
608
609	unsigned long u = simple_strtoul(buf, NULL, 10);
610	long s = simple_strtol(buf, NULL, 10);
611
612With buf being the buffer with the user input being passed by the kernel.
613Notice that we do not use the second argument of strto[u]l, and thus cannot
614tell when 0 is returned, if this was really 0 or is caused by invalid input.
615This is done deliberately as checking this everywhere would add a lot of
616code to the kernel.
617
618Notice that it is important to always store the converted value in an
619unsigned long or long, so that no wrap around can happen before any further
620checking.
621
622After the input string is converted to an (unsigned) long, the value should be
623checked if its acceptable. Be careful with further conversions on the value
624before checking it for validity, as these conversions could still cause a wrap
625around before the check. For example do not multiply the result, and only
626add/subtract if it has been divided before the add/subtract.
627
628What to do if a value is found to be invalid, depends on the type of the
629sysfs attribute that is being set. If it is a continuous setting like a
630tempX_max or inX_max attribute, then the value should be clamped to its
631limits using clamp_val(value, min_limit, max_limit). If it is not continuous
632like for example a tempX_type, then when an invalid value is written,
633-EINVAL should be returned.
634
635Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees)::
636
637	long v = simple_strtol(buf, NULL, 10) / 1000;
638	v = clamp_val(v, -128, 127);
639	/* write v to register */
640
641Example2, fan divider setting, valid values 2, 4 and 8::
642
643	unsigned long v = simple_strtoul(buf, NULL, 10);
644
645	switch (v) {
646	case 2: v = 1; break;
647	case 4: v = 2; break;
648	case 8: v = 3; break;
649	default:
650		return -EINVAL;
651	}
652	/* write v to register */
653