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.