| 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 | |
| more further information. As of writing this document, libsensors | |
| (from lm_sensors 2.8.3) is heavily chip-dependant. 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-independant 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-independant 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, even important ones. One more reason to use the library instead | |
| of accessing sysfs files directly. | |
| Each chip gets its own directory in the sysfs /sys/devices tree. To | |
| find all sensor chips, it is easier to follow the symlinks from | |
| /sys/i2c/devices/ | |
| All sysfs values are fixed point numbers. To get the true value of some | |
| of the values, you should divide by the specified value. | |
| 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. | |
| ------------------------------------------------------------------------- | |
| ************ | |
| * Voltages * | |
| ************ | |
| in[0-8]_min Voltage min value. | |
| Unit: millivolt | |
| Read/Write | |
| in[0-8]_max Voltage max value. | |
| Unit: millivolt | |
| Read/Write | |
| in[0-8]_input Voltage input value. | |
| Unit: millivolt | |
| Read only | |
| 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, with various degrees of success. | |
| 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-1]_vid CPU core reference voltage. | |
| Unit: millivolt | |
| Read only. | |
| Not always correct. | |
| vrm Voltage Regulator Module version number. | |
| Read only. | |
| Two digit number, first is major version, second is | |
| minor version. | |
| Affects the way the driver calculates the CPU core reference | |
| voltage from the vid pins. | |
| ******** | |
| * Fans * | |
| ******** | |
| fan[1-3]_min Fan minimum value | |
| Unit: revolution/min (RPM) | |
| Read/Write. | |
| fan[1-3]_input Fan input value. | |
| Unit: revolution/min (RPM) | |
| Read only. | |
| fan[1-3]_div Fan divisor. | |
| Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128). | |
| 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. | |
| ******* | |
| * PWM * | |
| ******* | |
| pwm[1-3] Pulse width modulation fan control. | |
| Integer value in the range 0 to 255 | |
| Read/Write | |
| 255 is max or 100%. | |
| pwm[1-3]_enable | |
| Switch PWM on and off. | |
| Not always present even if fan*_pwm is. | |
| 0 to turn off | |
| 1 to turn on in manual mode | |
| 2 to turn on in automatic mode | |
| Read/Write | |
| 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. | |
| 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. | |
| 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. | |
| **************** | |
| * Temperatures * | |
| **************** | |
| temp[1-3]_type Sensor type selection. | |
| Integers 1, 2, 3 or thermistor Beta value (3435) | |
| Read/Write. | |
| 1: PII/Celeron Diode | |
| 2: 3904 transistor | |
| 3: thermal diode | |
| Not all types are supported by all chips | |
| temp[1-4]_max Temperature max value. | |
| Unit: millidegree Celcius | |
| Read/Write value. | |
| temp[1-3]_min Temperature min value. | |
| Unit: millidegree Celcius | |
| Read/Write value. | |
| temp[1-3]_max_hyst | |
| Temperature hysteresis value for max limit. | |
| Unit: millidegree Celcius | |
| Must be reported as an absolute temperature, NOT a delta | |
| from the max value. | |
| Read/Write value. | |
| temp[1-4]_input Temperature input value. | |
| Unit: millidegree Celcius | |
| Read only value. | |
| temp[1-4]_crit Temperature critical value, typically greater than | |
| corresponding temp_max values. | |
| Unit: millidegree Celcius | |
| Read/Write value. | |
| temp[1-2]_crit_hyst | |
| Temperature hysteresis value for critical limit. | |
| Unit: millidegree Celcius | |
| Must be reported as an absolute temperature, NOT a delta | |
| from the critical value. | |
| 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. | |
| ************ | |
| * Currents * | |
| ************ | |
| Note that no known chip provides current measurements as of writing, | |
| so this part is theoretical, so to say. | |
| curr[1-n]_max Current max value | |
| Unit: milliampere | |
| Read/Write. | |
| curr[1-n]_min Current min value. | |
| Unit: milliampere | |
| Read/Write. | |
| curr[1-n]_input Current input value | |
| Unit: milliampere | |
| Read only. | |
| ********* | |
| * Other * | |
| ********* | |
| alarms Alarm bitmask. | |
| Read only. | |
| 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. | |
| Bits are defined in kernel/include/sensors.h. | |
| beep_enable Beep/interrupt enable | |
| 0 to disable. | |
| 1 to enable. | |
| Read/Write | |
| beep_mask Bitmask for beep. | |
| Same format as 'alarms' with the same bit locations. | |
| Read/Write | |
| eeprom Raw EEPROM data in binary form. | |
| Read only. |