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
  73RW      read/write value
  74
  75Read/write values may be read-only for some chips, depending on the
  76hardware implementation.
  77
  78All entries (except name) are optional, and should only be created in a
  79given driver if the chip has the feature.
  80
  81
  82********
  83* Name *
  84********
  85
  86name            The chip name.
  87                This should be a short, lowercase string, not containing
  88                spaces nor dashes, representing the chip name. This is
  89                the only mandatory attribute.
  90                I2C devices get this attribute created automatically.
  91                RO
  92
  93
  94************
  95* Voltages *
  96************
  97
  98in[0-*]_min     Voltage min value.
  99                Unit: millivolt
 100                RW
 101                
 102in[0-*]_max     Voltage max value.
 103                Unit: millivolt
 104                RW
 105                
 106in[0-*]_input   Voltage input value.
 107                Unit: millivolt
 108                RO
 109                Voltage measured on the chip pin.
 110                Actual voltage depends on the scaling resistors on the
 111                motherboard, as recommended in the chip datasheet.
 112                This varies by chip and by motherboard.
 113                Because of this variation, values are generally NOT scaled
 114                by the chip driver, and must be done by the application.
 115                However, some drivers (notably lm87 and via686a)
 116                do scale, because of internal resistors built into a chip.
 117                These drivers will output the actual voltage. Rule of
 118                thumb: drivers should report the voltage values at the
 119                "pins" of the chip.
 120
 121in[0-*]_label   Suggested voltage channel label.
 122                Text string
 123                Should only be created if the driver has hints about what
 124                this voltage channel is being used for, and user-space
 125                doesn't. In all other cases, the label is provided by
 126                user-space.
 127                RO
 128
 129cpu[0-*]_vid    CPU core reference voltage.
 130                Unit: millivolt
 131                RO
 132                Not always correct.
 133
 134vrm             Voltage Regulator Module version number. 
 135                RW (but changing it should no more be necessary)
 136                Originally the VRM standard version multiplied by 10, but now
 137                an arbitrary number, as not all standards have a version
 138                number.
 139                Affects the way the driver calculates the CPU core reference
 140                voltage from the vid pins.
 141
 142Also see the Alarms section for status flags associated with voltages.
 143
 144
 145********
 146* Fans *
 147********
 148
 149fan[1-*]_min    Fan minimum value
 150                Unit: revolution/min (RPM)
 151                RW
 152
 153fan[1-*]_max    Fan maximum value
 154                Unit: revolution/min (RPM)
 155                Only rarely supported by the hardware.
 156                RW
 157
 158fan[1-*]_input  Fan input value.
 159                Unit: revolution/min (RPM)
 160                RO
 161
 162fan[1-*]_div    Fan divisor.
 163                Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
 164                RW
 165                Some chips only support values 1, 2, 4 and 8.
 166                Note that this is actually an internal clock divisor, which
 167                affects the measurable speed range, not the read value.
 168
 169fan[1-*]_target
 170                Desired fan speed
 171                Unit: revolution/min (RPM)
 172                RW
 173                Only makes sense if the chip supports closed-loop fan speed
 174                control based on the measured fan speed.
 175
 176fan[1-*]_label  Suggested fan channel label.
 177                Text string
 178                Should only be created if the driver has hints about what
 179                this fan channel is being used for, and user-space doesn't.
 180                In all other cases, the label is provided by user-space.
 181                RO
 182
 183Also see the Alarms section for status flags associated with fans.
 184
 185
 186*******
 187* PWM *
 188*******
 189
 190pwm[1-*]        Pulse width modulation fan control.
 191                Integer value in the range 0 to 255
 192                RW
 193                255 is max or 100%.
 194
 195pwm[1-*]_enable
 196                Fan speed control method:
 197                0: no fan speed control (i.e. fan at full speed)
 198                1: manual fan speed control enabled (using pwm[1-*])
 199                2+: automatic fan speed control enabled
 200                Check individual chip documentation files for automatic mode
 201                details.
 202                RW
 203
 204pwm[1-*]_mode   0: DC mode (direct current)
 205                1: PWM mode (pulse-width modulation)
 206                RW
 207
 208pwm[1-*]_freq   Base PWM frequency in Hz.
 209                Only possibly available when pwmN_mode is PWM, but not always
 210                present even then.
 211                RW
 212
 213pwm[1-*]_auto_channels_temp
 214                Select which temperature channels affect this PWM output in
 215                auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
 216                Which values are possible depend on the chip used.
 217                RW
 218
 219pwm[1-*]_auto_point[1-*]_pwm
 220pwm[1-*]_auto_point[1-*]_temp
 221pwm[1-*]_auto_point[1-*]_temp_hyst
 222                Define the PWM vs temperature curve. Number of trip points is
 223                chip-dependent. Use this for chips which associate trip points
 224                to PWM output channels.
 225                RW
 226
 227OR
 228
 229temp[1-*]_auto_point[1-*]_pwm
 230temp[1-*]_auto_point[1-*]_temp
 231temp[1-*]_auto_point[1-*]_temp_hyst
 232                Define the PWM vs temperature curve. Number of trip points is
 233                chip-dependent. Use this for chips which associate trip points
 234                to temperature channels.
 235                RW
 236
 237
 238****************
 239* Temperatures *
 240****************
 241
 242temp[1-*]_type  Sensor type selection.
 243                Integers 1 to 6
 244                RW
 245                1: PII/Celeron Diode
 246                2: 3904 transistor
 247                3: thermal diode
 248                4: thermistor
 249                5: AMD AMDSI
 250                6: Intel PECI
 251                Not all types are supported by all chips
 252
 253temp[1-*]_max   Temperature max value.
 254                Unit: millidegree Celsius (or millivolt, see below)
 255                RW
 256
 257temp[1-*]_min   Temperature min value.
 258                Unit: millidegree Celsius
 259                RW
 260
 261temp[1-*]_max_hyst
 262                Temperature hysteresis value for max limit.
 263                Unit: millidegree Celsius
 264                Must be reported as an absolute temperature, NOT a delta
 265                from the max value.
 266                RW
 267
 268temp[1-*]_input Temperature input value.
 269                Unit: millidegree Celsius
 270                RO
 271
 272temp[1-*]_crit  Temperature critical value, typically greater than
 273                corresponding temp_max values.
 274                Unit: millidegree Celsius
 275                RW
 276
 277temp[1-*]_crit_hyst
 278                Temperature hysteresis value for critical limit.
 279                Unit: millidegree Celsius
 280                Must be reported as an absolute temperature, NOT a delta
 281                from the critical value.
 282                RW
 283
 284temp[1-*]_offset
 285                Temperature offset which is added to the temperature reading
 286                by the chip.
 287                Unit: millidegree Celsius
 288                Read/Write value.
 289
 290temp[1-*]_label Suggested temperature channel label.
 291                Text string
 292                Should only be created if the driver has hints about what
 293                this temperature channel is being used for, and user-space
 294                doesn't. In all other cases, the label is provided by
 295                user-space.
 296                RO
 297
 298Some chips measure temperature using external thermistors and an ADC, and
 299report the temperature measurement as a voltage. Converting this voltage
 300back to a temperature (or the other way around for limits) requires
 301mathematical functions not available in the kernel, so the conversion
 302must occur in user space. For these chips, all temp* files described
 303above should contain values expressed in millivolt instead of millidegree
 304Celsius. In other words, such temperature channels are handled as voltage
 305channels by the driver.
 306
 307Also see the Alarms section for status flags associated with temperatures.
 308
 309
 310************
 311* Currents *
 312************
 313
 314Note that no known chip provides current measurements as of writing,
 315so this part is theoretical, so to say.
 316
 317curr[1-*]_max   Current max value
 318                Unit: milliampere
 319                RW
 320
 321curr[1-*]_min   Current min value.
 322                Unit: milliampere
 323                RW
 324
 325curr[1-*]_input Current input value
 326                Unit: milliampere
 327                RO
 328
 329*********
 330* Power *
 331*********
 332
 333power[1-*]_average              Average power use
 334                                Unit: microWatt
 335                                RO
 336
 337power[1-*]_average_interval     Power use averaging interval
 338                                Unit: milliseconds
 339                                RW
 340
 341power[1-*]_average_highest      Historical average maximum power use
 342                                Unit: microWatt
 343                                RO
 344
 345power[1-*]_average_lowest       Historical average minimum power use
 346                                Unit: microWatt
 347                                RO
 348
 349power[1-*]_input                Instantaneous power use
 350                                Unit: microWatt
 351                                RO
 352
 353power[1-*]_input_highest        Historical maximum power use
 354                                Unit: microWatt
 355                                RO
 356
 357power[1-*]_input_lowest         Historical minimum power use
 358                                Unit: microWatt
 359                                RO
 360
 361power[1-*]_reset_history        Reset input_highest, input_lowest,
 362                                average_highest and average_lowest.
 363                                WO
 364
 365**********
 366* Energy *
 367**********
 368
 369energy[1-*]_input               Cumulative energy use
 370                                Unit: microJoule
 371                                RO
 372
 373
 374**********
 375* Alarms *
 376**********
 377
 378Each channel or limit may have an associated alarm file, containing a
 379boolean value. 1 means than an alarm condition exists, 0 means no alarm.
 380
 381Usually a given chip will either use channel-related alarms, or
 382limit-related alarms, not both. The driver should just reflect the hardware
 383implementation.
 384
 385in[0-*]_alarm
 386fan[1-*]_alarm
 387temp[1-*]_alarm
 388                Channel alarm
 389                0: no alarm
 390                1: alarm
 391                RO
 392
 393OR
 394
 395in[0-*]_min_alarm
 396in[0-*]_max_alarm
 397fan[1-*]_min_alarm
 398fan[1-*]_max_alarm
 399temp[1-*]_min_alarm
 400temp[1-*]_max_alarm
 401temp[1-*]_crit_alarm
 402                Limit alarm
 403                0: no alarm
 404                1: alarm
 405                RO
 406
 407Each input channel may have an associated fault file. This can be used
 408to notify open diodes, unconnected fans etc. where the hardware
 409supports it. When this boolean has value 1, the measurement for that
 410channel should not be trusted.
 411
 412in[0-*]_fault
 413fan[1-*]_fault
 414temp[1-*]_fault
 415                Input fault condition
 416                0: no fault occured
 417                1: fault condition
 418                RO
 419
 420Some chips also offer the possibility to get beeped when an alarm occurs:
 421
 422beep_enable     Master beep enable
 423                0: no beeps
 424                1: beeps
 425                RW
 426
 427in[0-*]_beep
 428fan[1-*]_beep
 429temp[1-*]_beep
 430                Channel beep
 431                0: disable
 432                1: enable
 433                RW
 434
 435In theory, a chip could provide per-limit beep masking, but no such chip
 436was seen so far.
 437
 438Old drivers provided a different, non-standard interface to alarms and
 439beeps. These interface files are deprecated, but will be kept around
 440for compatibility reasons:
 441
 442alarms          Alarm bitmask.
 443                RO
 444                Integer representation of one to four bytes.
 445                A '1' bit means an alarm.
 446                Chips should be programmed for 'comparator' mode so that
 447                the alarm will 'come back' after you read the register
 448                if it is still valid.
 449                Generally a direct representation of a chip's internal
 450                alarm registers; there is no standard for the position
 451                of individual bits. For this reason, the use of this
 452                interface file for new drivers is discouraged. Use
 453                individual *_alarm and *_fault files instead.
 454                Bits are defined in kernel/include/sensors.h.
 455
 456beep_mask       Bitmask for beep.
 457                Same format as 'alarms' with the same bit locations,
 458                use discouraged for the same reason. Use individual
 459                *_beep files instead.
 460                RW
 461
 462
 463***********************
 464* Intrusion detection *
 465***********************
 466
 467intrusion[0-*]_alarm
 468                Chassis intrusion detection
 469                0: OK
 470                1: intrusion detected
 471                RW
 472                Contrary to regular alarm flags which clear themselves
 473                automatically when read, this one sticks until cleared by
 474                the user. This is done by writing 0 to the file. Writing
 475                other values is unsupported.
 476
 477intrusion[0-*]_beep
 478                Chassis intrusion beep
 479                0: disable
 480                1: enable
 481                RW
 482
 483
 484sysfs attribute writes interpretation
 485-------------------------------------
 486
 487hwmon sysfs attributes always contain numbers, so the first thing to do is to
 488convert the input to a number, there are 2 ways todo this depending whether
 489the number can be negative or not:
 490unsigned long u = simple_strtoul(buf, NULL, 10);
 491long s = simple_strtol(buf, NULL, 10);
 492
 493With buf being the buffer with the user input being passed by the kernel.
 494Notice that we do not use the second argument of strto[u]l, and thus cannot
 495tell when 0 is returned, if this was really 0 or is caused by invalid input.
 496This is done deliberately as checking this everywhere would add a lot of
 497code to the kernel.
 498
 499Notice that it is important to always store the converted value in an
 500unsigned long or long, so that no wrap around can happen before any further
 501checking.
 502
 503After the input string is converted to an (unsigned) long, the value should be
 504checked if its acceptable. Be careful with further conversions on the value
 505before checking it for validity, as these conversions could still cause a wrap
 506around before the check. For example do not multiply the result, and only
 507add/subtract if it has been divided before the add/subtract.
 508
 509What to do if a value is found to be invalid, depends on the type of the
 510sysfs attribute that is being set. If it is a continuous setting like a
 511tempX_max or inX_max attribute, then the value should be clamped to its
 512limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not
 513continuous like for example a tempX_type, then when an invalid value is
 514written, -EINVAL should be returned.
 515
 516Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):
 517
 518        long v = simple_strtol(buf, NULL, 10) / 1000;
 519        v = SENSORS_LIMIT(v, -128, 127);
 520        /* write v to register */
 521
 522Example2, fan divider setting, valid values 2, 4 and 8:
 523
 524        unsigned long v = simple_strtoul(buf, NULL, 10);
 525
 526        switch (v) {
 527        case 2: v = 1; break;
 528        case 4: v = 2; break;
 529        case 8: v = 3; break;
 530        default:
 531                return -EINVAL;
 532        }
 533        /* write v to register */
 534