--- /dev/null
+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 to 4 or thermistor Beta value (typically 3435)
+ Read/Write.
+ 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-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.
+
+alarms_in Alarm bitmask relative to in (voltage) channels
+ Read only
+ A '1' bit means an alarm, LSB corresponds to in0 and so on
+ Prefered to 'alarms' for newer chips
+
+alarms_fan Alarm bitmask relative to fan channels
+ Read only
+ A '1' bit means an alarm, LSB corresponds to fan1 and so on
+ Prefered to 'alarms' for newer chips
+
+alarms_temp Alarm bitmask relative to temp (temperature) channels
+ Read only
+ A '1' bit means an alarm, LSB corresponds to temp1 and so on
+ Prefered to 'alarms' for newer chips
+
+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.
+
+pec Enable or disable PEC (SMBus only)
+ Read/Write
git://git.onelab.eu / linux-2.6.git / blobdiff