Loading...
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 */
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
68-------------------------------------------------------------------------
69
70======= ===========================================
71`[0-*]` denotes any positive number starting from 0
72`[1-*]` denotes any positive number starting from 1
73RO read only value
74WO write only value
75RW read/write value
76======= ===========================================
77
78Read/write values may be read-only for some chips, depending on the
79hardware implementation.
80
81All entries (except name) are optional, and should only be created in a
82given driver if the chip has the feature.
83
84
85*****************
86Global attributes
87*****************
88
89`name`
90 The chip name.
91 This should be a short, lowercase string, not containing
92 whitespace, dashes, or the wildcard character '*'.
93 This attribute represents the chip name. It is the only
94 mandatory attribute.
95 I2C devices get this attribute created automatically.
96
97 RO
98
99`update_interval`
100 The interval at which the chip will update readings.
101 Unit: millisecond
102
103 RW
104
105 Some devices have a variable update rate or interval.
106 This attribute can be used to change it to the desired value.
107
108
109********
110Voltages
111********
112
113`in[0-*]_min`
114 Voltage min value.
115
116 Unit: millivolt
117
118 RW
119
120`in[0-*]_lcrit`
121 Voltage critical min value.
122
123 Unit: millivolt
124
125 RW
126
127 If voltage drops to or below this limit, the system may
128 take drastic action such as power down or reset. At the very
129 least, it should report a fault.
130
131`in[0-*]_max`
132 Voltage max value.
133
134 Unit: millivolt
135
136 RW
137
138`in[0-*]_crit`
139 Voltage critical max value.
140
141 Unit: millivolt
142
143 RW
144
145 If voltage reaches or exceeds this limit, the system may
146 take drastic action such as power down or reset. At the very
147 least, it should report a fault.
148
149`in[0-*]_input`
150 Voltage input value.
151
152 Unit: millivolt
153
154 RO
155
156 Voltage measured on the chip pin.
157
158 Actual voltage depends on the scaling resistors on the
159 motherboard, as recommended in the chip datasheet.
160
161 This varies by chip and by motherboard.
162 Because of this variation, values are generally NOT scaled
163 by the chip driver, and must be done by the application.
164 However, some drivers (notably lm87 and via686a)
165 do scale, because of internal resistors built into a chip.
166 These drivers will output the actual voltage. Rule of
167 thumb: drivers should report the voltage values at the
168 "pins" of the chip.
169
170`in[0-*]_average`
171 Average voltage
172
173 Unit: millivolt
174
175 RO
176
177`in[0-*]_lowest`
178 Historical minimum voltage
179
180 Unit: millivolt
181
182 RO
183
184`in[0-*]_highest`
185 Historical maximum voltage
186
187 Unit: millivolt
188
189 RO
190
191`in[0-*]_reset_history`
192 Reset inX_lowest and inX_highest
193
194 WO
195
196`in_reset_history`
197 Reset inX_lowest and inX_highest for all sensors
198
199 WO
200
201`in[0-*]_label`
202 Suggested voltage channel label.
203
204 Text string
205
206 Should only be created if the driver has hints about what
207 this voltage channel is being used for, and user-space
208 doesn't. In all other cases, the label is provided by
209 user-space.
210
211 RO
212
213`in[0-*]_enable`
214 Enable or disable the sensors.
215
216 When disabled the sensor read will return -ENODATA.
217
218 - 1: Enable
219 - 0: Disable
220
221 RW
222
223`cpu[0-*]_vid`
224 CPU core reference voltage.
225
226 Unit: millivolt
227
228 RO
229
230 Not always correct.
231
232`vrm`
233 Voltage Regulator Module version number.
234
235 RW (but changing it should no more be necessary)
236
237 Originally the VRM standard version multiplied by 10, but now
238 an arbitrary number, as not all standards have a version
239 number.
240
241 Affects the way the driver calculates the CPU core reference
242 voltage from the vid pins.
243
244Also see the Alarms section for status flags associated with voltages.
245
246
247****
248Fans
249****
250
251`fan[1-*]_min`
252 Fan minimum value
253
254 Unit: revolution/min (RPM)
255
256 RW
257
258`fan[1-*]_max`
259 Fan maximum value
260
261 Unit: revolution/min (RPM)
262
263 Only rarely supported by the hardware.
264 RW
265
266`fan[1-*]_input`
267 Fan input value.
268
269 Unit: revolution/min (RPM)
270
271 RO
272
273`fan[1-*]_div`
274 Fan divisor.
275
276 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
277
278 RW
279
280 Some chips only support values 1, 2, 4 and 8.
281 Note that this is actually an internal clock divisor, which
282 affects the measurable speed range, not the read value.
283
284`fan[1-*]_pulses`
285 Number of tachometer pulses per fan revolution.
286
287 Integer value, typically between 1 and 4.
288
289 RW
290
291 This value is a characteristic of the fan connected to the
292 device's input, so it has to be set in accordance with the fan
293 model.
294
295 Should only be created if the chip has a register to configure
296 the number of pulses. In the absence of such a register (and
297 thus attribute) the value assumed by all devices is 2 pulses
298 per fan revolution.
299
300`fan[1-*]_target`
301 Desired fan speed
302
303 Unit: revolution/min (RPM)
304
305 RW
306
307 Only makes sense if the chip supports closed-loop fan speed
308 control based on the measured fan speed.
309
310`fan[1-*]_label`
311 Suggested fan channel label.
312
313 Text string
314
315 Should only be created if the driver has hints about what
316 this fan channel is being used for, and user-space doesn't.
317 In all other cases, the label is provided by user-space.
318
319 RO
320
321`fan[1-*]_enable`
322 Enable or disable the sensors.
323
324 When disabled the sensor read will return -ENODATA.
325
326 - 1: Enable
327 - 0: Disable
328
329 RW
330
331Also see the Alarms section for status flags associated with fans.
332
333
334***
335PWM
336***
337
338`pwm[1-*]`
339 Pulse width modulation fan control.
340
341 Integer value in the range 0 to 255
342
343 RW
344
345 255 is max or 100%.
346
347`pwm[1-*]_enable`
348 Fan speed control method:
349
350 - 0: no fan speed control (i.e. fan at full speed)
351 - 1: manual fan speed control enabled (using `pwm[1-*]`)
352 - 2+: automatic fan speed control enabled
353
354 Check individual chip documentation files for automatic mode
355 details.
356
357 RW
358
359`pwm[1-*]_mode`
360 - 0: DC mode (direct current)
361 - 1: PWM mode (pulse-width modulation)
362
363 RW
364
365`pwm[1-*]_freq`
366 Base PWM frequency in Hz.
367
368 Only possibly available when pwmN_mode is PWM, but not always
369 present even then.
370
371 RW
372
373`pwm[1-*]_auto_channels_temp`
374 Select which temperature channels affect this PWM output in
375 auto mode.
376
377 Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
378 Which values are possible depend on the chip used.
379
380 RW
381
382`pwm[1-*]_auto_point[1-*]_pwm` / `pwm[1-*]_auto_point[1-*]_temp` / `pwm[1-*]_auto_point[1-*]_temp_hyst`
383 Define the PWM vs temperature curve.
384
385 Number of trip points is chip-dependent. Use this for chips
386 which associate trip points to PWM output channels.
387
388 RW
389
390`temp[1-*]_auto_point[1-*]_pwm` / `temp[1-*]_auto_point[1-*]_temp` / `temp[1-*]_auto_point[1-*]_temp_hyst`
391 Define the PWM vs temperature curve.
392
393 Number of trip points is chip-dependent. Use this for chips
394 which associate trip points to temperature channels.
395
396 RW
397
398There is a third case where trip points are associated to both PWM output
399channels and temperature channels: the PWM values are associated to PWM
400output channels while the temperature values are associated to temperature
401channels. In that case, the result is determined by the mapping between
402temperature inputs and PWM outputs. When several temperature inputs are
403mapped to a given PWM output, this leads to several candidate PWM values.
404The actual result is up to the chip, but in general the highest candidate
405value (fastest fan speed) wins.
406
407
408************
409Temperatures
410************
411
412`temp[1-*]_type`
413 Sensor type selection.
414
415 Integers 1 to 6
416
417 RW
418
419 - 1: CPU embedded diode
420 - 2: 3904 transistor
421 - 3: thermal diode
422 - 4: thermistor
423 - 5: AMD AMDSI
424 - 6: Intel PECI
425
426 Not all types are supported by all chips
427
428`temp[1-*]_max`
429 Temperature max value.
430
431 Unit: millidegree Celsius (or millivolt, see below)
432
433 RW
434
435`temp[1-*]_min`
436 Temperature min value.
437
438 Unit: millidegree Celsius
439
440 RW
441
442`temp[1-*]_max_hyst`
443 Temperature hysteresis value for max limit.
444
445 Unit: millidegree Celsius
446
447 Must be reported as an absolute temperature, NOT a delta
448 from the max value.
449
450 RW
451
452`temp[1-*]_min_hyst`
453 Temperature hysteresis value for min limit.
454 Unit: millidegree Celsius
455
456 Must be reported as an absolute temperature, NOT a delta
457 from the min value.
458
459 RW
460
461`temp[1-*]_input`
462 Temperature input value.
463
464 Unit: millidegree Celsius
465
466 RO
467
468`temp[1-*]_crit`
469 Temperature critical max value, typically greater than
470 corresponding temp_max values.
471
472 Unit: millidegree Celsius
473
474 RW
475
476`temp[1-*]_crit_hyst`
477 Temperature hysteresis value for critical limit.
478
479 Unit: millidegree Celsius
480
481 Must be reported as an absolute temperature, NOT a delta
482 from the critical value.
483
484 RW
485
486`temp[1-*]_emergency`
487 Temperature emergency max value, for chips supporting more than
488 two upper temperature limits. Must be equal or greater than
489 corresponding temp_crit values.
490
491 Unit: millidegree Celsius
492
493 RW
494
495`temp[1-*]_emergency_hyst`
496 Temperature hysteresis value for emergency limit.
497
498 Unit: millidegree Celsius
499
500 Must be reported as an absolute temperature, NOT a delta
501 from the emergency value.
502
503 RW
504
505`temp[1-*]_lcrit`
506 Temperature critical min value, typically lower than
507 corresponding temp_min values.
508
509 Unit: millidegree Celsius
510
511 RW
512
513`temp[1-*]_lcrit_hyst`
514 Temperature hysteresis value for critical min limit.
515
516 Unit: millidegree Celsius
517
518 Must be reported as an absolute temperature, NOT a delta
519 from the critical min value.
520
521 RW
522
523`temp[1-*]_offset`
524 Temperature offset which is added to the temperature reading
525 by the chip.
526
527 Unit: millidegree Celsius
528
529 Read/Write value.
530
531`temp[1-*]_label`
532 Suggested temperature channel label.
533
534 Text string
535
536 Should only be created if the driver has hints about what
537 this temperature channel is being used for, and user-space
538 doesn't. In all other cases, the label is provided by
539 user-space.
540
541 RO
542
543`temp[1-*]_lowest`
544 Historical minimum temperature
545
546 Unit: millidegree Celsius
547
548 RO
549
550`temp[1-*]_highest`
551 Historical maximum temperature
552
553 Unit: millidegree Celsius
554
555 RO
556
557`temp[1-*]_reset_history`
558 Reset temp_lowest and temp_highest
559
560 WO
561
562`temp_reset_history`
563 Reset temp_lowest and temp_highest for all sensors
564
565 WO
566
567`temp[1-*]_enable`
568 Enable or disable the sensors.
569
570 When disabled the sensor read will return -ENODATA.
571
572 - 1: Enable
573 - 0: Disable
574
575 RW
576
577Some chips measure temperature using external thermistors and an ADC, and
578report the temperature measurement as a voltage. Converting this voltage
579back to a temperature (or the other way around for limits) requires
580mathematical functions not available in the kernel, so the conversion
581must occur in user space. For these chips, all temp* files described
582above should contain values expressed in millivolt instead of millidegree
583Celsius. In other words, such temperature channels are handled as voltage
584channels by the driver.
585
586Also see the Alarms section for status flags associated with temperatures.
587
588
589********
590Currents
591********
592
593`curr[1-*]_max`
594 Current max value
595
596 Unit: milliampere
597
598 RW
599
600`curr[1-*]_min`
601 Current min value.
602
603 Unit: milliampere
604
605 RW
606
607`curr[1-*]_lcrit`
608 Current critical low value
609
610 Unit: milliampere
611
612 RW
613
614`curr[1-*]_crit`
615 Current critical high value.
616
617 Unit: milliampere
618
619 RW
620
621`curr[1-*]_input`
622 Current input value
623
624 Unit: milliampere
625
626 RO
627
628`curr[1-*]_average`
629 Average current use
630
631 Unit: milliampere
632
633 RO
634
635`curr[1-*]_lowest`
636 Historical minimum current
637
638 Unit: milliampere
639
640 RO
641
642`curr[1-*]_highest`
643 Historical maximum current
644 Unit: milliampere
645 RO
646
647`curr[1-*]_reset_history`
648 Reset currX_lowest and currX_highest
649
650 WO
651
652`curr_reset_history`
653 Reset currX_lowest and currX_highest for all sensors
654
655 WO
656
657`curr[1-*]_enable`
658 Enable or disable the sensors.
659
660 When disabled the sensor read will return -ENODATA.
661
662 - 1: Enable
663 - 0: Disable
664
665 RW
666
667Also see the Alarms section for status flags associated with currents.
668
669*****
670Power
671*****
672
673`power[1-*]_average`
674 Average power use
675
676 Unit: microWatt
677
678 RO
679
680`power[1-*]_average_interval`
681 Power use averaging interval. A poll
682 notification is sent to this file if the
683 hardware changes the averaging interval.
684
685 Unit: milliseconds
686
687 RW
688
689`power[1-*]_average_interval_max`
690 Maximum power use averaging interval
691
692 Unit: milliseconds
693
694 RO
695
696`power[1-*]_average_interval_min`
697 Minimum power use averaging interval
698
699 Unit: milliseconds
700
701 RO
702
703`power[1-*]_average_highest`
704 Historical average maximum power use
705
706 Unit: microWatt
707
708 RO
709
710`power[1-*]_average_lowest`
711 Historical average minimum power use
712
713 Unit: microWatt
714
715 RO
716
717`power[1-*]_average_max`
718 A poll notification is sent to
719 `power[1-*]_average` when power use
720 rises above this value.
721
722 Unit: microWatt
723
724 RW
725
726`power[1-*]_average_min`
727 A poll notification is sent to
728 `power[1-*]_average` when power use
729 sinks below this value.
730
731 Unit: microWatt
732
733 RW
734
735`power[1-*]_input`
736 Instantaneous power use
737
738 Unit: microWatt
739
740 RO
741
742`power[1-*]_input_highest`
743 Historical maximum power use
744
745 Unit: microWatt
746
747 RO
748
749`power[1-*]_input_lowest`
750 Historical minimum power use
751
752 Unit: microWatt
753
754 RO
755
756`power[1-*]_reset_history`
757 Reset input_highest, input_lowest,
758 average_highest and average_lowest.
759
760 WO
761
762`power[1-*]_accuracy`
763 Accuracy of the power meter.
764
765 Unit: Percent
766
767 RO
768
769`power[1-*]_cap`
770 If power use rises above this limit, the
771 system should take action to reduce power use.
772 A poll notification is sent to this file if the
773 cap is changed by the hardware. The `*_cap`
774 files only appear if the cap is known to be
775 enforced by hardware.
776
777 Unit: microWatt
778
779 RW
780
781`power[1-*]_cap_hyst`
782 Margin of hysteresis built around capping and
783 notification.
784
785 Unit: microWatt
786
787 RW
788
789`power[1-*]_cap_max`
790 Maximum cap that can be set.
791
792 Unit: microWatt
793
794 RO
795
796`power[1-*]_cap_min`
797 Minimum cap that can be set.
798
799 Unit: microWatt
800
801 RO
802
803`power[1-*]_max`
804 Maximum power.
805
806 Unit: microWatt
807
808 RW
809
810`power[1-*]_crit`
811 Critical maximum power.
812
813 If power rises to or above this limit, the
814 system is expected take drastic action to reduce
815 power consumption, such as a system shutdown or
816 a forced powerdown of some devices.
817
818 Unit: microWatt
819
820 RW
821
822`power[1-*]_enable`
823 Enable or disable the sensors.
824
825 When disabled the sensor read will return
826 -ENODATA.
827
828 - 1: Enable
829 - 0: Disable
830
831 RW
832
833Also see the Alarms section for status flags associated with power readings.
834
835******
836Energy
837******
838
839`energy[1-*]_input`
840 Cumulative energy use
841
842 Unit: microJoule
843
844 RO
845
846`energy[1-*]_enable`
847 Enable or disable the sensors.
848
849 When disabled the sensor read will return
850 -ENODATA.
851
852 - 1: Enable
853 - 0: Disable
854
855 RW
856
857********
858Humidity
859********
860
861`humidity[1-*]_input`
862 Humidity
863
864 Unit: milli-percent (per cent mille, pcm)
865
866 RO
867
868
869`humidity[1-*]_enable`
870 Enable or disable the sensors
871
872 When disabled the sensor read will return
873 -ENODATA.
874
875 - 1: Enable
876 - 0: Disable
877
878 RW
879
880******
881Alarms
882******
883
884Each channel or limit may have an associated alarm file, containing a
885boolean value. 1 means than an alarm condition exists, 0 means no alarm.
886
887Usually a given chip will either use channel-related alarms, or
888limit-related alarms, not both. The driver should just reflect the hardware
889implementation.
890
891+-------------------------------+-----------------------+
892| **`in[0-*]_alarm`, | Channel alarm |
893| `curr[1-*]_alarm`, | |
894| `power[1-*]_alarm`, | - 0: no alarm |
895| `fan[1-*]_alarm`, | - 1: alarm |
896| `temp[1-*]_alarm`** | |
897| | RO |
898+-------------------------------+-----------------------+
899
900**OR**
901
902+-------------------------------+-----------------------+
903| **`in[0-*]_min_alarm`, | Limit alarm |
904| `in[0-*]_max_alarm`, | |
905| `in[0-*]_lcrit_alarm`, | - 0: no alarm |
906| `in[0-*]_crit_alarm`, | - 1: alarm |
907| `curr[1-*]_min_alarm`, | |
908| `curr[1-*]_max_alarm`, | RO |
909| `curr[1-*]_lcrit_alarm`, | |
910| `curr[1-*]_crit_alarm`, | |
911| `power[1-*]_cap_alarm`, | |
912| `power[1-*]_max_alarm`, | |
913| `power[1-*]_crit_alarm`, | |
914| `fan[1-*]_min_alarm`, | |
915| `fan[1-*]_max_alarm`, | |
916| `temp[1-*]_min_alarm`, | |
917| `temp[1-*]_max_alarm`, | |
918| `temp[1-*]_lcrit_alarm`, | |
919| `temp[1-*]_crit_alarm`, | |
920| `temp[1-*]_emergency_alarm`** | |
921+-------------------------------+-----------------------+
922
923Each input channel may have an associated fault file. This can be used
924to notify open diodes, unconnected fans etc. where the hardware
925supports it. When this boolean has value 1, the measurement for that
926channel should not be trusted.
927
928`fan[1-*]_fault` / `temp[1-*]_fault`
929 Input fault condition
930
931 - 0: no fault occurred
932 - 1: fault condition
933
934 RO
935
936Some chips also offer the possibility to get beeped when an alarm occurs:
937
938`beep_enable`
939 Master beep enable
940
941 - 0: no beeps
942 - 1: beeps
943
944 RW
945
946`in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`,
947 Channel beep
948
949 - 0: disable
950 - 1: enable
951
952 RW
953
954In theory, a chip could provide per-limit beep masking, but no such chip
955was seen so far.
956
957Old drivers provided a different, non-standard interface to alarms and
958beeps. These interface files are deprecated, but will be kept around
959for compatibility reasons:
960
961`alarms`
962 Alarm bitmask.
963
964 RO
965
966 Integer representation of one to four bytes.
967
968 A '1' bit means an alarm.
969
970 Chips should be programmed for 'comparator' mode so that
971 the alarm will 'come back' after you read the register
972 if it is still valid.
973
974 Generally a direct representation of a chip's internal
975 alarm registers; there is no standard for the position
976 of individual bits. For this reason, the use of this
977 interface file for new drivers is discouraged. Use
978 `individual *_alarm` and `*_fault` files instead.
979 Bits are defined in kernel/include/sensors.h.
980
981`beep_mask`
982 Bitmask for beep.
983 Same format as 'alarms' with the same bit locations,
984 use discouraged for the same reason. Use individual
985 `*_beep` files instead.
986 RW
987
988
989*******************
990Intrusion detection
991*******************
992
993`intrusion[0-*]_alarm`
994 Chassis intrusion detection
995
996 - 0: OK
997 - 1: intrusion detected
998
999 RW
1000
1001 Contrary to regular alarm flags which clear themselves
1002 automatically when read, this one sticks until cleared by
1003 the user. This is done by writing 0 to the file. Writing
1004 other values is unsupported.
1005
1006`intrusion[0-*]_beep`
1007 Chassis intrusion beep
1008
1009 0: disable
1010 1: enable
1011
1012 RW
1013
1014****************************
1015Average sample configuration
1016****************************
1017
1018Devices allowing for reading {in,power,curr,temp}_average values may export
1019attributes for controlling number of samples used to compute average.
1020
1021+--------------+---------------------------------------------------------------+
1022| samples | Sets number of average samples for all types of measurements. |
1023| | |
1024| | RW |
1025+--------------+---------------------------------------------------------------+
1026| in_samples | Sets number of average samples for specific type of |
1027| power_samples| measurements. |
1028| curr_samples | |
1029| temp_samples | Note that on some devices it won't be possible to set all of |
1030| | them to different values so changing one might also change |
1031| | some others. |
1032| | |
1033| | RW |
1034+--------------+---------------------------------------------------------------+
1035
1036sysfs attribute writes interpretation
1037-------------------------------------
1038
1039hwmon sysfs attributes always contain numbers, so the first thing to do is to
1040convert the input to a number, there are 2 ways todo this depending whether
1041the number can be negative or not::
1042
1043 unsigned long u = simple_strtoul(buf, NULL, 10);
1044 long s = simple_strtol(buf, NULL, 10);
1045
1046With buf being the buffer with the user input being passed by the kernel.
1047Notice that we do not use the second argument of strto[u]l, and thus cannot
1048tell when 0 is returned, if this was really 0 or is caused by invalid input.
1049This is done deliberately as checking this everywhere would add a lot of
1050code to the kernel.
1051
1052Notice that it is important to always store the converted value in an
1053unsigned long or long, so that no wrap around can happen before any further
1054checking.
1055
1056After the input string is converted to an (unsigned) long, the value should be
1057checked if its acceptable. Be careful with further conversions on the value
1058before checking it for validity, as these conversions could still cause a wrap
1059around before the check. For example do not multiply the result, and only
1060add/subtract if it has been divided before the add/subtract.
1061
1062What to do if a value is found to be invalid, depends on the type of the
1063sysfs attribute that is being set. If it is a continuous setting like a
1064tempX_max or inX_max attribute, then the value should be clamped to its
1065limits using clamp_val(value, min_limit, max_limit). If it is not continuous
1066like for example a tempX_type, then when an invalid value is written,
1067-EINVAL should be returned.
1068
1069Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees)::
1070
1071 long v = simple_strtol(buf, NULL, 10) / 1000;
1072 v = clamp_val(v, -128, 127);
1073 /* write v to register */
1074
1075Example2, fan divider setting, valid values 2, 4 and 8::
1076
1077 unsigned long v = simple_strtoul(buf, NULL, 10);
1078
1079 switch (v) {
1080 case 2: v = 1; break;
1081 case 4: v = 2; break;
1082 case 8: v = 3; break;
1083 default:
1084 return -EINVAL;
1085 }
1086 /* write v to register */