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`label`
103		A descriptive label that allows to uniquely identify a device
104		within the system.
105
106`update_interval`
107		The interval at which the chip will update readings.
108
109
110********
111Voltages
112********
113
114`in[0-*]_min`
115		Voltage min value.
116
117`in[0-*]_lcrit`
118		Voltage critical min value.
119
120`in[0-*]_max`
121		Voltage max value.
122
123`in[0-*]_crit`
124		Voltage critical max value.
125
126`in[0-*]_input`
127		Voltage input value.
128
129`in[0-*]_average`
130		Average voltage
131
132`in[0-*]_lowest`
133		Historical minimum voltage
134
135`in[0-*]_highest`
136		Historical maximum voltage
137
138`in[0-*]_reset_history`
139		Reset inX_lowest and inX_highest
140
141`in_reset_history`
142		Reset inX_lowest and inX_highest for all sensors
143
144`in[0-*]_label`
145		Suggested voltage channel label.
146
147`in[0-*]_enable`
148		Enable or disable the sensors.
149
150`cpu[0-*]_vid`
151		CPU core reference voltage.
152
153`vrm`
154		Voltage Regulator Module version number.
155
156`in[0-*]_rated_min`
157		Minimum rated voltage.
158
159`in[0-*]_rated_max`
160		Maximum rated voltage.
161
162Also see the Alarms section for status flags associated with voltages.
163
164
165****
166Fans
167****
168
169`fan[1-*]_min`
170		Fan minimum value
171
172`fan[1-*]_max`
173		Fan maximum value
174
175`fan[1-*]_input`
176		Fan input value.
177
178`fan[1-*]_div`
179		Fan divisor.
180
181`fan[1-*]_pulses`
182		Number of tachometer pulses per fan revolution.
183
184`fan[1-*]_target`
185		Desired fan speed
186
187`fan[1-*]_label`
188		Suggested fan channel label.
189
190`fan[1-*]_enable`
191		Enable or disable the sensors.
192
193Also see the Alarms section for status flags associated with fans.
194
195
196***
197PWM
198***
199
200`pwm[1-*]`
201		Pulse width modulation fan control.
202
203`pwm[1-*]_enable`
204		Fan speed control method.
205
206`pwm[1-*]_mode`
207		direct current or pulse-width modulation.
208
209`pwm[1-*]_freq`
210		Base PWM frequency in Hz.
211
212`pwm[1-*]_auto_channels_temp`
213		Select which temperature channels affect this PWM output in
214		auto mode.
215
216`pwm[1-*]_auto_point[1-*]_pwm` / `pwm[1-*]_auto_point[1-*]_temp` / `pwm[1-*]_auto_point[1-*]_temp_hyst`
217		Define the PWM vs temperature curve.
218
219`temp[1-*]_auto_point[1-*]_pwm` / `temp[1-*]_auto_point[1-*]_temp` / `temp[1-*]_auto_point[1-*]_temp_hyst`
220		Define the PWM vs temperature curve.
221
222There is a third case where trip points are associated to both PWM output
223channels and temperature channels: the PWM values are associated to PWM
224output channels while the temperature values are associated to temperature
225channels. In that case, the result is determined by the mapping between
226temperature inputs and PWM outputs. When several temperature inputs are
227mapped to a given PWM output, this leads to several candidate PWM values.
228The actual result is up to the chip, but in general the highest candidate
229value (fastest fan speed) wins.
230
231
232************
233Temperatures
234************
235
236`temp[1-*]_type`
237		Sensor type selection.
238
239`temp[1-*]_max`
240		Temperature max value.
241
242`temp[1-*]_min`
243		Temperature min value.
244
245`temp[1-*]_max_hyst`
246		Temperature hysteresis value for max limit.
247
248`temp[1-*]_min_hyst`
249		Temperature hysteresis value for min limit.
250
251`temp[1-*]_input`
252		Temperature input value.
253
254`temp[1-*]_crit`
255		Temperature critical max value, typically greater than
256		corresponding temp_max values.
257
258`temp[1-*]_crit_hyst`
259		Temperature hysteresis value for critical limit.
260
261`temp[1-*]_emergency`
262		Temperature emergency max value, for chips supporting more than
263		two upper temperature limits.
264
265`temp[1-*]_emergency_hyst`
266		Temperature hysteresis value for emergency limit.
267
268`temp[1-*]_lcrit`
269		Temperature critical min value, typically lower than
270		corresponding temp_min values.
271
272`temp[1-*]_lcrit_hyst`
273		Temperature hysteresis value for critical min limit.
274
275`temp[1-*]_offset`
276		Temperature offset which is added to the temperature reading
277		by the chip.
278
279`temp[1-*]_label`
280		Suggested temperature channel label.
281
282`temp[1-*]_lowest`
283		Historical minimum temperature
284
285`temp[1-*]_highest`
286		Historical maximum temperature
287
288`temp[1-*]_reset_history`
289		Reset temp_lowest and temp_highest
290
291`temp_reset_history`
292		Reset temp_lowest and temp_highest for all sensors
293
294`temp[1-*]_enable`
295		Enable or disable the sensors.
296
297`temp[1-*]_rated_min`
298		Minimum rated temperature.
299
300`temp[1-*]_rated_max`
301		Maximum rated temperature.
302
303Some chips measure temperature using external thermistors and an ADC, and
304report the temperature measurement as a voltage. Converting this voltage
305back to a temperature (or the other way around for limits) requires
306mathematical functions not available in the kernel, so the conversion
307must occur in user space. For these chips, all temp* files described
308above should contain values expressed in millivolt instead of millidegree
309Celsius. In other words, such temperature channels are handled as voltage
310channels by the driver.
311
312Also see the Alarms section for status flags associated with temperatures.
313
314
315********
316Currents
317********
318
319`curr[1-*]_max`
320		Current max value.
321
322`curr[1-*]_min`
323		Current min value.
324
325`curr[1-*]_lcrit`
326		Current critical low value
327
328`curr[1-*]_crit`
329		Current critical high value.
330
331`curr[1-*]_input`
332		Current input value.
333
334`curr[1-*]_average`
335		Average current use.
336
337`curr[1-*]_lowest`
338		Historical minimum current.
339
340`curr[1-*]_highest`
341		Historical maximum current.
342
343`curr[1-*]_reset_history`
344		Reset currX_lowest and currX_highest
345
346		WO
347
348`curr_reset_history`
349		Reset currX_lowest and currX_highest for all sensors.
350
351`curr[1-*]_enable`
352		Enable or disable the sensors.
353
354`curr[1-*]_rated_min`
355		Minimum rated current.
356
357`curr[1-*]_rated_max`
358		Maximum rated current.
359
360Also see the Alarms section for status flags associated with currents.
361
362*****
363Power
364*****
365
366`power[1-*]_average`
367		Average power use.
368
369`power[1-*]_average_interval`
370		Power use averaging interval.
371
372`power[1-*]_average_interval_max`
373		Maximum power use averaging interval.
374
375`power[1-*]_average_interval_min`
376		Minimum power use averaging interval.
377
378`power[1-*]_average_highest`
379		Historical average maximum power use
380
381`power[1-*]_average_lowest`
382		Historical average minimum power use
383
384`power[1-*]_average_max`
385		A poll notification is sent to `power[1-*]_average` when
386		power use rises above this value.
387
388`power[1-*]_average_min`
389		A poll notification is sent to `power[1-*]_average` when
390		power use sinks below this value.
391
392`power[1-*]_input`
393		Instantaneous power use.
394
395`power[1-*]_input_highest`
396		Historical maximum power use
397
398`power[1-*]_input_lowest`
399		Historical minimum power use.
400
401`power[1-*]_reset_history`
402		Reset input_highest, input_lowest, average_highest and
403		average_lowest.
404
405`power[1-*]_accuracy`
406		Accuracy of the power meter.
407
408`power[1-*]_cap`
409		If power use rises above this limit, the
410		system should take action to reduce power use.
411
412`power[1-*]_cap_hyst`
413		Margin of hysteresis built around capping and notification.
414
415`power[1-*]_cap_max`
416		Maximum cap that can be set.
417
418`power[1-*]_cap_min`
419		Minimum cap that can be set.
420
421`power[1-*]_max`
422		Maximum power.
423
424`power[1-*]_crit`
425				Critical maximum power.
426
427				If power rises to or above this limit, the
428				system is expected take drastic action to reduce
429				power consumption, such as a system shutdown or
430				a forced powerdown of some devices.
431
432				Unit: microWatt
433
434				RW
435
436`power[1-*]_enable`
437				Enable or disable the sensors.
438
439				When disabled the sensor read will return
440				-ENODATA.
441
442				- 1: Enable
443				- 0: Disable
444
445				RW
446
447`power[1-*]_rated_min`
448				Minimum rated power.
449
450				Unit: microWatt
451
452				RO
453
454`power[1-*]_rated_max`
455				Maximum rated power.
456
457				Unit: microWatt
458
459				RO
460
461Also see the Alarms section for status flags associated with power readings.
462
463******
464Energy
465******
466
467`energy[1-*]_input`
468				Cumulative energy use
469
470				Unit: microJoule
471
472				RO
473
474`energy[1-*]_enable`
475				Enable or disable the sensors.
476
477				When disabled the sensor read will return
478				-ENODATA.
479
480				- 1: Enable
481				- 0: Disable
482
483				RW
484
485********
486Humidity
487********
488
489`humidity[1-*]_input`
490		Humidity.
491
492`humidity[1-*]_enable`
493		Enable or disable the sensors.
494
495`humidity[1-*]_rated_min`
496		Minimum rated humidity.
497
498`humidity[1-*]_rated_max`
499		Maximum rated humidity.
500
501******
502Alarms
503******
504
505Each channel or limit may have an associated alarm file, containing a
506boolean value. 1 means than an alarm condition exists, 0 means no alarm.
507
508Usually a given chip will either use channel-related alarms, or
509limit-related alarms, not both. The driver should just reflect the hardware
510implementation.
511
512+-------------------------------+-----------------------+
513| **`in[0-*]_alarm`,		| Channel alarm		|
514| `curr[1-*]_alarm`,		|			|
515| `power[1-*]_alarm`,		|   - 0: no alarm	|
516| `fan[1-*]_alarm`,		|   - 1: alarm		|
517| `temp[1-*]_alarm`**		|			|
518|				|   RO			|
519+-------------------------------+-----------------------+
520
521**OR**
522
523+-------------------------------+-----------------------+
524| **`in[0-*]_min_alarm`,	| Limit alarm		|
525| `in[0-*]_max_alarm`,		|			|
526| `in[0-*]_lcrit_alarm`,	|   - 0: no alarm	|
527| `in[0-*]_crit_alarm`,		|   - 1: alarm		|
528| `curr[1-*]_min_alarm`,	|			|
529| `curr[1-*]_max_alarm`,	| RO			|
530| `curr[1-*]_lcrit_alarm`,	|			|
531| `curr[1-*]_crit_alarm`,	|			|
532| `power[1-*]_cap_alarm`,	|			|
533| `power[1-*]_max_alarm`,	|			|
534| `power[1-*]_crit_alarm`,	|			|
535| `fan[1-*]_min_alarm`,		|			|
536| `fan[1-*]_max_alarm`,		|			|
537| `temp[1-*]_min_alarm`,	|			|
538| `temp[1-*]_max_alarm`,	|			|
539| `temp[1-*]_lcrit_alarm`,	|			|
540| `temp[1-*]_crit_alarm`,	|			|
541| `temp[1-*]_emergency_alarm`**	|			|
542+-------------------------------+-----------------------+
543
544Each input channel may have an associated fault file. This can be used
545to notify open diodes, unconnected fans etc. where the hardware
546supports it. When this boolean has value 1, the measurement for that
547channel should not be trusted.
548
549`fan[1-*]_fault` / `temp[1-*]_fault`
550		Input fault condition.
551
552Some chips also offer the possibility to get beeped when an alarm occurs:
553
554`beep_enable`
555		Master beep enable.
556
557`in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`,
558		Channel beep.
559
560In theory, a chip could provide per-limit beep masking, but no such chip
561was seen so far.
562
563Old drivers provided a different, non-standard interface to alarms and
564beeps. These interface files are deprecated, but will be kept around
565for compatibility reasons:
566
567`alarms`
568		Alarm bitmask.
569
570`beep_mask`
571		Bitmask for beep.
572
573
574*******************
575Intrusion detection
576*******************
577
578`intrusion[0-*]_alarm`
579		Chassis intrusion detection.
580
581`intrusion[0-*]_beep`
582		Chassis intrusion beep.
583
584****************************
585Average sample configuration
586****************************
587
588Devices allowing for reading {in,power,curr,temp}_average values may export
589attributes for controlling number of samples used to compute average.
590
591+--------------+---------------------------------------------------------------+
592| samples      | Sets number of average samples for all types of measurements. |
593|	       |							       |
594|	       | RW							       |
595+--------------+---------------------------------------------------------------+
596| in_samples   | Sets number of average samples for specific type of	       |
597| power_samples| measurements.						       |
598| curr_samples |							       |
599| temp_samples | Note that on some devices it won't be possible to set all of  |
600|	       | them to different values so changing one might also change    |
601|	       | some others.						       |
602|	       |							       |
603|	       | RW							       |
604+--------------+---------------------------------------------------------------+
605
606sysfs attribute writes interpretation
607-------------------------------------
608
609hwmon sysfs attributes always contain numbers, so the first thing to do is to
610convert the input to a number, there are 2 ways todo this depending whether
611the number can be negative or not::
612
613	unsigned long u = simple_strtoul(buf, NULL, 10);
614	long s = simple_strtol(buf, NULL, 10);
615
616With buf being the buffer with the user input being passed by the kernel.
617Notice that we do not use the second argument of strto[u]l, and thus cannot
618tell when 0 is returned, if this was really 0 or is caused by invalid input.
619This is done deliberately as checking this everywhere would add a lot of
620code to the kernel.
621
622Notice that it is important to always store the converted value in an
623unsigned long or long, so that no wrap around can happen before any further
624checking.
625
626After the input string is converted to an (unsigned) long, the value should be
627checked if its acceptable. Be careful with further conversions on the value
628before checking it for validity, as these conversions could still cause a wrap
629around before the check. For example do not multiply the result, and only
630add/subtract if it has been divided before the add/subtract.
631
632What to do if a value is found to be invalid, depends on the type of the
633sysfs attribute that is being set. If it is a continuous setting like a
634tempX_max or inX_max attribute, then the value should be clamped to its
635limits using clamp_val(value, min_limit, max_limit). If it is not continuous
636like for example a tempX_type, then when an invalid value is written,
637-EINVAL should be returned.
638
639Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees)::
640
641	long v = simple_strtol(buf, NULL, 10) / 1000;
642	v = clamp_val(v, -128, 127);
643	/* write v to register */
644
645Example2, fan divider setting, valid values 2, 4 and 8::
646
647	unsigned long v = simple_strtoul(buf, NULL, 10);
648
649	switch (v) {
650	case 2: v = 1; break;
651	case 4: v = 2; break;
652	case 8: v = 3; break;
653	default:
654		return -EINVAL;
655	}
656	/* write v to register */