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. See libsensors documentation and source for 6further information. As of writing this document, libsensors 7(from lm_sensors 2.8.3) is heavily chip-dependent. Adding or updating 8support for any given chip requires modifying the library's code. 9This is because libsensors was written for the procfs interface 10older kernel modules were using, which wasn't standardized enough. 11Recent versions of libsensors (from lm_sensors 2.8.2 and later) have 12support for the sysfs interface, though. 13 14The new sysfs interface was designed to be as chip-independent as 15possible. 16 17Note that motherboards vary widely in the connections to sensor chips. 18There is no standard that ensures, for example, that the second 19temperature sensor is connected to the CPU, or that the second fan is on 20the CPU. Also, some values reported by the chips need some computation 21before they make full sense. For example, most chips can only measure 22voltages between 0 and +4V. Other voltages are scaled back into that 23range using external resistors. Since the values of these resistors 24can change from motherboard to motherboard, the conversions cannot be 25hard coded into the driver and have to be done in user space. 26 27For this reason, even if we aim at a chip-independent libsensors, it will 28still require a configuration file (e.g. /etc/sensors.conf) for proper 29values conversion, labeling of inputs and hiding of unused inputs. 30 31An alternative method that some programs use is to access the sysfs 32files directly. This document briefly describes the standards that the 33drivers follow, so that an application program can scan for entries and 34access this data in a simple and consistent way. That said, such programs 35will have to implement conversion, labeling and hiding of inputs. For 36this reason, it is still not recommended to bypass the library. 37 38If you are developing a userspace application please send us feedback on 39this standard. 40 41Note that this standard isn't completely established yet, so it is subject 42to changes. If you are writing a new hardware monitoring driver those 43features can't seem to fit in this interface, please contact us with your 44extension proposal. Keep in mind that backward compatibility must be 45preserved. 46 47Each chip gets its own directory in the sysfs /sys/devices tree. To 48find all sensor chips, it is easier to follow the device symlinks from 49/sys/class/hwmon/hwmon*. 50 51All sysfs values are fixed point numbers. 52 53There is only one value per file, unlike the older /proc specification. 54The common scheme for files naming is: <type><number>_<item>. Usual 55types for sensor chips are "in" (voltage), "temp" (temperature) and 56"fan" (fan). Usual items are "input" (measured value), "max" (high 57threshold, "min" (low threshold). Numbering usually starts from 1, 58except for voltages which start from 0 (because most data sheets use 59this). A number is always used for elements that can be present more 60than once, even if there is a single element of the given type on the 61specific chip. Other files do not refer to a specific element, so 62they have a simple name, and no number. 63 64Alarms are direct indications read from the chips. The drivers do NOT 65make comparisons of readings to thresholds. This allows violations 66between readings to be caught and alarmed. The exact definition of an 67alarm (for example, whether a threshold must be met or must be exceeded 68to cause an alarm) is chip-dependent. 69 70 71------------------------------------------------------------------------- 72 73[0-*] denotes any positive number starting from 0 74[1-*] denotes any positive number starting from 1 75RO read only value 76RW read/write value 77 78Read/write values may be read-only for some chips, depending on the 79hardware implementation. 80 81All entries are optional, and should only be created in a given driver 82if the chip has the feature. 83 84************ 85* Voltages * 86************ 87 88in[0-*]_min Voltage min value. 89 Unit: millivolt 90 RW 91 92in[0-*]_max Voltage max value. 93 Unit: millivolt 94 RW 95 96in[0-*]_input Voltage input value. 97 Unit: millivolt 98 RO 99 Voltage measured on the chip pin. 100 Actual voltage depends on the scaling resistors on the 101 motherboard, as recommended in the chip datasheet. 102 This varies by chip and by motherboard. 103 Because of this variation, values are generally NOT scaled 104 by the chip driver, and must be done by the application. 105 However, some drivers (notably lm87 and via686a) 106 do scale, because of internal resistors built into a chip. 107 These drivers will output the actual voltage. 108 109 Typical usage: 110 in0_* CPU #1 voltage (not scaled) 111 in1_* CPU #2 voltage (not scaled) 112 in2_* 3.3V nominal (not scaled) 113 in3_* 5.0V nominal (scaled) 114 in4_* 12.0V nominal (scaled) 115 in5_* -12.0V nominal (scaled) 116 in6_* -5.0V nominal (scaled) 117 in7_* varies 118 in8_* varies 119 120cpu[0-*]_vid CPU core reference voltage. 121 Unit: millivolt 122 RO 123 Not always correct. 124 125vrm Voltage Regulator Module version number. 126 RW (but changing it should no more be necessary) 127 Originally the VRM standard version multiplied by 10, but now 128 an arbitrary number, as not all standards have a version 129 number. 130 Affects the way the driver calculates the CPU core reference 131 voltage from the vid pins. 132 133Also see the Alarms section for status flags associated with voltages. 134 135 136******** 137* Fans * 138******** 139 140fan[1-*]_min Fan minimum value 141 Unit: revolution/min (RPM) 142 RW 143 144fan[1-*]_input Fan input value. 145 Unit: revolution/min (RPM) 146 RO 147 148fan[1-*]_div Fan divisor. 149 Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128). 150 RW 151 Some chips only support values 1, 2, 4 and 8. 152 Note that this is actually an internal clock divisor, which 153 affects the measurable speed range, not the read value. 154 155fan[1-*]_target 156 Desired fan speed 157 Unit: revolution/min (RPM) 158 RW 159 Only makes sense if the chip supports closed-loop fan speed 160 control based on the measured fan speed. 161 162Also see the Alarms section for status flags associated with fans. 163 164 165******* 166* PWM * 167******* 168 169pwm[1-*] Pulse width modulation fan control. 170 Integer value in the range 0 to 255 171 RW 172 255 is max or 100%. 173 174pwm[1-*]_enable 175 Switch PWM on and off. 176 Not always present even if pwmN is. 177 0: turn off 178 1: turn on in manual mode 179 2+: turn on in automatic mode 180 Check individual chip documentation files for automatic mode 181 details. 182 RW 183 184pwm[1-*]_mode 0: DC mode (direct current) 185 1: PWM mode (pulse-width modulation) 186 RW 187 188pwm[1-*]_freq Base PWM frequency in Hz. 189 Only possibly available when pwmN_mode is PWM, but not always 190 present even then. 191 RW 192 193pwm[1-*]_auto_channels_temp 194 Select which temperature channels affect this PWM output in 195 auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc... 196 Which values are possible depend on the chip used. 197 RW 198 199pwm[1-*]_auto_point[1-*]_pwm 200pwm[1-*]_auto_point[1-*]_temp 201pwm[1-*]_auto_point[1-*]_temp_hyst 202 Define the PWM vs temperature curve. Number of trip points is 203 chip-dependent. Use this for chips which associate trip points 204 to PWM output channels. 205 RW 206 207OR 208 209temp[1-*]_auto_point[1-*]_pwm 210temp[1-*]_auto_point[1-*]_temp 211temp[1-*]_auto_point[1-*]_temp_hyst 212 Define the PWM vs temperature curve. Number of trip points is 213 chip-dependent. Use this for chips which associate trip points 214 to temperature channels. 215 RW 216 217 218**************** 219* Temperatures * 220**************** 221 222temp[1-*]_type Sensor type selection. 223 Integers 1 to 6 or thermistor Beta value (typically 3435) 224 RW 225 1: PII/Celeron Diode 226 2: 3904 transistor 227 3: thermal diode 228 4: thermistor (default/unknown Beta) 229 5: AMD AMDSI 230 6: Intel PECI 231 Not all types are supported by all chips 232 233temp[1-*]_max Temperature max value. 234 Unit: millidegree Celsius (or millivolt, see below) 235 RW 236 237temp[1-*]_min Temperature min value. 238 Unit: millidegree Celsius 239 RW 240 241temp[1-*]_max_hyst 242 Temperature hysteresis value for max limit. 243 Unit: millidegree Celsius 244 Must be reported as an absolute temperature, NOT a delta 245 from the max value. 246 RW 247 248temp[1-*]_input Temperature input value. 249 Unit: millidegree Celsius 250 RO 251 252temp[1-*]_crit Temperature critical value, typically greater than 253 corresponding temp_max values. 254 Unit: millidegree Celsius 255 RW 256 257temp[1-*]_crit_hyst 258 Temperature hysteresis value for critical limit. 259 Unit: millidegree Celsius 260 Must be reported as an absolute temperature, NOT a delta 261 from the critical value. 262 RW 263 264temp[1-4]_offset 265 Temperature offset which is added to the temperature reading 266 by the chip. 267 Unit: millidegree Celsius 268 Read/Write value. 269 270 If there are multiple temperature sensors, temp1_* is 271 generally the sensor inside the chip itself, 272 reported as "motherboard temperature". temp2_* to 273 temp4_* are generally sensors external to the chip 274 itself, for example the thermal diode inside the CPU or 275 a thermistor nearby. 276 277Some chips measure temperature using external thermistors and an ADC, and 278report the temperature measurement as a voltage. Converting this voltage 279back to a temperature (or the other way around for limits) requires 280mathematical functions not available in the kernel, so the conversion 281must occur in user space. For these chips, all temp* files described 282above should contain values expressed in millivolt instead of millidegree 283Celsius. In other words, such temperature channels are handled as voltage 284channels by the driver. 285 286Also see the Alarms section for status flags associated with temperatures. 287 288 289************ 290* Currents * 291************ 292 293Note that no known chip provides current measurements as of writing, 294so this part is theoretical, so to say. 295 296curr[1-*]_max Current max value 297 Unit: milliampere 298 RW 299 300curr[1-*]_min Current min value. 301 Unit: milliampere 302 RW 303 304curr[1-*]_input Current input value 305 Unit: milliampere 306 RO 307 308 309********** 310* Alarms * 311********** 312 313Each channel or limit may have an associated alarm file, containing a 314boolean value. 1 means than an alarm condition exists, 0 means no alarm. 315 316Usually a given chip will either use channel-related alarms, or 317limit-related alarms, not both. The driver should just reflect the hardware 318implementation. 319 320in[0-*]_alarm 321fan[1-*]_alarm 322temp[1-*]_alarm 323 Channel alarm 324 0: no alarm 325 1: alarm 326 RO 327 328OR 329 330in[0-*]_min_alarm 331in[0-*]_max_alarm 332fan[1-*]_min_alarm 333temp[1-*]_min_alarm 334temp[1-*]_max_alarm 335temp[1-*]_crit_alarm 336 Limit alarm 337 0: no alarm 338 1: alarm 339 RO 340 341Each input channel may have an associated fault file. This can be used 342to notify open diodes, unconnected fans etc. where the hardware 343supports it. When this boolean has value 1, the measurement for that 344channel should not be trusted. 345 346in[0-*]_input_fault 347fan[1-*]_input_fault 348temp[1-*]_input_fault 349 Input fault condition 350 0: no fault occured 351 1: fault condition 352 RO 353 354Some chips also offer the possibility to get beeped when an alarm occurs: 355 356beep_enable Master beep enable 357 0: no beeps 358 1: beeps 359 RW 360 361in[0-*]_beep 362fan[1-*]_beep 363temp[1-*]_beep 364 Channel beep 365 0: disable 366 1: enable 367 RW 368 369In theory, a chip could provide per-limit beep masking, but no such chip 370was seen so far. 371 372Old drivers provided a different, non-standard interface to alarms and 373beeps. These interface files are deprecated, but will be kept around 374for compatibility reasons: 375 376alarms Alarm bitmask. 377 RO 378 Integer representation of one to four bytes. 379 A '1' bit means an alarm. 380 Chips should be programmed for 'comparator' mode so that 381 the alarm will 'come back' after you read the register 382 if it is still valid. 383 Generally a direct representation of a chip's internal 384 alarm registers; there is no standard for the position 385 of individual bits. For this reason, the use of this 386 interface file for new drivers is discouraged. Use 387 individual *_alarm and *_fault files instead. 388 Bits are defined in kernel/include/sensors.h. 389 390beep_mask Bitmask for beep. 391 Same format as 'alarms' with the same bit locations, 392 use discouraged for the same reason. Use individual 393 *_beep files instead. 394 RW 395 396 397********* 398* Other * 399********* 400 401eeprom Raw EEPROM data in binary form. 402 RO 403 404pec Enable or disable PEC (SMBus only) 405 0: disable 406 1: enable 407 RW 408