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