| Naming and data format standards for sysfs files | |
| ------------------------------------------------ | |
| The libsensors library offers an interface to the raw sensors data | |
| through the sysfs interface. See libsensors documentation and source for | |
| further information. As of writing this document, libsensors | |
| (from lm_sensors 2.8.3) is heavily chip-dependent. Adding or updating | |
| support for any given chip requires modifying the library's code. | |
| This is because libsensors was written for the procfs interface | |
| older kernel modules were using, which wasn't standardized enough. | |
| Recent versions of libsensors (from lm_sensors 2.8.2 and later) have | |
| support for the sysfs interface, though. | |
| The new sysfs interface was designed to be as chip-independent as | |
| possible. | |
| Note that motherboards vary widely in the connections to sensor chips. | |
| There is no standard that ensures, for example, that the second | |
| temperature sensor is connected to the CPU, or that the second fan is on | |
| the CPU. Also, some values reported by the chips need some computation | |
| before they make full sense. For example, most chips can only measure | |
| voltages between 0 and +4V. Other voltages are scaled back into that | |
| range using external resistors. Since the values of these resistors | |
| can change from motherboard to motherboard, the conversions cannot be | |
| hard coded into the driver and have to be done in user space. | |
| For this reason, even if we aim at a chip-independent libsensors, it will | |
| still require a configuration file (e.g. /etc/sensors.conf) for proper | |
| values conversion, labeling of inputs and hiding of unused inputs. | |
| An alternative method that some programs use is to access the sysfs | |
| files directly. This document briefly describes the standards that the | |
| drivers follow, so that an application program can scan for entries and | |
| access this data in a simple and consistent way. That said, such programs | |
| will have to implement conversion, labeling and hiding of inputs. For | |
| this reason, it is still not recommended to bypass the library. | |
| If you are developing a userspace application please send us feedback on | |
| this standard. | |
| Note that this standard isn't completely established yet, so it is subject | |
| to changes. If you are writing a new hardware monitoring driver those | |
| features can't seem to fit in this interface, please contact us with your | |
| extension proposal. Keep in mind that backward compatibility must be | |
| preserved. | |
| Each chip gets its own directory in the sysfs /sys/devices tree. To | |
| find all sensor chips, it is easier to follow the device symlinks from | |
| /sys/class/hwmon/hwmon*. | |
| All sysfs values are fixed point numbers. | |
| There is only one value per file, unlike the older /proc specification. | |
| The common scheme for files naming is: <type><number>_<item>. Usual | |
| types for sensor chips are "in" (voltage), "temp" (temperature) and | |
| "fan" (fan). Usual items are "input" (measured value), "max" (high | |
| threshold, "min" (low threshold). Numbering usually starts from 1, | |
| except for voltages which start from 0 (because most data sheets use | |
| this). A number is always used for elements that can be present more | |
| than once, even if there is a single element of the given type on the | |
| specific chip. Other files do not refer to a specific element, so | |
| they have a simple name, and no number. | |
| Alarms are direct indications read from the chips. The drivers do NOT | |
| make comparisons of readings to thresholds. This allows violations | |
| between readings to be caught and alarmed. The exact definition of an | |
| alarm (for example, whether a threshold must be met or must be exceeded | |
| to cause an alarm) is chip-dependent. | |
| ------------------------------------------------------------------------- | |
| [0-*] denotes any positive number starting from 0 | |
| [1-*] denotes any positive number starting from 1 | |
| RO read only value | |
| RW read/write value | |
| Read/write values may be read-only for some chips, depending on the | |
| hardware implementation. | |
| All entries are optional, and should only be created in a given driver | |
| if the chip has the feature. | |
| ************ | |
| * Voltages * | |
| ************ | |
| in[0-*]_min Voltage min value. | |
| Unit: millivolt | |
| RW | |
| in[0-*]_max Voltage max value. | |
| Unit: millivolt | |
| RW | |
| in[0-*]_input Voltage input value. | |
| Unit: millivolt | |
| RO | |
| Voltage measured on the chip pin. | |
| Actual voltage depends on the scaling resistors on the | |
| motherboard, as recommended in the chip datasheet. | |
| This varies by chip and by motherboard. | |
| Because of this variation, values are generally NOT scaled | |
| by the chip driver, and must be done by the application. | |
| However, some drivers (notably lm87 and via686a) | |
| do scale, because of internal resistors built into a chip. | |
| These drivers will output the actual voltage. | |
| Typical usage: | |
| in0_* CPU #1 voltage (not scaled) | |
| in1_* CPU #2 voltage (not scaled) | |
| in2_* 3.3V nominal (not scaled) | |
| in3_* 5.0V nominal (scaled) | |
| in4_* 12.0V nominal (scaled) | |
| in5_* -12.0V nominal (scaled) | |
| in6_* -5.0V nominal (scaled) | |
| in7_* varies | |
| in8_* varies | |
| cpu[0-*]_vid CPU core reference voltage. | |
| Unit: millivolt | |
| RO | |
| Not always correct. | |
| vrm Voltage Regulator Module version number. | |
| RW (but changing it should no more be necessary) | |
| Originally the VRM standard version multiplied by 10, but now | |
| an arbitrary number, as not all standards have a version | |
| number. | |
| Affects the way the driver calculates the CPU core reference | |
| voltage from the vid pins. | |
| Also see the Alarms section for status flags associated with voltages. | |
| ******** | |
| * Fans * | |
| ******** | |
| fan[1-*]_min Fan minimum value | |
| Unit: revolution/min (RPM) | |
| RW | |
| fan[1-*]_input Fan input value. | |
| Unit: revolution/min (RPM) | |
| RO | |
| fan[1-*]_div Fan divisor. | |
| Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128). | |
| RW | |
| Some chips only support values 1, 2, 4 and 8. | |
| Note that this is actually an internal clock divisor, which | |
| affects the measurable speed range, not the read value. | |
| Also see the Alarms section for status flags associated with fans. | |
| ******* | |
| * PWM * | |
| ******* | |
| pwm[1-*] Pulse width modulation fan control. | |
| Integer value in the range 0 to 255 | |
| RW | |
| 255 is max or 100%. | |
| pwm[1-*]_enable | |
| Switch PWM on and off. | |
| Not always present even if fan*_pwm is. | |
| 0: turn off | |
| 1: turn on in manual mode | |
| 2+: turn on in automatic mode | |
| Check individual chip documentation files for automatic mode details. | |
| RW | |
| pwm[1-*]_mode | |
| 0: DC mode | |
| 1: PWM mode | |
| RW | |
| pwm[1-*]_auto_channels_temp | |
| Select which temperature channels affect this PWM output in | |
| auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc... | |
| Which values are possible depend on the chip used. | |
| RW | |
| pwm[1-*]_auto_point[1-*]_pwm | |
| pwm[1-*]_auto_point[1-*]_temp | |
| pwm[1-*]_auto_point[1-*]_temp_hyst | |
| Define the PWM vs temperature curve. Number of trip points is | |
| chip-dependent. Use this for chips which associate trip points | |
| to PWM output channels. | |
| RW | |
| OR | |
| temp[1-*]_auto_point[1-*]_pwm | |
| temp[1-*]_auto_point[1-*]_temp | |
| temp[1-*]_auto_point[1-*]_temp_hyst | |
| Define the PWM vs temperature curve. Number of trip points is | |
| chip-dependent. Use this for chips which associate trip points | |
| to temperature channels. | |
| RW | |
| **************** | |
| * Temperatures * | |
| **************** | |
| temp[1-*]_type Sensor type selection. | |
| Integers 1 to 4 or thermistor Beta value (typically 3435) | |
| RW | |
| 1: PII/Celeron Diode | |
| 2: 3904 transistor | |
| 3: thermal diode | |
| 4: thermistor (default/unknown Beta) | |
| Not all types are supported by all chips | |
| temp[1-*]_max Temperature max value. | |
| Unit: millidegree Celsius (or millivolt, see below) | |
| RW | |
| temp[1-*]_min Temperature min value. | |
| Unit: millidegree Celsius | |
| RW | |
| temp[1-*]_max_hyst | |
| Temperature hysteresis value for max limit. | |
| Unit: millidegree Celsius | |
| Must be reported as an absolute temperature, NOT a delta | |
| from the max value. | |
| RW | |
| temp[1-*]_input Temperature input value. | |
| Unit: millidegree Celsius | |
| RO | |
| temp[1-*]_crit Temperature critical value, typically greater than | |
| corresponding temp_max values. | |
| Unit: millidegree Celsius | |
| RW | |
| temp[1-*]_crit_hyst | |
| Temperature hysteresis value for critical limit. | |
| Unit: millidegree Celsius | |
| Must be reported as an absolute temperature, NOT a delta | |
| from the critical value. | |
| RW | |
| temp[1-4]_offset | |
| Temperature offset which is added to the temperature reading | |
| by the chip. | |
| Unit: millidegree Celsius | |
| Read/Write value. | |
| If there are multiple temperature sensors, temp1_* is | |
| generally the sensor inside the chip itself, | |
| reported as "motherboard temperature". temp2_* to | |
| temp4_* are generally sensors external to the chip | |
| itself, for example the thermal diode inside the CPU or | |
| a thermistor nearby. | |
| Some chips measure temperature using external thermistors and an ADC, and | |
| report the temperature measurement as a voltage. Converting this voltage | |
| back to a temperature (or the other way around for limits) requires | |
| mathematical functions not available in the kernel, so the conversion | |
| must occur in user space. For these chips, all temp* files described | |
| above should contain values expressed in millivolt instead of millidegree | |
| Celsius. In other words, such temperature channels are handled as voltage | |
| channels by the driver. | |
| Also see the Alarms section for status flags associated with temperatures. | |
| ************ | |
| * Currents * | |
| ************ | |
| Note that no known chip provides current measurements as of writing, | |
| so this part is theoretical, so to say. | |
| curr[1-*]_max Current max value | |
| Unit: milliampere | |
| RW | |
| curr[1-*]_min Current min value. | |
| Unit: milliampere | |
| RW | |
| curr[1-*]_input Current input value | |
| Unit: milliampere | |
| RO | |
| ********** | |
| * Alarms * | |
| ********** | |
| Each channel or limit may have an associated alarm file, containing a | |
| boolean value. 1 means than an alarm condition exists, 0 means no alarm. | |
| Usually a given chip will either use channel-related alarms, or | |
| limit-related alarms, not both. The driver should just reflect the hardware | |
| implementation. | |
| in[0-*]_alarm | |
| fan[1-*]_alarm | |
| temp[1-*]_alarm | |
| Channel alarm | |
| 0: no alarm | |
| 1: alarm | |
| RO | |
| OR | |
| in[0-*]_min_alarm | |
| in[0-*]_max_alarm | |
| fan[1-*]_min_alarm | |
| temp[1-*]_min_alarm | |
| temp[1-*]_max_alarm | |
| temp[1-*]_crit_alarm | |
| Limit alarm | |
| 0: no alarm | |
| 1: alarm | |
| RO | |
| Each input channel may have an associated fault file. This can be used | |
| to notify open diodes, unconnected fans etc. where the hardware | |
| supports it. When this boolean has value 1, the measurement for that | |
| channel should not be trusted. | |
| in[0-*]_input_fault | |
| fan[1-*]_input_fault | |
| temp[1-*]_input_fault | |
| Input fault condition | |
| 0: no fault occured | |
| 1: fault condition | |
| RO | |
| Some chips also offer the possibility to get beeped when an alarm occurs: | |
| beep_enable Master beep enable | |
| 0: no beeps | |
| 1: beeps | |
| RW | |
| in[0-*]_beep | |
| fan[1-*]_beep | |
| temp[1-*]_beep | |
| Channel beep | |
| 0: disable | |
| 1: enable | |
| RW | |
| In theory, a chip could provide per-limit beep masking, but no such chip | |
| was seen so far. | |
| Old drivers provided a different, non-standard interface to alarms and | |
| beeps. These interface files are deprecated, but will be kept around | |
| for compatibility reasons: | |
| alarms Alarm bitmask. | |
| RO | |
| Integer representation of one to four bytes. | |
| A '1' bit means an alarm. | |
| Chips should be programmed for 'comparator' mode so that | |
| the alarm will 'come back' after you read the register | |
| if it is still valid. | |
| Generally a direct representation of a chip's internal | |
| alarm registers; there is no standard for the position | |
| of individual bits. For this reason, the use of this | |
| interface file for new drivers is discouraged. Use | |
| individual *_alarm and *_fault files instead. | |
| Bits are defined in kernel/include/sensors.h. | |
| beep_mask Bitmask for beep. | |
| Same format as 'alarms' with the same bit locations, | |
| use discouraged for the same reason. Use individual | |
| *_beep files instead. | |
| RW | |
| ********* | |
| * Other * | |
| ********* | |
| eeprom Raw EEPROM data in binary form. | |
| RO | |
| pec Enable or disable PEC (SMBus only) | |
| 0: disable | |
| 1: enable | |
| RW |