Documentation/hwmon/sysfs-interface

   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 -------------------------------------------------------------------------
  69
  70 [0-*]   denotes any positive number starting from 0
  71 [1-*]   denotes any positive number starting from 1
  72 RO      read only value
  73 WO      write only value
  74 RW      read/write value
  75
  76 Read/write values may be read-only for some chips, depending on the
  77 hardware implementation.
  78
  79 All entries (except name) are optional, and should only be created in a
  80 given driver if the chip has the feature.
  81
  82
  83 *********************
  84 * Global attributes *
  85 *********************
  86
  87 name            The chip name.
  88                 This should be a short, lowercase string, not containing
  89                 spaces nor dashes, representing the chip name. This is
  90                 the only mandatory attribute.
  91                 I2C devices get this attribute created automatically.
  92                 RO
  93
  94 update_interval The interval at which the chip will update readings.
  95                 Unit: millisecond
  96                 RW
  97                 Some devices have a variable update rate or interval.
  98                 This attribute can be used to change it to the desired value.
  99
 100
 101 ************
 102 * Voltages *
 103 ************
 104
 105 in[0-*]_min     Voltage min value.
 106                 Unit: millivolt
 107                 RW
 108
 109 in[0-*]_lcrit   Voltage critical min value.
 110                 Unit: millivolt
 111                 RW
 112                 If voltage drops to or below this limit, the system may
 113                 take drastic action such as power down or reset. At the very
 114                 least, it should report a fault.
 115
 116 in[0-*]_max     Voltage max value.
 117                 Unit: millivolt
 118                 RW
 119
 120 in[0-*]_crit    Voltage critical max value.
 121                 Unit: millivolt
 122                 RW
 123                 If voltage reaches or exceeds this limit, the system may
 124                 take drastic action such as power down or reset. At the very
 125                 least, it should report a fault.
 126
 127 in[0-*]_input   Voltage input value.
 128                 Unit: millivolt
 129                 RO
 130                 Voltage measured on the chip pin.
 131                 Actual voltage depends on the scaling resistors on the
 132                 motherboard, as recommended in the chip datasheet.
 133                 This varies by chip and by motherboard.
 134                 Because of this variation, values are generally NOT scaled
 135                 by the chip driver, and must be done by the application.
 136                 However, some drivers (notably lm87 and via686a)
 137                 do scale, because of internal resistors built into a chip.
 138                 These drivers will output the actual voltage. Rule of
 139                 thumb: drivers should report the voltage values at the
 140                 "pins" of the chip.
 141
 142 in[0-*]_label   Suggested voltage channel label.
 143                 Text string
 144                 Should only be created if the driver has hints about what
 145                 this voltage channel is being used for, and user-space
 146                 doesn't. In all other cases, the label is provided by
 147                 user-space.
 148                 RO
 149
 150 cpu[0-*]_vid    CPU core reference voltage.
 151                 Unit: millivolt
 152                 RO
 153                 Not always correct.
 154
 155 vrm             Voltage Regulator Module version number.
 156                 RW (but changing it should no more be necessary)
 157                 Originally the VRM standard version multiplied by 10, but now
 158                 an arbitrary number, as not all standards have a version
 159                 number.
 160                 Affects the way the driver calculates the CPU core reference
 161                 voltage from the vid pins.
 162
 163 Also see the Alarms section for status flags associated with voltages.
 164
 165
 166 ********
 167 * Fans *
 168 ********
 169
 170 fan[1-*]_min    Fan minimum value
 171                 Unit: revolution/min (RPM)
 172                 RW
 173
 174 fan[1-*]_max    Fan maximum value
 175                 Unit: revolution/min (RPM)
 176                 Only rarely supported by the hardware.
 177                 RW
 178
 179 fan[1-*]_input  Fan input value.
 180                 Unit: revolution/min (RPM)
 181                 RO
 182
 183 fan[1-*]_div    Fan divisor.
 184                 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
 185                 RW
 186                 Some chips only support values 1, 2, 4 and 8.
 187                 Note that this is actually an internal clock divisor, which
 188                 affects the measurable speed range, not the read value.
 189
 190 fan[1-*]_pulses Number of tachometer pulses per fan revolution.
 191                 Integer value, typically between 1 and 4.
 192                 RW
 193                 This value is a characteristic of the fan connected to the
 194                 device's input, so it has to be set in accordance with the fan
 195                 model.
 196                 Should only be created if the chip has a register to configure
 197                 the number of pulses. In the absence of such a register (and
 198                 thus attribute) the value assumed by all devices is 2 pulses
 199                 per fan revolution.
 200
 201 fan[1-*]_target
 202                 Desired fan speed
 203                 Unit: revolution/min (RPM)
 204                 RW
 205                 Only makes sense if the chip supports closed-loop fan speed
 206                 control based on the measured fan speed.
 207
 208 fan[1-*]_label  Suggested fan channel label.
 209                 Text string
 210                 Should only be created if the driver has hints about what
 211                 this fan channel is being used for, and user-space doesn't.
 212                 In all other cases, the label is provided by user-space.
 213                 RO
 214
 215 Also see the Alarms section for status flags associated with fans.
 216
 217
 218 *******
 219 * PWM *
 220 *******
 221
 222 pwm[1-*]        Pulse width modulation fan control.
 223                 Integer value in the range 0 to 255
 224                 RW
 225                 255 is max or 100%.
 226
 227 pwm[1-*]_enable
 228                 Fan speed control method:
 229                 0: no fan speed control (i.e. fan at full speed)
 230                 1: manual fan speed control enabled (using pwm[1-*])
 231                 2+: automatic fan speed control enabled
 232                 Check individual chip documentation files for automatic mode
 233                 details.
 234                 RW
 235
 236 pwm[1-*]_mode   0: DC mode (direct current)
 237                 1: PWM mode (pulse-width modulation)
 238                 RW
 239
 240 pwm[1-*]_freq   Base PWM frequency in Hz.
 241                 Only possibly available when pwmN_mode is PWM, but not always
 242                 present even then.
 243                 RW
 244
 245 pwm[1-*]_auto_channels_temp
 246                 Select which temperature channels affect this PWM output in
 247                 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
 248                 Which values are possible depend on the chip used.
 249                 RW
 250
 251 pwm[1-*]_auto_point[1-*]_pwm
 252 pwm[1-*]_auto_point[1-*]_temp
 253 pwm[1-*]_auto_point[1-*]_temp_hyst
 254                 Define the PWM vs temperature curve. Number of trip points is
 255                 chip-dependent. Use this for chips which associate trip points
 256                 to PWM output channels.
 257                 RW
 258
 259 temp[1-*]_auto_point[1-*]_pwm
 260 temp[1-*]_auto_point[1-*]_temp
 261 temp[1-*]_auto_point[1-*]_temp_hyst
 262                 Define the PWM vs temperature curve. Number of trip points is
 263                 chip-dependent. Use this for chips which associate trip points
 264                 to temperature channels.
 265                 RW
 266
 267 There is a third case where trip points are associated to both PWM output
 268 channels and temperature channels: the PWM values are associated to PWM
 269 output channels while the temperature values are associated to temperature
 270 channels. In that case, the result is determined by the mapping between
 271 temperature inputs and PWM outputs. When several temperature inputs are
 272 mapped to a given PWM output, this leads to several candidate PWM values.
 273 The actual result is up to the chip, but in general the highest candidate
 274 value (fastest fan speed) wins.
 275
 276
 277 ****************
 278 * Temperatures *
 279 ****************
 280
 281 temp[1-*]_type  Sensor type selection.
 282                 Integers 1 to 6
 283                 RW
 284                 1: PII/Celeron Diode
 285                 2: 3904 transistor
 286                 3: thermal diode
 287                 4: thermistor
 288                 5: AMD AMDSI
 289                 6: Intel PECI
 290                 Not all types are supported by all chips
 291
 292 temp[1-*]_max   Temperature max value.
 293                 Unit: millidegree Celsius (or millivolt, see below)
 294                 RW
 295
 296 temp[1-*]_min   Temperature min value.
 297                 Unit: millidegree Celsius
 298                 RW
 299
 300 temp[1-*]_max_hyst
 301                 Temperature hysteresis value for max limit.
 302                 Unit: millidegree Celsius
 303                 Must be reported as an absolute temperature, NOT a delta
 304                 from the max value.
 305                 RW
 306
 307 temp[1-*]_input Temperature input value.
 308                 Unit: millidegree Celsius
 309                 RO
 310
 311 temp[1-*]_crit  Temperature critical max value, typically greater than
 312                 corresponding temp_max values.
 313                 Unit: millidegree Celsius
 314                 RW
 315
 316 temp[1-*]_crit_hyst
 317                 Temperature hysteresis value for critical limit.
 318                 Unit: millidegree Celsius
 319                 Must be reported as an absolute temperature, NOT a delta
 320                 from the critical value.
 321                 RW
 322
 323 temp[1-*]_emergency
 324                 Temperature emergency max value, for chips supporting more than
 325                 two upper temperature limits. Must be equal or greater than
 326                 corresponding temp_crit values.
 327                 Unit: millidegree Celsius
 328                 RW
 329
 330 temp[1-*]_emergency_hyst
 331                 Temperature hysteresis value for emergency limit.
 332                 Unit: millidegree Celsius
 333                 Must be reported as an absolute temperature, NOT a delta
 334                 from the emergency value.
 335                 RW
 336
 337 temp[1-*]_lcrit Temperature critical min value, typically lower than
 338                 corresponding temp_min values.
 339                 Unit: millidegree Celsius
 340                 RW
 341
 342 temp[1-*]_offset
 343                 Temperature offset which is added to the temperature reading
 344                 by the chip.
 345                 Unit: millidegree Celsius
 346                 Read/Write value.
 347
 348 temp[1-*]_label Suggested temperature channel label.
 349                 Text string
 350                 Should only be created if the driver has hints about what
 351                 this temperature channel is being used for, and user-space
 352                 doesn't. In all other cases, the label is provided by
 353                 user-space.
 354                 RO
 355
 356 temp[1-*]_lowest
 357                 Historical minimum temperature
 358                 Unit: millidegree Celsius
 359                 RO
 360
 361 temp[1-*]_highest
 362                 Historical maximum temperature
 363                 Unit: millidegree Celsius
 364                 RO
 365
 366 temp[1-*]_reset_history
 367                 Reset temp_lowest and temp_highest
 368                 WO
 369
 370 temp_reset_history
 371                 Reset temp_lowest and temp_highest for all sensors
 372                 WO
 373
 374 Some chips measure temperature using external thermistors and an ADC, and
 375 report the temperature measurement as a voltage. Converting this voltage
 376 back to a temperature (or the other way around for limits) requires
 377 mathematical functions not available in the kernel, so the conversion
 378 must occur in user space. For these chips, all temp* files described
 379 above should contain values expressed in millivolt instead of millidegree
 380 Celsius. In other words, such temperature channels are handled as voltage
 381 channels by the driver.
 382
 383 Also see the Alarms section for status flags associated with temperatures.
 384
 385
 386 ************
 387 * Currents *
 388 ************
 389
 390 curr[1-*]_max   Current max value
 391                 Unit: milliampere
 392                 RW
 393
 394 curr[1-*]_min   Current min value.
 395                 Unit: milliampere
 396                 RW
 397
 398 curr[1-*]_lcrit Current critical low value
 399                 Unit: milliampere
 400                 RW
 401
 402 curr[1-*]_crit  Current critical high value.
 403                 Unit: milliampere
 404                 RW
 405
 406 curr[1-*]_input Current input value
 407                 Unit: milliampere
 408                 RO
 409
 410 Also see the Alarms section for status flags associated with currents.
 411
 412 *********
 413 * Power *
 414 *********
 415
 416 power[1-*]_average              Average power use
 417                                 Unit: microWatt
 418                                 RO
 419
 420 power[1-*]_average_interval     Power use averaging interval.  A poll
 421                                 notification is sent to this file if the
 422                                 hardware changes the averaging interval.
 423                                 Unit: milliseconds
 424                                 RW
 425
 426 power[1-*]_average_interval_max Maximum power use averaging interval
 427                                 Unit: milliseconds
 428                                 RO
 429
 430 power[1-*]_average_interval_min Minimum power use averaging interval
 431                                 Unit: milliseconds
 432                                 RO
 433
 434 power[1-*]_average_highest      Historical average maximum power use
 435                                 Unit: microWatt
 436                                 RO
 437
 438 power[1-*]_average_lowest       Historical average minimum power use
 439                                 Unit: microWatt
 440                                 RO
 441
 442 power[1-*]_average_max          A poll notification is sent to
 443                                 power[1-*]_average when power use
 444                                 rises above this value.
 445                                 Unit: microWatt
 446                                 RW
 447
 448 power[1-*]_average_min          A poll notification is sent to
 449                                 power[1-*]_average when power use
 450                                 sinks below this value.
 451                                 Unit: microWatt
 452                                 RW
 453
 454 power[1-*]_input                Instantaneous power use
 455                                 Unit: microWatt
 456                                 RO
 457
 458 power[1-*]_input_highest        Historical maximum power use
 459                                 Unit: microWatt
 460                                 RO
 461
 462 power[1-*]_input_lowest         Historical minimum power use
 463                                 Unit: microWatt
 464                                 RO
 465
 466 power[1-*]_reset_history        Reset input_highest, input_lowest,
 467                                 average_highest and average_lowest.
 468                                 WO
 469
 470 power[1-*]_accuracy             Accuracy of the power meter.
 471                                 Unit: Percent
 472                                 RO
 473
 474 power[1-*]_cap                  If power use rises above this limit, the
 475                                 system should take action to reduce power use.
 476                                 A poll notification is sent to this file if the
 477                                 cap is changed by the hardware.  The *_cap
 478                                 files only appear if the cap is known to be
 479                                 enforced by hardware.
 480                                 Unit: microWatt
 481                                 RW
 482
 483 power[1-*]_cap_hyst             Margin of hysteresis built around capping and
 484                                 notification.
 485                                 Unit: microWatt
 486                                 RW
 487
 488 power[1-*]_cap_max              Maximum cap that can be set.
 489                                 Unit: microWatt
 490                                 RO
 491
 492 power[1-*]_cap_min              Minimum cap that can be set.
 493                                 Unit: microWatt
 494                                 RO
 495
 496 power[1-*]_max                  Maximum power.
 497                                 Unit: microWatt
 498                                 RW
 499
 500 power[1-*]_crit                 Critical maximum power.
 501                                 If power rises to or above this limit, the
 502                                 system is expected take drastic action to reduce
 503                                 power consumption, such as a system shutdown or
 504                                 a forced powerdown of some devices.
 505                                 Unit: microWatt
 506                                 RW
 507
 508 Also see the Alarms section for status flags associated with power readings.
 509
 510 **********
 511 * Energy *
 512 **********
 513
 514 energy[1-*]_input               Cumulative energy use
 515                                 Unit: microJoule
 516                                 RO
 517
 518
 519 ************
 520 * Humidity *
 521 ************
 522
 523 humidity[1-*]_input             Humidity
 524                                 Unit: milli-percent (per cent mille, pcm)
 525                                 RO
 526
 527
 528 **********
 529 * Alarms *
 530 **********
 531
 532 Each channel or limit may have an associated alarm file, containing a
 533 boolean value. 1 means than an alarm condition exists, 0 means no alarm.
 534
 535 Usually a given chip will either use channel-related alarms, or
 536 limit-related alarms, not both. The driver should just reflect the hardware
 537 implementation.
 538
 539 in[0-*]_alarm
 540 curr[1-*]_alarm
 541 power[1-*]_alarm
 542 fan[1-*]_alarm
 543 temp[1-*]_alarm
 544                 Channel alarm
 545                 0: no alarm
 546                 1: alarm
 547                 RO
 548
 549 OR
 550
 551 in[0-*]_min_alarm
 552 in[0-*]_max_alarm
 553 in[0-*]_lcrit_alarm
 554 in[0-*]_crit_alarm
 555 curr[1-*]_min_alarm
 556 curr[1-*]_max_alarm
 557 curr[1-*]_lcrit_alarm
 558 curr[1-*]_crit_alarm
 559 power[1-*]_cap_alarm
 560 power[1-*]_max_alarm
 561 power[1-*]_crit_alarm
 562 fan[1-*]_min_alarm
 563 fan[1-*]_max_alarm
 564 temp[1-*]_min_alarm
 565 temp[1-*]_max_alarm
 566 temp[1-*]_lcrit_alarm
 567 temp[1-*]_crit_alarm
 568 temp[1-*]_emergency_alarm
 569                 Limit alarm
 570                 0: no alarm
 571                 1: alarm
 572                 RO
 573
 574 Each input channel may have an associated fault file. This can be used
 575 to notify open diodes, unconnected fans etc. where the hardware
 576 supports it. When this boolean has value 1, the measurement for that
 577 channel should not be trusted.
 578
 579 fan[1-*]_fault
 580 temp[1-*]_fault
 581                 Input fault condition
 582                 0: no fault occurred
 583                 1: fault condition
 584                 RO
 585
 586 Some chips also offer the possibility to get beeped when an alarm occurs:
 587
 588 beep_enable     Master beep enable
 589                 0: no beeps
 590                 1: beeps
 591                 RW
 592
 593 in[0-*]_beep
 594 curr[1-*]_beep
 595 fan[1-*]_beep
 596 temp[1-*]_beep
 597                 Channel beep
 598                 0: disable
 599                 1: enable
 600                 RW
 601
 602 In theory, a chip could provide per-limit beep masking, but no such chip
 603 was seen so far.
 604
 605 Old drivers provided a different, non-standard interface to alarms and
 606 beeps. These interface files are deprecated, but will be kept around
 607 for compatibility reasons:
 608
 609 alarms          Alarm bitmask.
 610                 RO
 611                 Integer representation of one to four bytes.
 612                 A '1' bit means an alarm.
 613                 Chips should be programmed for 'comparator' mode so that
 614                 the alarm will 'come back' after you read the register
 615                 if it is still valid.
 616                 Generally a direct representation of a chip's internal
 617                 alarm registers; there is no standard for the position
 618                 of individual bits. For this reason, the use of this
 619                 interface file for new drivers is discouraged. Use
 620                 individual *_alarm and *_fault files instead.
 621                 Bits are defined in kernel/include/sensors.h.
 622
 623 beep_mask       Bitmask for beep.
 624                 Same format as 'alarms' with the same bit locations,
 625                 use discouraged for the same reason. Use individual
 626                 *_beep files instead.
 627                 RW
 628
 629
 630 ***********************
 631 * Intrusion detection *
 632 ***********************
 633
 634 intrusion[0-*]_alarm
 635                 Chassis intrusion detection
 636                 0: OK
 637                 1: intrusion detected
 638                 RW
 639                 Contrary to regular alarm flags which clear themselves
 640                 automatically when read, this one sticks until cleared by
 641                 the user. This is done by writing 0 to the file. Writing
 642                 other values is unsupported.
 643
 644 intrusion[0-*]_beep
 645                 Chassis intrusion beep
 646                 0: disable
 647                 1: enable
 648                 RW
 649
 650
 651 sysfs attribute writes interpretation
 652 -------------------------------------
 653
 654 hwmon sysfs attributes always contain numbers, so the first thing to do is to
 655 convert the input to a number, there are 2 ways todo this depending whether
 656 the number can be negative or not:
 657 unsigned long u = simple_strtoul(buf, NULL, 10);
 658 long s = simple_strtol(buf, NULL, 10);
 659
 660 With buf being the buffer with the user input being passed by the kernel.
 661 Notice that we do not use the second argument of strto[u]l, and thus cannot
 662 tell when 0 is returned, if this was really 0 or is caused by invalid input.
 663 This is done deliberately as checking this everywhere would add a lot of
 664 code to the kernel.
 665
 666 Notice that it is important to always store the converted value in an
 667 unsigned long or long, so that no wrap around can happen before any further
 668 checking.
 669
 670 After the input string is converted to an (unsigned) long, the value should be
 671 checked if its acceptable. Be careful with further conversions on the value
 672 before checking it for validity, as these conversions could still cause a wrap
 673 around before the check. For example do not multiply the result, and only
 674 add/subtract if it has been divided before the add/subtract.
 675
 676 What to do if a value is found to be invalid, depends on the type of the
 677 sysfs attribute that is being set. If it is a continuous setting like a
 678 tempX_max or inX_max attribute, then the value should be clamped to its
 679 limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
 680 continuous like for example a tempX_type, then when an invalid value is
 681 written, -EINVAL should be returned.
 682
 683 Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
 684
 685         long v = simple_strtol(buf, NULL, 10) / 1000;
 686         v = SENSORS_LIMIT(v, -128, 127);
 687         /* write v to register */
 688
 689 Example2, fan divider setting, valid values 2, 4 and 8:
 690
 691         unsigned long v = simple_strtoul(buf, NULL, 10);
 692
 693         switch (v) {
 694         case 2: v = 1; break;
 695         case 4: v = 2; break;
 696         case 8: v = 3; break;
 697         default:
 698                 return -EINVAL;
 699         }
 700         /* write v to register */