Documentation/hwmon/sysfs-interface.rst

   1 Naming and data format standards for sysfs files
   2 ================================================
   3
   4 The libsensors library offers an interface to the raw sensors data
   5 through the sysfs interface. Since lm-sensors 3.0.0, libsensors is
   6 completely chip-independent. It assumes that all the kernel drivers
   7 implement the standard sysfs interface described in this document.
   8 This makes adding or updating support for any given chip very easy, as
   9 libsensors, and applications using it, do not need to be modified.
  10 This is a major improvement compared to lm-sensors 2.
  11
  12 Note that motherboards vary widely in the connections to sensor chips.
  13 There is no standard that ensures, for example, that the second
  14 temperature sensor is connected to the CPU, or that the second fan is on
  15 the CPU. Also, some values reported by the chips need some computation
  16 before they make full sense. For example, most chips can only measure
  17 voltages between 0 and +4V. Other voltages are scaled back into that
  18 range using external resistors. Since the values of these resistors
  19 can change from motherboard to motherboard, the conversions cannot be
  20 hard coded into the driver and have to be done in user space.
  21
  22 For this reason, even if we aim at a chip-independent libsensors, it will
  23 still require a configuration file (e.g. /etc/sensors.conf) for proper
  24 values conversion, labeling of inputs and hiding of unused inputs.
  25
  26 An alternative method that some programs use is to access the sysfs
  27 files directly. This document briefly describes the standards that the
  28 drivers follow, so that an application program can scan for entries and
  29 access this data in a simple and consistent way. That said, such programs
  30 will have to implement conversion, labeling and hiding of inputs. For
  31 this reason, it is still not recommended to bypass the library.
  32
  33 Each chip gets its own directory in the sysfs /sys/devices tree.  To
  34 find all sensor chips, it is easier to follow the device symlinks from
  35 `/sys/class/hwmon/hwmon*`.
  36
  37 Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes
  38 in the "physical" device directory. Since lm-sensors 3.0.1, attributes found
  39 in the hwmon "class" device directory are also supported. Complex drivers
  40 (e.g. drivers for multifunction chips) may want to use this possibility to
  41 avoid namespace pollution. The only drawback will be that older versions of
  42 libsensors won't support the driver in question.
  43
  44 All sysfs values are fixed point numbers.
  45
  46 There is only one value per file, unlike the older /proc specification.
  47 The common scheme for files naming is: <type><number>_<item>. Usual
  48 types for sensor chips are "in" (voltage), "temp" (temperature) and
  49 "fan" (fan). Usual items are "input" (measured value), "max" (high
  50 threshold, "min" (low threshold). Numbering usually starts from 1,
  51 except for voltages which start from 0 (because most data sheets use
  52 this). A number is always used for elements that can be present more
  53 than once, even if there is a single element of the given type on the
  54 specific chip. Other files do not refer to a specific element, so
  55 they have a simple name, and no number.
  56
  57 Alarms are direct indications read from the chips. The drivers do NOT
  58 make comparisons of readings to thresholds. This allows violations
  59 between readings to be caught and alarmed. The exact definition of an
  60 alarm (for example, whether a threshold must be met or must be exceeded
  61 to cause an alarm) is chip-dependent.
  62
  63 When setting values of hwmon sysfs attributes, the string representation of
  64 the desired value must be written, note that strings which are not a number
  65 are interpreted as 0! For more on how written strings are interpreted see the
  66 "sysfs attribute writes interpretation" section at the end of this file.
  67
  68 Attribute access
  69 ----------------
  70
  71 Hardware monitoring sysfs attributes are displayed by unrestricted userspace
  72 applications. For this reason, all standard ABI attributes shall be world
  73 readable. Writeable standard ABI attributes shall be writeable only for
  74 privileged users.
  75
  76 -------------------------------------------------------------------------
  77
  78 ======= ===========================================
  79 `[0-*]` denotes any positive number starting from 0
  80 `[1-*]` denotes any positive number starting from 1
  81 RO      read only value
  82 WO      write only value
  83 RW      read/write value
  84 ======= ===========================================
  85
  86 Read/write values may be read-only for some chips, depending on the
  87 hardware implementation.
  88
  89 All entries (except name) are optional, and should only be created in a
  90 given driver if the chip has the feature.
  91
  92 See Documentation/ABI/testing/sysfs-class-hwmon for a complete description
  93 of the attributes.
  94
  95 *****************
  96 Global 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 ********
 111 Voltages
 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
 162 Also see the Alarms section for status flags associated with voltages.
 163
 164
 165 ****
 166 Fans
 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
 193 Also see the Alarms section for status flags associated with fans.
 194
 195
 196 ***
 197 PWM
 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
 222 There is a third case where trip points are associated to both PWM output
 223 channels and temperature channels: the PWM values are associated to PWM
 224 output channels while the temperature values are associated to temperature
 225 channels. In that case, the result is determined by the mapping between
 226 temperature inputs and PWM outputs. When several temperature inputs are
 227 mapped to a given PWM output, this leads to several candidate PWM values.
 228 The actual result is up to the chip, but in general the highest candidate
 229 value (fastest fan speed) wins.
 230
 231
 232 ************
 233 Temperatures
 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
 303 Some chips measure temperature using external thermistors and an ADC, and
 304 report the temperature measurement as a voltage. Converting this voltage
 305 back to a temperature (or the other way around for limits) requires
 306 mathematical functions not available in the kernel, so the conversion
 307 must occur in user space. For these chips, all temp* files described
 308 above should contain values expressed in millivolt instead of millidegree
 309 Celsius. In other words, such temperature channels are handled as voltage
 310 channels by the driver.
 311
 312 Also see the Alarms section for status flags associated with temperatures.
 313
 314
 315 ********
 316 Currents
 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
 360 Also see the Alarms section for status flags associated with currents.
 361
 362 *****
 363 Power
 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
 461 Also see the Alarms section for status flags associated with power readings.
 462
 463 ******
 464 Energy
 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 ********
 486 Humidity
 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 ******
 502 Alarms
 503 ******
 504
 505 Each channel or limit may have an associated alarm file, containing a
 506 boolean value. 1 means than an alarm condition exists, 0 means no alarm.
 507
 508 Usually a given chip will either use channel-related alarms, or
 509 limit-related alarms, not both. The driver should just reflect the hardware
 510 implementation.
 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
 544 Each input channel may have an associated fault file. This can be used
 545 to notify open diodes, unconnected fans etc. where the hardware
 546 supports it. When this boolean has value 1, the measurement for that
 547 channel should not be trusted.
 548
 549 `fan[1-*]_fault` / `temp[1-*]_fault`
 550                 Input fault condition.
 551
 552 Some 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
 560 In theory, a chip could provide per-limit beep masking, but no such chip
 561 was seen so far.
 562
 563 Old drivers provided a different, non-standard interface to alarms and
 564 beeps. These interface files are deprecated, but will be kept around
 565 for compatibility reasons:
 566
 567 `alarms`
 568                 Alarm bitmask.
 569
 570 `beep_mask`
 571                 Bitmask for beep.
 572
 573
 574 *******************
 575 Intrusion detection
 576 *******************
 577
 578 `intrusion[0-*]_alarm`
 579                 Chassis intrusion detection.
 580
 581 `intrusion[0-*]_beep`
 582                 Chassis intrusion beep.
 583
 584 ****************************
 585 Average sample configuration
 586 ****************************
 587
 588 Devices allowing for reading {in,power,curr,temp}_average values may export
 589 attributes 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
 606 sysfs attribute writes interpretation
 607 -------------------------------------
 608
 609 hwmon sysfs attributes always contain numbers, so the first thing to do is to
 610 convert the input to a number, there are 2 ways todo this depending whether
 611 the 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
 616 With buf being the buffer with the user input being passed by the kernel.
 617 Notice that we do not use the second argument of strto[u]l, and thus cannot
 618 tell when 0 is returned, if this was really 0 or is caused by invalid input.
 619 This is done deliberately as checking this everywhere would add a lot of
 620 code to the kernel.
 621
 622 Notice that it is important to always store the converted value in an
 623 unsigned long or long, so that no wrap around can happen before any further
 624 checking.
 625
 626 After the input string is converted to an (unsigned) long, the value should be
 627 checked if its acceptable. Be careful with further conversions on the value
 628 before checking it for validity, as these conversions could still cause a wrap
 629 around before the check. For example do not multiply the result, and only
 630 add/subtract if it has been divided before the add/subtract.
 631
 632 What to do if a value is found to be invalid, depends on the type of the
 633 sysfs attribute that is being set. If it is a continuous setting like a
 634 tempX_max or inX_max attribute, then the value should be clamped to its
 635 limits using clamp_val(value, min_limit, max_limit). If it is not continuous
 636 like for example a tempX_type, then when an invalid value is written,
 637 -EINVAL should be returned.
 638
 639 Example1, 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
 645 Example2, 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 */