0001 Naming and data format standards for sysfs files
0002 ================================================
0003
0004 The libsensors library offers an interface to the raw sensors data
0005 through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
0006 completely chip-independent. It assumes that all the kernel drivers
0007 implement the standard sysfs interface described in this document.
0008 This makes adding or updating support for any given chip very easy, as
0009 libsensors, and applications using it, do not need to be modified.
0010 This is a major improvement compared to lm-sensors 2.
0011
0012 Note that motherboards vary widely in the connections to sensor chips.
0013 There is no standard that ensures, for example, that the second
0014 temperature sensor is connected to the CPU, or that the second fan is on
0015 the CPU. Also, some values reported by the chips need some computation
0016 before they make full sense. For example, most chips can only measure
0017 voltages between 0 and +4V. Other voltages are scaled back into that
0018 range using external resistors. Since the values of these resistors
0019 can change from motherboard to motherboard, the conversions cannot be
0020 hard coded into the driver and have to be done in user space.
0021
0022 For this reason, even if we aim at a chip-independent libsensors, it will
0023 still require a configuration file (e.g. /etc/sensors.conf) for proper
0024 values conversion, labeling of inputs and hiding of unused inputs.
0025
0026 An alternative method that some programs use is to access the sysfs
0027 files directly. This document briefly describes the standards that the
0028 drivers follow, so that an application program can scan for entries and
0029 access this data in a simple and consistent way. That said, such programs
0030 will have to implement conversion, labeling and hiding of inputs. For
0031 this reason, it is still not recommended to bypass the library.
0032
0033 Each chip gets its own directory in the sysfs /sys/devices tree. To
0034 find all sensor chips, it is easier to follow the device symlinks from
0035 `/sys/class/hwmon/hwmon*`.
0036
0037 Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
0038 in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
0039 in the hwmon "class" device directory are also supported. Complex drivers
0040 (e.g. drivers for multifunction chips) may want to use this possibility to
0041 avoid namespace pollution. The only drawback will be that older versions of
0042 libsensors won't support the driver in question.
0043
0044 All sysfs values are fixed point numbers.
0045
0046 There is only one value per file, unlike the older /proc specification.
0047 The common scheme for files naming is: <type><number>_<item>. Usual
0048 types for sensor chips are "in" (voltage), "temp" (temperature) and
0049 "fan" (fan). Usual items are "input" (measured value), "max" (high
0050 threshold, "min" (low threshold). Numbering usually starts from 1,
0051 except for voltages which start from 0 (because most data sheets use
0052 this). A number is always used for elements that can be present more
0053 than once, even if there is a single element of the given type on the
0054 specific chip. Other files do not refer to a specific element, so
0055 they have a simple name, and no number.
0056
0057 Alarms are direct indications read from the chips. The drivers do NOT
0058 make comparisons of readings to thresholds. This allows violations
0059 between readings to be caught and alarmed. The exact definition of an
0060 alarm (for example, whether a threshold must be met or must be exceeded
0061 to cause an alarm) is chip-dependent.
0062
0063 When setting values of hwmon sysfs attributes, the string representation of
0064 the desired value must be written, note that strings which are not a number
0065 are interpreted as 0! For more on how written strings are interpreted see the
0066 "sysfs attribute writes interpretation" section at the end of this file.
0067
0068 Attribute access
0069 ----------------
0070
0071 Hardware monitoring sysfs attributes are displayed by unrestricted userspace
0072 applications. For this reason, all standard ABI attributes shall be world
0073 readable. Writeable standard ABI attributes shall be writeable only for
0074 privileged users.
0075
0076 -------------------------------------------------------------------------
0077
0078 ======= ===========================================
0079 `[0-*]` denotes any positive number starting from 0
0080 `[1-*]` denotes any positive number starting from 1
0081 RO read only value
0082 WO write only value
0083 RW read/write value
0084 ======= ===========================================
0085
0086 Read/write values may be read-only for some chips, depending on the
0087 hardware implementation.
0088
0089 All entries (except name) are optional, and should only be created in a
0090 given driver if the chip has the feature.
0091
0092 See Documentation/ABI/testing/sysfs-class-hwmon for a complete description
0093 of the attributes.
0094
0095 *****************
0096 Global attributes
0097 *****************
0098
0099 `name`
0100 The chip name.
0101
0102 `label`
0103 A descriptive label that allows to uniquely identify a device
0104 within the system.
0105
0106 `update_interval`
0107 The interval at which the chip will update readings.
0108
0109
0110 ********
0111 Voltages
0112 ********
0113
0114 `in[0-*]_min`
0115 Voltage min value.
0116
0117 `in[0-*]_lcrit`
0118 Voltage critical min value.
0119
0120 `in[0-*]_max`
0121 Voltage max value.
0122
0123 `in[0-*]_crit`
0124 Voltage critical max value.
0125
0126 `in[0-*]_input`
0127 Voltage input value.
0128
0129 `in[0-*]_average`
0130 Average voltage
0131
0132 `in[0-*]_lowest`
0133 Historical minimum voltage
0134
0135 `in[0-*]_highest`
0136 Historical maximum voltage
0137
0138 `in[0-*]_reset_history`
0139 Reset inX_lowest and inX_highest
0140
0141 `in_reset_history`
0142 Reset inX_lowest and inX_highest for all sensors
0143
0144 `in[0-*]_label`
0145 Suggested voltage channel label.
0146
0147 `in[0-*]_enable`
0148 Enable or disable the sensors.
0149
0150 `cpu[0-*]_vid`
0151 CPU core reference voltage.
0152
0153 `vrm`
0154 Voltage Regulator Module version number.
0155
0156 `in[0-*]_rated_min`
0157 Minimum rated voltage.
0158
0159 `in[0-*]_rated_max`
0160 Maximum rated voltage.
0161
0162 Also see the Alarms section for status flags associated with voltages.
0163
0164
0165 ****
0166 Fans
0167 ****
0168
0169 `fan[1-*]_min`
0170 Fan minimum value
0171
0172 `fan[1-*]_max`
0173 Fan maximum value
0174
0175 `fan[1-*]_input`
0176 Fan input value.
0177
0178 `fan[1-*]_div`
0179 Fan divisor.
0180
0181 `fan[1-*]_pulses`
0182 Number of tachometer pulses per fan revolution.
0183
0184 `fan[1-*]_target`
0185 Desired fan speed
0186
0187 `fan[1-*]_label`
0188 Suggested fan channel label.
0189
0190 `fan[1-*]_enable`
0191 Enable or disable the sensors.
0192
0193 Also see the Alarms section for status flags associated with fans.
0194
0195
0196 ***
0197 PWM
0198 ***
0199
0200 `pwm[1-*]`
0201 Pulse width modulation fan control.
0202
0203 `pwm[1-*]_enable`
0204 Fan speed control method:
0205
0206 `pwm[1-*]_mode`
0207 direct current or pulse-width modulation.
0208
0209 `pwm[1-*]_freq`
0210 Base PWM frequency in Hz.
0211
0212 `pwm[1-*]_auto_channels_temp`
0213 Select which temperature channels affect this PWM output in
0214 auto mode.
0215
0216 `pwm[1-*]_auto_point[1-*]_pwm` / `pwm[1-*]_auto_point[1-*]_temp` / `pwm[1-*]_auto_point[1-*]_temp_hyst`
0217 Define the PWM vs temperature curve.
0218
0219 `temp[1-*]_auto_point[1-*]_pwm` / `temp[1-*]_auto_point[1-*]_temp` / `temp[1-*]_auto_point[1-*]_temp_hyst`
0220 Define the PWM vs temperature curve.
0221
0222 There is a third case where trip points are associated to both PWM output
0223 channels and temperature channels: the PWM values are associated to PWM
0224 output channels while the temperature values are associated to temperature
0225 channels. In that case, the result is determined by the mapping between
0226 temperature inputs and PWM outputs. When several temperature inputs are
0227 mapped to a given PWM output, this leads to several candidate PWM values.
0228 The actual result is up to the chip, but in general the highest candidate
0229 value (fastest fan speed) wins.
0230
0231
0232 ************
0233 Temperatures
0234 ************
0235
0236 `temp[1-*]_type`
0237 Sensor type selection.
0238
0239 `temp[1-*]_max`
0240 Temperature max value.
0241
0242 `temp[1-*]_min`
0243 Temperature min value.
0244
0245 `temp[1-*]_max_hyst`
0246 Temperature hysteresis value for max limit.
0247
0248 `temp[1-*]_min_hyst`
0249 Temperature hysteresis value for min limit.
0250
0251 `temp[1-*]_input`
0252 Temperature input value.
0253
0254 `temp[1-*]_crit`
0255 Temperature critical max value, typically greater than
0256 corresponding temp_max values.
0257
0258 `temp[1-*]_crit_hyst`
0259 Temperature hysteresis value for critical limit.
0260
0261 `temp[1-*]_emergency`
0262 Temperature emergency max value, for chips supporting more than
0263 two upper temperature limits.
0264
0265 `temp[1-*]_emergency_hyst`
0266 Temperature hysteresis value for emergency limit.
0267
0268 `temp[1-*]_lcrit`
0269 Temperature critical min value, typically lower than
0270 corresponding temp_min values.
0271
0272 `temp[1-*]_lcrit_hyst`
0273 Temperature hysteresis value for critical min limit.
0274
0275 `temp[1-*]_offset`
0276 Temperature offset which is added to the temperature reading
0277 by the chip.
0278
0279 `temp[1-*]_label`
0280 Suggested temperature channel label.
0281
0282 `temp[1-*]_lowest`
0283 Historical minimum temperature
0284
0285 `temp[1-*]_highest`
0286 Historical maximum temperature
0287
0288 `temp[1-*]_reset_history`
0289 Reset temp_lowest and temp_highest
0290
0291 `temp_reset_history`
0292 Reset temp_lowest and temp_highest for all sensors
0293
0294 `temp[1-*]_enable`
0295 Enable or disable the sensors.
0296
0297 `temp[1-*]_rated_min`
0298 Minimum rated temperature.
0299
0300 `temp[1-*]_rated_max`
0301 Maximum rated temperature.
0302
0303 Some chips measure temperature using external thermistors and an ADC, and
0304 report the temperature measurement as a voltage. Converting this voltage
0305 back to a temperature (or the other way around for limits) requires
0306 mathematical functions not available in the kernel, so the conversion
0307 must occur in user space. For these chips, all temp* files described
0308 above should contain values expressed in millivolt instead of millidegree
0309 Celsius. In other words, such temperature channels are handled as voltage
0310 channels by the driver.
0311
0312 Also see the Alarms section for status flags associated with temperatures.
0313
0314
0315 ********
0316 Currents
0317 ********
0318
0319 `curr[1-*]_max`
0320 Current max value.
0321
0322 `curr[1-*]_min`
0323 Current min value.
0324
0325 `curr[1-*]_lcrit`
0326 Current critical low value
0327
0328 `curr[1-*]_crit`
0329 Current critical high value.
0330
0331 `curr[1-*]_input`
0332 Current input value.
0333
0334 `curr[1-*]_average`
0335 Average current use.
0336
0337 `curr[1-*]_lowest`
0338 Historical minimum current.
0339
0340 `curr[1-*]_highest`
0341 Historical maximum current.
0342
0343 `curr[1-*]_reset_history`
0344 Reset currX_lowest and currX_highest
0345
0346 WO
0347
0348 `curr_reset_history`
0349 Reset currX_lowest and currX_highest for all sensors.
0350
0351 `curr[1-*]_enable`
0352 Enable or disable the sensors.
0353
0354 `curr[1-*]_rated_min`
0355 Minimum rated current.
0356
0357 `curr[1-*]_rated_max`
0358 Maximum rated current.
0359
0360 Also see the Alarms section for status flags associated with currents.
0361
0362 *****
0363 Power
0364 *****
0365
0366 `power[1-*]_average`
0367 Average power use.
0368
0369 `power[1-*]_average_interval`
0370 Power use averaging interval.
0371
0372 `power[1-*]_average_interval_max`
0373 Maximum power use averaging interval.
0374
0375 `power[1-*]_average_interval_min`
0376 Minimum power use averaging interval.
0377
0378 `power[1-*]_average_highest`
0379 Historical average maximum power use
0380
0381 `power[1-*]_average_lowest`
0382 Historical average minimum power use
0383
0384 `power[1-*]_average_max`
0385 A poll notification is sent to `power[1-*]_average` when
0386 power use rises above this value.
0387
0388 `power[1-*]_average_min`
0389 A poll notification is sent to `power[1-*]_average` when
0390 power use sinks below this value.
0391
0392 `power[1-*]_input`
0393 Instantaneous power use.
0394
0395 `power[1-*]_input_highest`
0396 Historical maximum power use
0397
0398 `power[1-*]_input_lowest`
0399 Historical minimum power use.
0400
0401 `power[1-*]_reset_history`
0402 Reset input_highest, input_lowest, average_highest and
0403 average_lowest.
0404
0405 `power[1-*]_accuracy`
0406 Accuracy of the power meter.
0407
0408 `power[1-*]_cap`
0409 If power use rises above this limit, the
0410 system should take action to reduce power use.
0411
0412 `power[1-*]_cap_hyst`
0413 Margin of hysteresis built around capping and notification.
0414
0415 `power[1-*]_cap_max`
0416 Maximum cap that can be set.
0417
0418 `power[1-*]_cap_min`
0419 Minimum cap that can be set.
0420
0421 `power[1-*]_max`
0422 Maximum power.
0423
0424 `power[1-*]_crit`
0425 Critical maximum power.
0426
0427 If power rises to or above this limit, the
0428 system is expected take drastic action to reduce
0429 power consumption, such as a system shutdown or
0430 a forced powerdown of some devices.
0431
0432 Unit: microWatt
0433
0434 RW
0435
0436 `power[1-*]_enable`
0437 Enable or disable the sensors.
0438
0439 When disabled the sensor read will return
0440 -ENODATA.
0441
0442 - 1: Enable
0443 - 0: Disable
0444
0445 RW
0446
0447 `power[1-*]_rated_min`
0448 Minimum rated power.
0449
0450 Unit: microWatt
0451
0452 RO
0453
0454 `power[1-*]_rated_max`
0455 Maximum rated power.
0456
0457 Unit: microWatt
0458
0459 RO
0460
0461 Also see the Alarms section for status flags associated with power readings.
0462
0463 ******
0464 Energy
0465 ******
0466
0467 `energy[1-*]_input`
0468 Cumulative energy use
0469
0470 Unit: microJoule
0471
0472 RO
0473
0474 `energy[1-*]_enable`
0475 Enable or disable the sensors.
0476
0477 When disabled the sensor read will return
0478 -ENODATA.
0479
0480 - 1: Enable
0481 - 0: Disable
0482
0483 RW
0484
0485 ********
0486 Humidity
0487 ********
0488
0489 `humidity[1-*]_input`
0490 Humidity.
0491
0492 `humidity[1-*]_enable`
0493 Enable or disable the sensors.
0494
0495 `humidity[1-*]_rated_min`
0496 Minimum rated humidity.
0497
0498 `humidity[1-*]_rated_max`
0499 Maximum rated humidity.
0500
0501 ******
0502 Alarms
0503 ******
0504
0505 Each channel or limit may have an associated alarm file, containing a
0506 boolean value. 1 means than an alarm condition exists, 0 means no alarm.
0507
0508 Usually a given chip will either use channel-related alarms, or
0509 limit-related alarms, not both. The driver should just reflect the hardware
0510 implementation.
0511
0512 +-------------------------------+-----------------------+
0513 | **`in[0-*]_alarm`, | Channel alarm |
0514 | `curr[1-*]_alarm`, | |
0515 | `power[1-*]_alarm`, | - 0: no alarm |
0516 | `fan[1-*]_alarm`, | - 1: alarm |
0517 | `temp[1-*]_alarm`** | |
0518 | | RO |
0519 +-------------------------------+-----------------------+
0520
0521 **OR**
0522
0523 +-------------------------------+-----------------------+
0524 | **`in[0-*]_min_alarm`, | Limit alarm |
0525 | `in[0-*]_max_alarm`, | |
0526 | `in[0-*]_lcrit_alarm`, | - 0: no alarm |
0527 | `in[0-*]_crit_alarm`, | - 1: alarm |
0528 | `curr[1-*]_min_alarm`, | |
0529 | `curr[1-*]_max_alarm`, | RO |
0530 | `curr[1-*]_lcrit_alarm`, | |
0531 | `curr[1-*]_crit_alarm`, | |
0532 | `power[1-*]_cap_alarm`, | |
0533 | `power[1-*]_max_alarm`, | |
0534 | `power[1-*]_crit_alarm`, | |
0535 | `fan[1-*]_min_alarm`, | |
0536 | `fan[1-*]_max_alarm`, | |
0537 | `temp[1-*]_min_alarm`, | |
0538 | `temp[1-*]_max_alarm`, | |
0539 | `temp[1-*]_lcrit_alarm`, | |
0540 | `temp[1-*]_crit_alarm`, | |
0541 | `temp[1-*]_emergency_alarm`** | |
0542 +-------------------------------+-----------------------+
0543
0544 Each input channel may have an associated fault file. This can be used
0545 to notify open diodes, unconnected fans etc. where the hardware
0546 supports it. When this boolean has value 1, the measurement for that
0547 channel should not be trusted.
0548
0549 `fan[1-*]_fault` / `temp[1-*]_fault`
0550 Input fault condition.
0551
0552 Some chips also offer the possibility to get beeped when an alarm occurs:
0553
0554 `beep_enable`
0555 Master beep enable.
0556
0557 `in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`,
0558 Channel beep.
0559
0560 In theory, a chip could provide per-limit beep masking, but no such chip
0561 was seen so far.
0562
0563 Old drivers provided a different, non-standard interface to alarms and
0564 beeps. These interface files are deprecated, but will be kept around
0565 for compatibility reasons:
0566
0567 `alarms`
0568 Alarm bitmask.
0569
0570 `beep_mask`
0571 Bitmask for beep.
0572
0573
0574 *******************
0575 Intrusion detection
0576 *******************
0577
0578 `intrusion[0-*]_alarm`
0579 Chassis intrusion detection.
0580
0581 `intrusion[0-*]_beep`
0582 Chassis intrusion beep.
0583
0584 ****************************
0585 Average sample configuration
0586 ****************************
0587
0588 Devices allowing for reading {in,power,curr,temp}_average values may export
0589 attributes for controlling number of samples used to compute average.
0590
0591 +--------------+---------------------------------------------------------------+
0592 | samples | Sets number of average samples for all types of measurements. |
0593 | | |
0594 | | RW |
0595 +--------------+---------------------------------------------------------------+
0596 | in_samples | Sets number of average samples for specific type of |
0597 | power_samples| measurements. |
0598 | curr_samples | |
0599 | temp_samples | Note that on some devices it won't be possible to set all of |
0600 | | them to different values so changing one might also change |
0601 | | some others. |
0602 | | |
0603 | | RW |
0604 +--------------+---------------------------------------------------------------+
0605
0606 sysfs attribute writes interpretation
0607 -------------------------------------
0608
0609 hwmon sysfs attributes always contain numbers, so the first thing to do is to
0610 convert the input to a number, there are 2 ways todo this depending whether
0611 the number can be negative or not::
0612
0613 unsigned long u = simple_strtoul(buf, NULL, 10);
0614 long s = simple_strtol(buf, NULL, 10);
0615
0616 With buf being the buffer with the user input being passed by the kernel.
0617 Notice that we do not use the second argument of strto[u]l, and thus cannot
0618 tell when 0 is returned, if this was really 0 or is caused by invalid input.
0619 This is done deliberately as checking this everywhere would add a lot of
0620 code to the kernel.
0621
0622 Notice that it is important to always store the converted value in an
0623 unsigned long or long, so that no wrap around can happen before any further
0624 checking.
0625
0626 After the input string is converted to an (unsigned) long, the value should be
0627 checked if its acceptable. Be careful with further conversions on the value
0628 before checking it for validity, as these conversions could still cause a wrap
0629 around before the check. For example do not multiply the result, and only
0630 add/subtract if it has been divided before the add/subtract.
0631
0632 What to do if a value is found to be invalid, depends on the type of the
0633 sysfs attribute that is being set. If it is a continuous setting like a
0634 tempX_max or inX_max attribute, then the value should be clamped to its
0635 limits using clamp_val(value, min_limit, max_limit). If it is not continuous
0636 like for example a tempX_type, then when an invalid value is written,
0637 -EINVAL should be returned.
0638
0639 Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees)::
0640
0641 long v = simple_strtol(buf, NULL, 10) / 1000;
0642 v = clamp_val(v, -128, 127);
0643 /* write v to register */
0644
0645 Example2, fan divider setting, valid values 2, 4 and 8::
0646
0647 unsigned long v = simple_strtoul(buf, NULL, 10);
0648
0649 switch (v) {
0650 case 2: v = 1; break;
0651 case 4: v = 2; break;
0652 case 8: v = 3; break;
0653 default:
0654 return -EINVAL;
0655 }
0656 /* write v to register */
