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-*]_input Current input value 388 Unit: milliampere 389 RO 390 391********* 392* Power * 393********* 394 395power[1-*]_average Average power use 396 Unit: microWatt 397 RO 398 399power[1-*]_average_interval Power use averaging interval. A poll 400 notification is sent to this file if the 401 hardware changes the averaging interval. 402 Unit: milliseconds 403 RW 404 405power[1-*]_average_interval_max Maximum power use averaging interval 406 Unit: milliseconds 407 RO 408 409power[1-*]_average_interval_min Minimum power use averaging interval 410 Unit: milliseconds 411 RO 412 413power[1-*]_average_highest Historical average maximum power use 414 Unit: microWatt 415 RO 416 417power[1-*]_average_lowest Historical average minimum power use 418 Unit: microWatt 419 RO 420 421power[1-*]_average_max A poll notification is sent to 422 power[1-*]_average when power use 423 rises above this value. 424 Unit: microWatt 425 RW 426 427power[1-*]_average_min A poll notification is sent to 428 power[1-*]_average when power use 429 sinks below this value. 430 Unit: microWatt 431 RW 432 433power[1-*]_input Instantaneous power use 434 Unit: microWatt 435 RO 436 437power[1-*]_input_highest Historical maximum power use 438 Unit: microWatt 439 RO 440 441power[1-*]_input_lowest Historical minimum power use 442 Unit: microWatt 443 RO 444 445power[1-*]_reset_history Reset input_highest, input_lowest, 446 average_highest and average_lowest. 447 WO 448 449power[1-*]_accuracy Accuracy of the power meter. 450 Unit: Percent 451 RO 452 453power[1-*]_alarm 1 if the system is drawing more power than the 454 cap allows; 0 otherwise. A poll notification is 455 sent to this file when the power use exceeds the 456 cap. This file only appears if the cap is known 457 to be enforced by hardware. 458 RO 459 460power[1-*]_cap If power use rises above this limit, the 461 system should take action to reduce power use. 462 A poll notification is sent to this file if the 463 cap is changed by the hardware. The *_cap 464 files only appear if the cap is known to be 465 enforced by hardware. 466 Unit: microWatt 467 RW 468 469power[1-*]_cap_hyst Margin of hysteresis built around capping and 470 notification. 471 Unit: microWatt 472 RW 473 474power[1-*]_cap_max Maximum cap that can be set. 475 Unit: microWatt 476 RO 477 478power[1-*]_cap_min Minimum cap that can be set. 479 Unit: microWatt 480 RO 481 482********** 483* Energy * 484********** 485 486energy[1-*]_input Cumulative energy use 487 Unit: microJoule 488 RO 489 490 491********** 492* Alarms * 493********** 494 495Each channel or limit may have an associated alarm file, containing a 496boolean value. 1 means than an alarm condition exists, 0 means no alarm. 497 498Usually a given chip will either use channel-related alarms, or 499limit-related alarms, not both. The driver should just reflect the hardware 500implementation. 501 502in[0-*]_alarm 503curr[1-*]_alarm 504fan[1-*]_alarm 505temp[1-*]_alarm 506 Channel alarm 507 0: no alarm 508 1: alarm 509 RO 510 511OR 512 513in[0-*]_min_alarm 514in[0-*]_max_alarm 515curr[1-*]_min_alarm 516curr[1-*]_max_alarm 517fan[1-*]_min_alarm 518fan[1-*]_max_alarm 519temp[1-*]_min_alarm 520temp[1-*]_max_alarm 521temp[1-*]_crit_alarm 522temp[1-*]_emergency_alarm 523 Limit alarm 524 0: no alarm 525 1: alarm 526 RO 527 528Each input channel may have an associated fault file. This can be used 529to notify open diodes, unconnected fans etc. where the hardware 530supports it. When this boolean has value 1, the measurement for that 531channel should not be trusted. 532 533fan[1-*]_fault 534temp[1-*]_fault 535 Input fault condition 536 0: no fault occured 537 1: fault condition 538 RO 539 540Some chips also offer the possibility to get beeped when an alarm occurs: 541 542beep_enable Master beep enable 543 0: no beeps 544 1: beeps 545 RW 546 547in[0-*]_beep 548curr[1-*]_beep 549fan[1-*]_beep 550temp[1-*]_beep 551 Channel beep 552 0: disable 553 1: enable 554 RW 555 556In theory, a chip could provide per-limit beep masking, but no such chip 557was seen so far. 558 559Old drivers provided a different, non-standard interface to alarms and 560beeps. These interface files are deprecated, but will be kept around 561for compatibility reasons: 562 563alarms Alarm bitmask. 564 RO 565 Integer representation of one to four bytes. 566 A '1' bit means an alarm. 567 Chips should be programmed for 'comparator' mode so that 568 the alarm will 'come back' after you read the register 569 if it is still valid. 570 Generally a direct representation of a chip's internal 571 alarm registers; there is no standard for the position 572 of individual bits. For this reason, the use of this 573 interface file for new drivers is discouraged. Use 574 individual *_alarm and *_fault files instead. 575 Bits are defined in kernel/include/sensors.h. 576 577beep_mask Bitmask for beep. 578 Same format as 'alarms' with the same bit locations, 579 use discouraged for the same reason. Use individual 580 *_beep files instead. 581 RW 582 583 584*********************** 585* Intrusion detection * 586*********************** 587 588intrusion[0-*]_alarm 589 Chassis intrusion detection 590 0: OK 591 1: intrusion detected 592 RW 593 Contrary to regular alarm flags which clear themselves 594 automatically when read, this one sticks until cleared by 595 the user. This is done by writing 0 to the file. Writing 596 other values is unsupported. 597 598intrusion[0-*]_beep 599 Chassis intrusion beep 600 0: disable 601 1: enable 602 RW 603 604 605sysfs attribute writes interpretation 606------------------------------------- 607 608hwmon sysfs attributes always contain numbers, so the first thing to do is to 609convert the input to a number, there are 2 ways todo this depending whether 610the number can be negative or not: 611unsigned long u = simple_strtoul(buf, NULL, 10); 612long s = simple_strtol(buf, NULL, 10); 613 614With buf being the buffer with the user input being passed by the kernel. 615Notice that we do not use the second argument of strto[u]l, and thus cannot 616tell when 0 is returned, if this was really 0 or is caused by invalid input. 617This is done deliberately as checking this everywhere would add a lot of 618code to the kernel. 619 620Notice that it is important to always store the converted value in an 621unsigned long or long, so that no wrap around can happen before any further 622checking. 623 624After the input string is converted to an (unsigned) long, the value should be 625checked if its acceptable. Be careful with further conversions on the value 626before checking it for validity, as these conversions could still cause a wrap 627around before the check. For example do not multiply the result, and only 628add/subtract if it has been divided before the add/subtract. 629 630What to do if a value is found to be invalid, depends on the type of the 631sysfs attribute that is being set. If it is a continuous setting like a 632tempX_max or inX_max attribute, then the value should be clamped to its 633limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not 634continuous like for example a tempX_type, then when an invalid value is 635written, -EINVAL should be returned. 636 637Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees): 638 639 long v = simple_strtol(buf, NULL, 10) / 1000; 640 v = SENSORS_LIMIT(v, -128, 127); 641 /* write v to register */ 642 643Example2, fan divider setting, valid values 2, 4 and 8: 644 645 unsigned long v = simple_strtoul(buf, NULL, 10); 646 647 switch (v) { 648 case 2: v = 1; break; 649 case 4: v = 2; break; 650 case 8: v = 3; break; 651 default: 652 return -EINVAL; 653 } 654 /* write v to register */ 655