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