diff options
Diffstat (limited to 'Documentation/i2c/sysfs-interface')
| -rw-r--r-- | Documentation/i2c/sysfs-interface | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/Documentation/i2c/sysfs-interface b/Documentation/i2c/sysfs-interface new file mode 100644 index 000000000000..346400519d0d --- /dev/null +++ b/Documentation/i2c/sysfs-interface @@ -0,0 +1,274 @@ +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. |