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