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-*]_input Temperature input value.
 331                Unit: millidegree Celsius
 332                RO
 333
 334temp[1-*]_crit  Temperature critical max value, typically greater than
 335                corresponding temp_max values.
 336                Unit: millidegree Celsius
 337                RW
 338
 339temp[1-*]_crit_hyst
 340                Temperature hysteresis value for critical limit.
 341                Unit: millidegree Celsius
 342                Must be reported as an absolute temperature, NOT a delta
 343                from the critical value.
 344                RW
 345
 346temp[1-*]_emergency
 347                Temperature emergency max value, for chips supporting more than
 348                two upper temperature limits. Must be equal or greater than
 349                corresponding temp_crit values.
 350                Unit: millidegree Celsius
 351                RW
 352
 353temp[1-*]_emergency_hyst
 354                Temperature hysteresis value for emergency limit.
 355                Unit: millidegree Celsius
 356                Must be reported as an absolute temperature, NOT a delta
 357                from the emergency value.
 358                RW
 359
 360temp[1-*]_lcrit Temperature critical min value, typically lower than
 361                corresponding temp_min values.
 362                Unit: millidegree Celsius
 363                RW
 364
 365temp[1-*]_offset
 366                Temperature offset which is added to the temperature reading
 367                by the chip.
 368                Unit: millidegree Celsius
 369                Read/Write value.
 370
 371temp[1-*]_label Suggested temperature channel label.
 372                Text string
 373                Should only be created if the driver has hints about what
 374                this temperature channel is being used for, and user-space
 375                doesn't. In all other cases, the label is provided by
 376                user-space.
 377                RO
 378
 379temp[1-*]_lowest
 380                Historical minimum temperature
 381                Unit: millidegree Celsius
 382                RO
 383
 384temp[1-*]_highest
 385                Historical maximum temperature
 386                Unit: millidegree Celsius
 387                RO
 388
 389temp[1-*]_reset_history
 390                Reset temp_lowest and temp_highest
 391                WO
 392
 393temp_reset_history
 394                Reset temp_lowest and temp_highest for all sensors
 395                WO
 396
 397Some chips measure temperature using external thermistors and an ADC, and
 398report the temperature measurement as a voltage. Converting this voltage
 399back to a temperature (or the other way around for limits) requires
 400mathematical functions not available in the kernel, so the conversion
 401must occur in user space. For these chips, all temp* files described
 402above should contain values expressed in millivolt instead of millidegree
 403Celsius. In other words, such temperature channels are handled as voltage
 404channels by the driver.
 405
 406Also see the Alarms section for status flags associated with temperatures.
 407
 408
 409************
 410* Currents *
 411************
 412
 413curr[1-*]_max   Current max value
 414                Unit: milliampere
 415                RW
 416
 417curr[1-*]_min   Current min value.
 418                Unit: milliampere
 419                RW
 420
 421curr[1-*]_lcrit Current critical low value
 422                Unit: milliampere
 423                RW
 424
 425curr[1-*]_crit  Current critical high value.
 426                Unit: milliampere
 427                RW
 428
 429curr[1-*]_input Current input value
 430                Unit: milliampere
 431                RO
 432
 433curr[1-*]_average
 434                Average current use
 435                Unit: milliampere
 436                RO
 437
 438curr[1-*]_lowest
 439                Historical minimum current
 440                Unit: milliampere
 441                RO
 442
 443curr[1-*]_highest
 444                Historical maximum current
 445                Unit: milliampere
 446                RO
 447
 448curr[1-*]_reset_history
 449                Reset currX_lowest and currX_highest
 450                WO
 451
 452curr_reset_history
 453                Reset currX_lowest and currX_highest for all sensors
 454                WO
 455
 456Also see the Alarms section for status flags associated with currents.
 457
 458*********
 459* Power *
 460*********
 461
 462power[1-*]_average              Average power use
 463                                Unit: microWatt
 464                                RO
 465
 466power[1-*]_average_interval     Power use averaging interval.  A poll
 467                                notification is sent to this file if the
 468                                hardware changes the averaging interval.
 469                                Unit: milliseconds
 470                                RW
 471
 472power[1-*]_average_interval_max Maximum power use averaging interval
 473                                Unit: milliseconds
 474                                RO
 475
 476power[1-*]_average_interval_min Minimum power use averaging interval
 477                                Unit: milliseconds
 478                                RO
 479
 480power[1-*]_average_highest      Historical average maximum power use
 481                                Unit: microWatt
 482                                RO
 483
 484power[1-*]_average_lowest       Historical average minimum power use
 485                                Unit: microWatt
 486                                RO
 487
 488power[1-*]_average_max          A poll notification is sent to
 489                                power[1-*]_average when power use
 490                                rises above this value.
 491                                Unit: microWatt
 492                                RW
 493
 494power[1-*]_average_min          A poll notification is sent to
 495                                power[1-*]_average when power use
 496                                sinks below this value.
 497                                Unit: microWatt
 498                                RW
 499
 500power[1-*]_input                Instantaneous power use
 501                                Unit: microWatt
 502                                RO
 503
 504power[1-*]_input_highest        Historical maximum power use
 505                                Unit: microWatt
 506                                RO
 507
 508power[1-*]_input_lowest         Historical minimum power use
 509                                Unit: microWatt
 510                                RO
 511
 512power[1-*]_reset_history        Reset input_highest, input_lowest,
 513                                average_highest and average_lowest.
 514                                WO
 515
 516power[1-*]_accuracy             Accuracy of the power meter.
 517                                Unit: Percent
 518                                RO
 519
 520power[1-*]_cap                  If power use rises above this limit, the
 521                                system should take action to reduce power use.
 522                                A poll notification is sent to this file if the
 523                                cap is changed by the hardware.  The *_cap
 524                                files only appear if the cap is known to be
 525                                enforced by hardware.
 526                                Unit: microWatt
 527                                RW
 528
 529power[1-*]_cap_hyst             Margin of hysteresis built around capping and
 530                                notification.
 531                                Unit: microWatt
 532                                RW
 533
 534power[1-*]_cap_max              Maximum cap that can be set.
 535                                Unit: microWatt
 536                                RO
 537
 538power[1-*]_cap_min              Minimum cap that can be set.
 539                                Unit: microWatt
 540                                RO
 541
 542power[1-*]_max                  Maximum power.
 543                                Unit: microWatt
 544                                RW
 545
 546power[1-*]_crit                 Critical maximum power.
 547                                If power rises to or above this limit, the
 548                                system is expected take drastic action to reduce
 549                                power consumption, such as a system shutdown or
 550                                a forced powerdown of some devices.
 551                                Unit: microWatt
 552                                RW
 553
 554Also see the Alarms section for status flags associated with power readings.
 555
 556**********
 557* Energy *
 558**********
 559
 560energy[1-*]_input               Cumulative energy use
 561                                Unit: microJoule
 562                                RO
 563
 564
 565************
 566* Humidity *
 567************
 568
 569humidity[1-*]_input             Humidity
 570                                Unit: milli-percent (per cent mille, pcm)
 571                                RO
 572
 573
 574**********
 575* Alarms *
 576**********
 577
 578Each channel or limit may have an associated alarm file, containing a
 579boolean value. 1 means than an alarm condition exists, 0 means no alarm.
 580
 581Usually a given chip will either use channel-related alarms, or
 582limit-related alarms, not both. The driver should just reflect the hardware
 583implementation.
 584
 585in[0-*]_alarm
 586curr[1-*]_alarm
 587power[1-*]_alarm
 588fan[1-*]_alarm
 589temp[1-*]_alarm
 590                Channel alarm
 591                0: no alarm
 592                1: alarm
 593                RO
 594
 595OR
 596
 597in[0-*]_min_alarm
 598in[0-*]_max_alarm
 599in[0-*]_lcrit_alarm
 600in[0-*]_crit_alarm
 601curr[1-*]_min_alarm
 602curr[1-*]_max_alarm
 603curr[1-*]_lcrit_alarm
 604curr[1-*]_crit_alarm
 605power[1-*]_cap_alarm
 606power[1-*]_max_alarm
 607power[1-*]_crit_alarm
 608fan[1-*]_min_alarm
 609fan[1-*]_max_alarm
 610temp[1-*]_min_alarm
 611temp[1-*]_max_alarm
 612temp[1-*]_lcrit_alarm
 613temp[1-*]_crit_alarm
 614temp[1-*]_emergency_alarm
 615                Limit alarm
 616                0: no alarm
 617                1: alarm
 618                RO
 619
 620Each input channel may have an associated fault file. This can be used
 621to notify open diodes, unconnected fans etc. where the hardware
 622supports it. When this boolean has value 1, the measurement for that
 623channel should not be trusted.
 624
 625fan[1-*]_fault
 626temp[1-*]_fault
 627                Input fault condition
 628                0: no fault occurred
 629                1: fault condition
 630                RO
 631
 632Some chips also offer the possibility to get beeped when an alarm occurs:
 633
 634beep_enable     Master beep enable
 635                0: no beeps
 636                1: beeps
 637                RW
 638
 639in[0-*]_beep
 640curr[1-*]_beep
 641fan[1-*]_beep
 642temp[1-*]_beep
 643                Channel beep
 644                0: disable
 645                1: enable
 646                RW
 647
 648In theory, a chip could provide per-limit beep masking, but no such chip
 649was seen so far.
 650
 651Old drivers provided a different, non-standard interface to alarms and
 652beeps. These interface files are deprecated, but will be kept around
 653for compatibility reasons:
 654
 655alarms          Alarm bitmask.
 656                RO
 657                Integer representation of one to four bytes.
 658                A '1' bit means an alarm.
 659                Chips should be programmed for 'comparator' mode so that
 660                the alarm will 'come back' after you read the register
 661                if it is still valid.
 662                Generally a direct representation of a chip's internal
 663                alarm registers; there is no standard for the position
 664                of individual bits. For this reason, the use of this
 665                interface file for new drivers is discouraged. Use
 666                individual *_alarm and *_fault files instead.
 667                Bits are defined in kernel/include/sensors.h.
 668
 669beep_mask       Bitmask for beep.
 670                Same format as 'alarms' with the same bit locations,
 671                use discouraged for the same reason. Use individual
 672                *_beep files instead.
 673                RW
 674
 675
 676***********************
 677* Intrusion detection *
 678***********************
 679
 680intrusion[0-*]_alarm
 681                Chassis intrusion detection
 682                0: OK
 683                1: intrusion detected
 684                RW
 685                Contrary to regular alarm flags which clear themselves
 686                automatically when read, this one sticks until cleared by
 687                the user. This is done by writing 0 to the file. Writing
 688                other values is unsupported.
 689
 690intrusion[0-*]_beep
 691                Chassis intrusion beep
 692                0: disable
 693                1: enable
 694                RW
 695
 696
 697sysfs attribute writes interpretation
 698-------------------------------------
 699
 700hwmon sysfs attributes always contain numbers, so the first thing to do is to
 701convert the input to a number, there are 2 ways todo this depending whether
 702the number can be negative or not:
 703unsigned long u = simple_strtoul(buf, NULL, 10);
 704long s = simple_strtol(buf, NULL, 10);
 705
 706With buf being the buffer with the user input being passed by the kernel.
 707Notice that we do not use the second argument of strto[u]l, and thus cannot
 708tell when 0 is returned, if this was really 0 or is caused by invalid input.
 709This is done deliberately as checking this everywhere would add a lot of
 710code to the kernel.
 711
 712Notice that it is important to always store the converted value in an
 713unsigned long or long, so that no wrap around can happen before any further
 714checking.
 715
 716After the input string is converted to an (unsigned) long, the value should be
 717checked if its acceptable. Be careful with further conversions on the value
 718before checking it for validity, as these conversions could still cause a wrap
 719around before the check. For example do not multiply the result, and only
 720add/subtract if it has been divided before the add/subtract.
 721
 722What to do if a value is found to be invalid, depends on the type of the
 723sysfs attribute that is being set. If it is a continuous setting like a
 724tempX_max or inX_max attribute, then the value should be clamped to its
 725limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
 726continuous like for example a tempX_type, then when an invalid value is
 727written, -EINVAL should be returned.
 728
 729Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
 730
 731        long v = simple_strtol(buf, NULL, 10) / 1000;
 732        v = SENSORS_LIMIT(v, -128, 127);
 733        /* write v to register */
 734
 735Example2, fan divider setting, valid values 2, 4 and 8:
 736
 737        unsigned long v = simple_strtoul(buf, NULL, 10);
 738
 739        switch (v) {
 740        case 2: v = 1; break;
 741        case 4: v = 2; break;
 742        case 8: v = 3; break;
 743        default:
 744                return -EINVAL;
 745        }
 746        /* write v to register */
 747
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.