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 68Attribute access 69---------------- 70 71Hardware monitoring sysfs attributes are displayed by unrestricted userspace 72applications. For this reason, all standard ABI attributes shall be world 73readable. Writeable standard ABI attributes shall be writeable only for 74privileged users. 75 76------------------------------------------------------------------------- 77 78======= =========================================== 79`[0-*]` denotes any positive number starting from 0 80`[1-*]` denotes any positive number starting from 1 81RO read only value 82WO write only value 83RW read/write value 84======= =========================================== 85 86Read/write values may be read-only for some chips, depending on the 87hardware implementation. 88 89All entries (except name) are optional, and should only be created in a 90given driver if the chip has the feature. 91 92See Documentation/ABI/testing/sysfs-class-hwmon for a complete description 93of the attributes. 94 95***************** 96Global attributes 97***************** 98 99`name` 100 The chip name. 101 102`label` 103 A descriptive label that allows to uniquely identify a device 104 within the system. 105 106`update_interval` 107 The interval at which the chip will update readings. 108 109`update_interval_us` 110 The interval at which the chip will update readings, 111 expressed in microseconds for finer resolution. 112 113 114******** 115Voltages 116******** 117 118`in[0-*]_min` 119 Voltage min value. 120 121`in[0-*]_lcrit` 122 Voltage critical min value. 123 124`in[0-*]_max` 125 Voltage max value. 126 127`in[0-*]_crit` 128 Voltage critical max value. 129 130`in[0-*]_input` 131 Voltage input value. 132 133`in[0-*]_average` 134 Average voltage 135 136`in[0-*]_lowest` 137 Historical minimum voltage 138 139`in[0-*]_highest` 140 Historical maximum voltage 141 142`in[0-*]_reset_history` 143 Reset inX_lowest and inX_highest 144 145`in_reset_history` 146 Reset inX_lowest and inX_highest for all sensors 147 148`in[0-*]_label` 149 Suggested voltage channel label. 150 151`in[0-*]_enable` 152 Enable or disable the sensors. 153 154`cpu[0-*]_vid` 155 CPU core reference voltage. 156 157`vrm` 158 Voltage Regulator Module version number. 159 160`in[0-*]_rated_min` 161 Minimum rated voltage. 162 163`in[0-*]_rated_max` 164 Maximum rated voltage. 165 166Also see the Alarms section for status flags associated with voltages. 167 168 169**** 170Fans 171**** 172 173`fan[1-*]_min` 174 Fan minimum value 175 176`fan[1-*]_max` 177 Fan maximum value 178 179`fan[1-*]_input` 180 Fan input value. 181 182`fan[1-*]_div` 183 Fan divisor. 184 185`fan[1-*]_pulses` 186 Number of tachometer pulses per fan revolution. 187 188`fan[1-*]_target` 189 Desired fan speed 190 191`fan[1-*]_label` 192 Suggested fan channel label. 193 194`fan[1-*]_enable` 195 Enable or disable the sensors. 196 197Also see the Alarms section for status flags associated with fans. 198 199 200*** 201PWM 202*** 203 204`pwm[1-*]` 205 Pulse width modulation fan control. 206 207`pwm[1-*]_enable` 208 Fan speed control method. 209 210`pwm[1-*]_mode` 211 direct current or pulse-width modulation. 212 213`pwm[1-*]_freq` 214 Base PWM frequency in Hz. 215 216`pwm[1-*]_auto_channels_temp` 217 Select which temperature channels affect this PWM output in 218 auto mode. 219 220`pwm[1-*]_auto_point[1-*]_pwm` / `pwm[1-*]_auto_point[1-*]_temp` / `pwm[1-*]_auto_point[1-*]_temp_hyst` 221 Define the PWM vs temperature curve. 222 223`temp[1-*]_auto_point[1-*]_pwm` / `temp[1-*]_auto_point[1-*]_temp` / `temp[1-*]_auto_point[1-*]_temp_hyst` 224 Define the PWM vs temperature curve. 225 226There is a third case where trip points are associated to both PWM output 227channels and temperature channels: the PWM values are associated to PWM 228output channels while the temperature values are associated to temperature 229channels. In that case, the result is determined by the mapping between 230temperature inputs and PWM outputs. When several temperature inputs are 231mapped to a given PWM output, this leads to several candidate PWM values. 232The actual result is up to the chip, but in general the highest candidate 233value (fastest fan speed) wins. 234 235 236************ 237Temperatures 238************ 239 240`temp[1-*]_type` 241 Sensor type selection. 242 243`temp[1-*]_max` 244 Temperature max value. 245 246`temp[1-*]_min` 247 Temperature min value. 248 249`temp[1-*]_max_hyst` 250 Temperature hysteresis value for max limit. 251 252`temp[1-*]_min_hyst` 253 Temperature hysteresis value for min limit. 254 255`temp[1-*]_input` 256 Temperature input value. 257 258`temp[1-*]_crit` 259 Temperature critical max value, typically greater than 260 corresponding temp_max values. 261 262`temp[1-*]_crit_hyst` 263 Temperature hysteresis value for critical limit. 264 265`temp[1-*]_emergency` 266 Temperature emergency max value, for chips supporting more than 267 two upper temperature limits. 268 269`temp[1-*]_emergency_hyst` 270 Temperature hysteresis value for emergency limit. 271 272`temp[1-*]_lcrit` 273 Temperature critical min value, typically lower than 274 corresponding temp_min values. 275 276`temp[1-*]_lcrit_hyst` 277 Temperature hysteresis value for critical min limit. 278 279`temp[1-*]_offset` 280 Temperature offset which is added to the temperature reading 281 by the chip. 282 283`temp[1-*]_label` 284 Suggested temperature channel label. 285 286`temp[1-*]_lowest` 287 Historical minimum temperature 288 289`temp[1-*]_highest` 290 Historical maximum temperature 291 292`temp[1-*]_reset_history` 293 Reset temp_lowest and temp_highest 294 295`temp_reset_history` 296 Reset temp_lowest and temp_highest for all sensors 297 298`temp[1-*]_enable` 299 Enable or disable the sensors. 300 301`temp[1-*]_rated_min` 302 Minimum rated temperature. 303 304`temp[1-*]_rated_max` 305 Maximum rated temperature. 306 307Some chips measure temperature using external thermistors and an ADC, and 308report the temperature measurement as a voltage. Converting this voltage 309back to a temperature (or the other way around for limits) requires 310mathematical functions not available in the kernel, so the conversion 311must occur in user space. For these chips, all temp* files described 312above should contain values expressed in millivolt instead of millidegree 313Celsius. In other words, such temperature channels are handled as voltage 314channels by the driver. 315 316Also see the Alarms section for status flags associated with temperatures. 317 318 319******** 320Currents 321******** 322 323`curr[1-*]_max` 324 Current max value. 325 326`curr[1-*]_min` 327 Current min value. 328 329`curr[1-*]_lcrit` 330 Current critical low value 331 332`curr[1-*]_crit` 333 Current critical high value. 334 335`curr[1-*]_input` 336 Current input value. 337 338`curr[1-*]_average` 339 Average current use. 340 341`curr[1-*]_lowest` 342 Historical minimum current. 343 344`curr[1-*]_highest` 345 Historical maximum current. 346 347`curr[1-*]_reset_history` 348 Reset currX_lowest and currX_highest 349 350 WO 351 352`curr_reset_history` 353 Reset currX_lowest and currX_highest for all sensors. 354 355`curr[1-*]_enable` 356 Enable or disable the sensors. 357 358`curr[1-*]_rated_min` 359 Minimum rated current. 360 361`curr[1-*]_rated_max` 362 Maximum rated current. 363 364Also see the Alarms section for status flags associated with currents. 365 366***** 367Power 368***** 369 370`power[1-*]_average` 371 Average power use. 372 373`power[1-*]_average_interval` 374 Power use averaging interval. 375 376`power[1-*]_average_interval_max` 377 Maximum power use averaging interval. 378 379`power[1-*]_average_interval_min` 380 Minimum power use averaging interval. 381 382`power[1-*]_average_highest` 383 Historical average maximum power use 384 385`power[1-*]_average_lowest` 386 Historical average minimum power use 387 388`power[1-*]_average_max` 389 A poll notification is sent to `power[1-*]_average` when 390 power use rises above this value. 391 392`power[1-*]_average_min` 393 A poll notification is sent to `power[1-*]_average` when 394 power use sinks below this value. 395 396`power[1-*]_input` 397 Instantaneous power use. 398 399`power[1-*]_input_highest` 400 Historical maximum power use 401 402`power[1-*]_input_lowest` 403 Historical minimum power use. 404 405`power[1-*]_reset_history` 406 Reset input_highest, input_lowest, average_highest and 407 average_lowest. 408 409`power[1-*]_accuracy` 410 Accuracy of the power meter. 411 412`power[1-*]_cap` 413 If power use rises above this limit, the 414 system should take action to reduce power use. 415 416`power[1-*]_cap_hyst` 417 Margin of hysteresis built around capping and notification. 418 419`power[1-*]_cap_max` 420 Maximum cap that can be set. 421 422`power[1-*]_cap_min` 423 Minimum cap that can be set. 424 425`power[1-*]_max` 426 Maximum power. 427 428`power[1-*]_crit` 429 Critical maximum power. 430 431 If power rises to or above this limit, the 432 system is expected take drastic action to reduce 433 power consumption, such as a system shutdown or 434 a forced powerdown of some devices. 435 436 Unit: microWatt 437 438 RW 439 440`power[1-*]_enable` 441 Enable or disable the sensors. 442 443 When disabled the sensor read will return 444 -ENODATA. 445 446 - 1: Enable 447 - 0: Disable 448 449 RW 450 451`power[1-*]_rated_min` 452 Minimum rated power. 453 454 Unit: microWatt 455 456 RO 457 458`power[1-*]_rated_max` 459 Maximum rated power. 460 461 Unit: microWatt 462 463 RO 464 465Also see the Alarms section for status flags associated with power readings. 466 467****** 468Energy 469****** 470 471`energy[1-*]_input` 472 Cumulative energy use 473 474 Unit: microJoule 475 476 RO 477 478`energy[1-*]_enable` 479 Enable or disable the sensors. 480 481 When disabled the sensor read will return 482 -ENODATA. 483 484 - 1: Enable 485 - 0: Disable 486 487 RW 488 489******** 490Humidity 491******** 492 493`humidity[1-*]_input` 494 Humidity. 495 496`humidity[1-*]_enable` 497 Enable or disable the sensors. 498 499`humidity[1-*]_rated_min` 500 Minimum rated humidity. 501 502`humidity[1-*]_rated_max` 503 Maximum rated humidity. 504 505****** 506Alarms 507****** 508 509Each channel or limit may have an associated alarm file, containing a 510boolean value. 1 means than an alarm condition exists, 0 means no alarm. 511 512Usually a given chip will either use channel-related alarms, or 513limit-related alarms, not both. The driver should just reflect the hardware 514implementation. 515 516+-------------------------------+-----------------------+ 517| **`in[0-*]_alarm`, | Channel alarm | 518| `curr[1-*]_alarm`, | | 519| `power[1-*]_alarm`, | - 0: no alarm | 520| `fan[1-*]_alarm`, | - 1: alarm | 521| `temp[1-*]_alarm`** | | 522| | RO | 523+-------------------------------+-----------------------+ 524 525**OR** 526 527+-------------------------------+-----------------------+ 528| **`in[0-*]_min_alarm`, | Limit alarm | 529| `in[0-*]_max_alarm`, | | 530| `in[0-*]_lcrit_alarm`, | - 0: no alarm | 531| `in[0-*]_crit_alarm`, | - 1: alarm | 532| `curr[1-*]_min_alarm`, | | 533| `curr[1-*]_max_alarm`, | RO | 534| `curr[1-*]_lcrit_alarm`, | | 535| `curr[1-*]_crit_alarm`, | | 536| `power[1-*]_cap_alarm`, | | 537| `power[1-*]_max_alarm`, | | 538| `power[1-*]_crit_alarm`, | | 539| `fan[1-*]_min_alarm`, | | 540| `fan[1-*]_max_alarm`, | | 541| `temp[1-*]_min_alarm`, | | 542| `temp[1-*]_max_alarm`, | | 543| `temp[1-*]_lcrit_alarm`, | | 544| `temp[1-*]_crit_alarm`, | | 545| `temp[1-*]_emergency_alarm`** | | 546+-------------------------------+-----------------------+ 547 548Each input channel may have an associated fault file. This can be used 549to notify open diodes, unconnected fans etc. where the hardware 550supports it. When this boolean has value 1, the measurement for that 551channel should not be trusted. 552 553`fan[1-*]_fault` / `temp[1-*]_fault` 554 Input fault condition. 555 556Some chips also offer the possibility to get beeped when an alarm occurs: 557 558`beep_enable` 559 Master beep enable. 560 561`in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`, 562 Channel beep. 563 564In theory, a chip could provide per-limit beep masking, but no such chip 565was seen so far. 566 567Old drivers provided a different, non-standard interface to alarms and 568beeps. These interface files are deprecated, but will be kept around 569for compatibility reasons: 570 571`alarms` 572 Alarm bitmask. 573 574`beep_mask` 575 Bitmask for beep. 576 577 578******************* 579Intrusion detection 580******************* 581 582`intrusion[0-*]_alarm` 583 Chassis intrusion detection. 584 585`intrusion[0-*]_beep` 586 Chassis intrusion beep. 587 588**************************** 589Average sample configuration 590**************************** 591 592Devices allowing for reading {in,power,curr,temp}_average values may export 593attributes for controlling number of samples used to compute average. 594 595+--------------+---------------------------------------------------------------+ 596| samples | Sets number of average samples for all types of measurements. | 597| | | 598| | RW | 599+--------------+---------------------------------------------------------------+ 600| in_samples | Sets number of average samples for specific type of | 601| power_samples| measurements. | 602| curr_samples | | 603| temp_samples | Note that on some devices it won't be possible to set all of | 604| | them to different values so changing one might also change | 605| | some others. | 606| | | 607| | RW | 608+--------------+---------------------------------------------------------------+ 609 610sysfs attribute writes interpretation 611------------------------------------- 612 613hwmon sysfs attributes always contain numbers, so the first thing to do is to 614convert the input to a number, there are 2 ways todo this depending whether 615the number can be negative or not:: 616 617 unsigned long u = simple_strtoul(buf, NULL, 10); 618 long s = simple_strtol(buf, NULL, 10); 619 620With buf being the buffer with the user input being passed by the kernel. 621Notice that we do not use the second argument of strto[u]l, and thus cannot 622tell when 0 is returned, if this was really 0 or is caused by invalid input. 623This is done deliberately as checking this everywhere would add a lot of 624code to the kernel. 625 626Notice that it is important to always store the converted value in an 627unsigned long or long, so that no wrap around can happen before any further 628checking. 629 630After the input string is converted to an (unsigned) long, the value should be 631checked if its acceptable. Be careful with further conversions on the value 632before checking it for validity, as these conversions could still cause a wrap 633around before the check. For example do not multiply the result, and only 634add/subtract if it has been divided before the add/subtract. 635 636What to do if a value is found to be invalid, depends on the type of the 637sysfs attribute that is being set. If it is a continuous setting like a 638tempX_max or inX_max attribute, then the value should be clamped to its 639limits using clamp_val(value, min_limit, max_limit). If it is not continuous 640like for example a tempX_type, then when an invalid value is written, 641-EINVAL should be returned. 642 643Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):: 644 645 long v = simple_strtol(buf, NULL, 10) / 1000; 646 v = clamp_val(v, -128, 127); 647 /* write v to register */ 648 649Example2, fan divider setting, valid values 2, 4 and 8:: 650 651 unsigned long v = simple_strtoul(buf, NULL, 10); 652 653 switch (v) { 654 case 2: v = 1; break; 655 case 4: v = 2; break; 656 case 8: v = 3; break; 657 default: 658 return -EINVAL; 659 } 660 /* write v to register */ 661