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