Based on kernel version 2.6.26. Page generated on 2008-07-16 21:12 EST.
1 Naming and data format standards for sysfs files 2 ------------------------------------------------ 3 4 The libsensors library offers an interface to the raw sensors data 5 through the sysfs interface. See libsensors documentation and source for 6 further information. As of writing this document, libsensors 7 (from lm_sensors 2.8.3) is heavily chip-dependent. Adding or updating 8 support for any given chip requires modifying the library's code. 9 This is because libsensors was written for the procfs interface 10 older kernel modules were using, which wasn't standardized enough. 11 Recent versions of libsensors (from lm_sensors 2.8.2 and later) have 12 support for the sysfs interface, though. 13 14 The new sysfs interface was designed to be as chip-independent as 15 possible. 16 17 Note that motherboards vary widely in the connections to sensor chips. 18 There is no standard that ensures, for example, that the second 19 temperature sensor is connected to the CPU, or that the second fan is on 20 the CPU. Also, some values reported by the chips need some computation 21 before they make full sense. For example, most chips can only measure 22 voltages between 0 and +4V. Other voltages are scaled back into that 23 range using external resistors. Since the values of these resistors 24 can change from motherboard to motherboard, the conversions cannot be 25 hard coded into the driver and have to be done in user space. 26 27 For this reason, even if we aim at a chip-independent libsensors, it will 28 still require a configuration file (e.g. /etc/sensors.conf) for proper 29 values conversion, labeling of inputs and hiding of unused inputs. 30 31 An alternative method that some programs use is to access the sysfs 32 files directly. This document briefly describes the standards that the 33 drivers follow, so that an application program can scan for entries and 34 access this data in a simple and consistent way. That said, such programs 35 will have to implement conversion, labeling and hiding of inputs. For 36 this reason, it is still not recommended to bypass the library. 37 38 If you are developing a userspace application please send us feedback on 39 this standard. 40 41 Note that this standard isn't completely established yet, so it is subject 42 to changes. If you are writing a new hardware monitoring driver those 43 features can't seem to fit in this interface, please contact us with your 44 extension proposal. Keep in mind that backward compatibility must be 45 preserved. 46 47 Each chip gets its own directory in the sysfs /sys/devices tree. To 48 find all sensor chips, it is easier to follow the device symlinks from 49 /sys/class/hwmon/hwmon*. 50 51 All sysfs values are fixed point numbers. 52 53 There is only one value per file, unlike the older /proc specification. 54 The common scheme for files naming is: <type><number>_<item>. Usual 55 types for sensor chips are "in" (voltage), "temp" (temperature) and 56 "fan" (fan). Usual items are "input" (measured value), "max" (high 57 threshold, "min" (low threshold). Numbering usually starts from 1, 58 except for voltages which start from 0 (because most data sheets use 59 this). A number is always used for elements that can be present more 60 than once, even if there is a single element of the given type on the 61 specific chip. Other files do not refer to a specific element, so 62 they have a simple name, and no number. 63 64 Alarms are direct indications read from the chips. The drivers do NOT 65 make comparisons of readings to thresholds. This allows violations 66 between readings to be caught and alarmed. The exact definition of an 67 alarm (for example, whether a threshold must be met or must be exceeded 68 to cause an alarm) is chip-dependent. 69 70 When setting values of hwmon sysfs attributes, the string representation of 71 the desired value must be written, note that strings which are not a number 72 are interpreted as 0! For more on how written strings are interpreted see the 73 "sysfs attribute writes interpretation" section at the end of this file. 74 75 ------------------------------------------------------------------------- 76 77 [0-*] denotes any positive number starting from 0 78 [1-*] denotes any positive number starting from 1 79 RO read only value 80 RW read/write value 81 82 Read/write values may be read-only for some chips, depending on the 83 hardware implementation. 84 85 All entries (except name) are optional, and should only be created in a 86 given driver if the chip has the feature. 87 88 89 ******** 90 * Name * 91 ******** 92 93 name The chip name. 94 This should be a short, lowercase string, not containing 95 spaces nor dashes, representing the chip name. This is 96 the only mandatory attribute. 97 I2C devices get this attribute created automatically. 98 RO 99 100 101 ************ 102 * Voltages * 103 ************ 104 105 in[0-*]_min Voltage min value. 106 Unit: millivolt 107 RW 108 109 in[0-*]_max Voltage max value. 110 Unit: millivolt 111 RW 112 113 in[0-*]_input Voltage input value. 114 Unit: millivolt 115 RO 116 Voltage measured on the chip pin. 117 Actual voltage depends on the scaling resistors on the 118 motherboard, as recommended in the chip datasheet. 119 This varies by chip and by motherboard. 120 Because of this variation, values are generally NOT scaled 121 by the chip driver, and must be done by the application. 122 However, some drivers (notably lm87 and via686a) 123 do scale, because of internal resistors built into a chip. 124 These drivers will output the actual voltage. Rule of 125 thumb: drivers should report the voltage values at the 126 "pins" of the chip. 127 128 in[0-*]_label Suggested voltage channel label. 129 Text string 130 Should only be created if the driver has hints about what 131 this voltage channel is being used for, and user-space 132 doesn't. In all other cases, the label is provided by 133 user-space. 134 RO 135 136 cpu[0-*]_vid CPU core reference voltage. 137 Unit: millivolt 138 RO 139 Not always correct. 140 141 vrm Voltage Regulator Module version number. 142 RW (but changing it should no more be necessary) 143 Originally the VRM standard version multiplied by 10, but now 144 an arbitrary number, as not all standards have a version 145 number. 146 Affects the way the driver calculates the CPU core reference 147 voltage from the vid pins. 148 149 Also see the Alarms section for status flags associated with voltages. 150 151 152 ******** 153 * Fans * 154 ******** 155 156 fan[1-*]_min Fan minimum value 157 Unit: revolution/min (RPM) 158 RW 159 160 fan[1-*]_input Fan input value. 161 Unit: revolution/min (RPM) 162 RO 163 164 fan[1-*]_div Fan divisor. 165 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128). 166 RW 167 Some chips only support values 1, 2, 4 and 8. 168 Note that this is actually an internal clock divisor, which 169 affects the measurable speed range, not the read value. 170 171 fan[1-*]_target 172 Desired fan speed 173 Unit: revolution/min (RPM) 174 RW 175 Only makes sense if the chip supports closed-loop fan speed 176 control based on the measured fan speed. 177 178 fan[1-*]_label Suggested fan channel label. 179 Text string 180 Should only be created if the driver has hints about what 181 this fan channel is being used for, and user-space doesn't. 182 In all other cases, the label is provided by user-space. 183 RO 184 185 Also see the Alarms section for status flags associated with fans. 186 187 188 ******* 189 * PWM * 190 ******* 191 192 pwm[1-*] Pulse width modulation fan control. 193 Integer value in the range 0 to 255 194 RW 195 255 is max or 100%. 196 197 pwm[1-*]_enable 198 Fan speed control method: 199 0: no fan speed control (i.e. fan at full speed) 200 1: manual fan speed control enabled (using pwm[1-*]) 201 2+: automatic fan speed control enabled 202 Check individual chip documentation files for automatic mode 203 details. 204 RW 205 206 pwm[1-*]_mode 0: DC mode (direct current) 207 1: PWM mode (pulse-width modulation) 208 RW 209 210 pwm[1-*]_freq Base PWM frequency in Hz. 211 Only possibly available when pwmN_mode is PWM, but not always 212 present even then. 213 RW 214 215 pwm[1-*]_auto_channels_temp 216 Select which temperature channels affect this PWM output in 217 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc... 218 Which values are possible depend on the chip used. 219 RW 220 221 pwm[1-*]_auto_point[1-*]_pwm 222 pwm[1-*]_auto_point[1-*]_temp 223 pwm[1-*]_auto_point[1-*]_temp_hyst 224 Define the PWM vs temperature curve. Number of trip points is 225 chip-dependent. Use this for chips which associate trip points 226 to PWM output channels. 227 RW 228 229 OR 230 231 temp[1-*]_auto_point[1-*]_pwm 232 temp[1-*]_auto_point[1-*]_temp 233 temp[1-*]_auto_point[1-*]_temp_hyst 234 Define the PWM vs temperature curve. Number of trip points is 235 chip-dependent. Use this for chips which associate trip points 236 to temperature channels. 237 RW 238 239 240 **************** 241 * Temperatures * 242 **************** 243 244 temp[1-*]_type Sensor type selection. 245 Integers 1 to 6 246 RW 247 1: PII/Celeron Diode 248 2: 3904 transistor 249 3: thermal diode 250 4: thermistor 251 5: AMD AMDSI 252 6: Intel PECI 253 Not all types are supported by all chips 254 255 temp[1-*]_max Temperature max value. 256 Unit: millidegree Celsius (or millivolt, see below) 257 RW 258 259 temp[1-*]_min Temperature min value. 260 Unit: millidegree Celsius 261 RW 262 263 temp[1-*]_max_hyst 264 Temperature hysteresis value for max limit. 265 Unit: millidegree Celsius 266 Must be reported as an absolute temperature, NOT a delta 267 from the max value. 268 RW 269 270 temp[1-*]_input Temperature input value. 271 Unit: millidegree Celsius 272 RO 273 274 temp[1-*]_crit Temperature critical value, typically greater than 275 corresponding temp_max values. 276 Unit: millidegree Celsius 277 RW 278 279 temp[1-*]_crit_hyst 280 Temperature hysteresis value for critical limit. 281 Unit: millidegree Celsius 282 Must be reported as an absolute temperature, NOT a delta 283 from the critical value. 284 RW 285 286 temp[1-*]_offset 287 Temperature offset which is added to the temperature reading 288 by the chip. 289 Unit: millidegree Celsius 290 Read/Write value. 291 292 temp[1-*]_label Suggested temperature channel label. 293 Text string 294 Should only be created if the driver has hints about what 295 this temperature channel is being used for, and user-space 296 doesn't. In all other cases, the label is provided by 297 user-space. 298 RO 299 300 Some chips measure temperature using external thermistors and an ADC, and 301 report the temperature measurement as a voltage. Converting this voltage 302 back to a temperature (or the other way around for limits) requires 303 mathematical functions not available in the kernel, so the conversion 304 must occur in user space. For these chips, all temp* files described 305 above should contain values expressed in millivolt instead of millidegree 306 Celsius. In other words, such temperature channels are handled as voltage 307 channels by the driver. 308 309 Also see the Alarms section for status flags associated with temperatures. 310 311 312 ************ 313 * Currents * 314 ************ 315 316 Note that no known chip provides current measurements as of writing, 317 so this part is theoretical, so to say. 318 319 curr[1-*]_max Current max value 320 Unit: milliampere 321 RW 322 323 curr[1-*]_min Current min value. 324 Unit: milliampere 325 RW 326 327 curr[1-*]_input Current input value 328 Unit: milliampere 329 RO 330 331 ********* 332 * Power * 333 ********* 334 335 power[1-*]_average Average power use 336 Unit: microWatt 337 RO 338 339 power[1-*]_average_highest Historical average maximum power use 340 Unit: microWatt 341 RO 342 343 power[1-*]_average_lowest Historical average minimum power use 344 Unit: microWatt 345 RO 346 347 power[1-*]_input Instantaneous power use 348 Unit: microWatt 349 RO 350 351 power[1-*]_input_highest Historical maximum power use 352 Unit: microWatt 353 RO 354 355 power[1-*]_input_lowest Historical minimum power use 356 Unit: microWatt 357 RO 358 359 power[1-*]_reset_history Reset input_highest, input_lowest, 360 average_highest and average_lowest. 361 WO 362 363 ********** 364 * Alarms * 365 ********** 366 367 Each channel or limit may have an associated alarm file, containing a 368 boolean value. 1 means than an alarm condition exists, 0 means no alarm. 369 370 Usually a given chip will either use channel-related alarms, or 371 limit-related alarms, not both. The driver should just reflect the hardware 372 implementation. 373 374 in[0-*]_alarm 375 fan[1-*]_alarm 376 temp[1-*]_alarm 377 Channel alarm 378 0: no alarm 379 1: alarm 380 RO 381 382 OR 383 384 in[0-*]_min_alarm 385 in[0-*]_max_alarm 386 fan[1-*]_min_alarm 387 temp[1-*]_min_alarm 388 temp[1-*]_max_alarm 389 temp[1-*]_crit_alarm 390 Limit alarm 391 0: no alarm 392 1: alarm 393 RO 394 395 Each input channel may have an associated fault file. This can be used 396 to notify open diodes, unconnected fans etc. where the hardware 397 supports it. When this boolean has value 1, the measurement for that 398 channel should not be trusted. 399 400 in[0-*]_fault 401 fan[1-*]_fault 402 temp[1-*]_fault 403 Input fault condition 404 0: no fault occured 405 1: fault condition 406 RO 407 408 Some chips also offer the possibility to get beeped when an alarm occurs: 409 410 beep_enable Master beep enable 411 0: no beeps 412 1: beeps 413 RW 414 415 in[0-*]_beep 416 fan[1-*]_beep 417 temp[1-*]_beep 418 Channel beep 419 0: disable 420 1: enable 421 RW 422 423 In theory, a chip could provide per-limit beep masking, but no such chip 424 was seen so far. 425 426 Old drivers provided a different, non-standard interface to alarms and 427 beeps. These interface files are deprecated, but will be kept around 428 for compatibility reasons: 429 430 alarms Alarm bitmask. 431 RO 432 Integer representation of one to four bytes. 433 A '1' bit means an alarm. 434 Chips should be programmed for 'comparator' mode so that 435 the alarm will 'come back' after you read the register 436 if it is still valid. 437 Generally a direct representation of a chip's internal 438 alarm registers; there is no standard for the position 439 of individual bits. For this reason, the use of this 440 interface file for new drivers is discouraged. Use 441 individual *_alarm and *_fault files instead. 442 Bits are defined in kernel/include/sensors.h. 443 444 beep_mask Bitmask for beep. 445 Same format as 'alarms' with the same bit locations, 446 use discouraged for the same reason. Use individual 447 *_beep files instead. 448 RW 449 450 451 sysfs attribute writes interpretation 452 ------------------------------------- 453 454 hwmon sysfs attributes always contain numbers, so the first thing to do is to 455 convert the input to a number, there are 2 ways todo this depending whether 456 the number can be negative or not: 457 unsigned long u = simple_strtoul(buf, NULL, 10); 458 long s = simple_strtol(buf, NULL, 10); 459 460 With buf being the buffer with the user input being passed by the kernel. 461 Notice that we do not use the second argument of strto[u]l, and thus cannot 462 tell when 0 is returned, if this was really 0 or is caused by invalid input. 463 This is done deliberately as checking this everywhere would add a lot of 464 code to the kernel. 465 466 Notice that it is important to always store the converted value in an 467 unsigned long or long, so that no wrap around can happen before any further 468 checking. 469 470 After the input string is converted to an (unsigned) long, the value should be 471 checked if its acceptable. Be careful with further conversions on the value 472 before checking it for validity, as these conversions could still cause a wrap 473 around before the check. For example do not multiply the result, and only 474 add/subtract if it has been divided before the add/subtract. 475 476 What to do if a value is found to be invalid, depends on the type of the 477 sysfs attribute that is being set. If it is a continuous setting like a 478 tempX_max or inX_max attribute, then the value should be clamped to its 479 limits using SENSORS_LIMIT(value, min_limit, max_limit). If it is not 480 continuous like for example a tempX_type, then when an invalid value is 481 written, -EINVAL should be returned. 482 483 Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees): 484 485 long v = simple_strtol(buf, NULL, 10) / 1000; 486 v = SENSORS_LIMIT(v, -128, 127); 487 /* write v to register */ 488 489 Example2, fan divider setting, valid values 2, 4 and 8: 490 491 unsigned long v = simple_strtoul(buf, NULL, 10); 492 493 switch (v) { 494 case 2: v = 1; break; 495 case 4: v = 2; break; 496 case 8: v = 3; break; 497 default: 498 return -EINVAL; 499 } 500 /* write v to register */