1 files changed, 412 insertions, 0 deletions

diff --git a/Documentation/hwmon/lm93 b/Documentation/hwmon/lm93
new file mode 100644
index 000000000000..4e4a1dc1d2da
--- /dev/null
+++ b/Documentation/hwmon/lm93
@@ -0,0 +1,412 @@
+Kernel driver lm93
+==================
+
+Supported chips:
+  * National Semiconductor LM93
+    Prefix 'lm93'
+    Addresses scanned: I2C 0x2c-0x2e
+    Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf
+
+Author:
+        Mark M. Hoffman <mhoffman@lightlink.com>
+        Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com>
+        Adapted to 2.6.20 by Carsten Emde <ce@osadl.org>
+        Modified for mainline integration by Hans J. Koch <hjk@linutronix.de>
+
+Module Parameters
+-----------------
+
+(specific to LM93)
+* init: integer
+  Set to non-zero to force some initializations (default is 0).
+* disable_block: integer
+  A "0" allows SMBus block data transactions if the host supports them.  A "1"
+  disables SMBus block data transactions.  The default is 0.
+* vccp_limit_type: integer array (2)
+  Configures in7 and in8 limit type, where 0 means absolute and non-zero
+  means relative.  "Relative" here refers to "Dynamic Vccp Monitoring using
+  VID" from the datasheet.  It greatly simplifies the interface to allow
+  only one set of limits (absolute or relative) to be in operation at a
+  time (even though the hardware is capable of enabling both).  There's
+  not a compelling use case for enabling both at once, anyway.  The default
+  is "0,0".
+* vid_agtl: integer
+  A "0" configures the VID pins for V(ih) = 2.1V min, V(il) = 0.8V max.
+  A "1" configures the VID pins for V(ih) = 0.8V min, V(il) = 0.4V max.
+  (The latter setting is referred to as AGTL+ Compatible in the datasheet.)
+  I.e. this parameter controls the VID pin input thresholds; if your VID
+  inputs are not working, try changing this.  The default value is "0".
+
+(common among sensor drivers)
+* force: short array (min = 1, max = 48)
+  List of adapter,address pairs to assume to be present.  Autodetection
+  of the target device will still be attempted.  Use one of the more
+  specific force directives below if this doesn't detect the device.
+* force_lm93: short array (min = 1, max = 48)
+  List of adapter,address pairs which are unquestionably assumed to contain
+  a 'lm93' chip
+* ignore: short array (min = 1, max = 48)
+  List of adapter,address pairs not to scan
+* ignore_range: short array (min = 1, max = 48)
+  List of adapter,start-addr,end-addr triples not to scan
+* probe: short array (min = 1, max = 48)
+  List of adapter,address pairs to scan additionally
+* probe_range: short array (min = 1, max = 48)
+  List of adapter,start-addr,end-addr triples to scan additionally
+
+
+Hardware Description
+--------------------
+
+(from the datasheet)
+
+The LM93, hardware monitor, has a two wire digital interface compatible with
+SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote
+diode connected transistors as well as its own die and 16 power supply
+voltages. To set fan speed, the LM93 has two PWM outputs that are each
+controlled by up to four temperature zones. The fancontrol algorithm is lookup
+table based. The LM93 includes a digital filter that can be invoked to smooth
+temperature readings for better control of fan speed. The LM93 has four
+tachometer inputs to measure fan speed. Limit and status registers for all
+measured values are included. The LM93 builds upon the functionality of
+previous motherboard management ASICs and uses some of the LM85 s features
+(i.e. smart tachometer mode). It also adds measurement and control support
+for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual
+processor Xeon class motherboard with a minimum of external components.
+
+
+Driver Description
+------------------
+
+This driver implements support for the National Semiconductor LM93.
+
+
+User Interface
+--------------
+
+#PROCHOT:
+
+The LM93 can monitor two #PROCHOT signals.  The results are found in the
+sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max,
+and prochot2_max.  prochot1_max and prochot2_max contain the user limits
+for #PROCHOT1 and #PROCHOT2, respectively.  prochot1 and prochot2 contain
+the current readings for the most recent complete time interval.  The
+value of prochot1_avg and prochot2_avg is something like a 2 period
+exponential moving average (but not quite - check the datasheet). Note
+that this third value is calculated by the chip itself.  All values range
+from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%.
+
+The monitoring intervals for the two #PROCHOT signals is also configurable.
+These intervals can be found in the sysfs files prochot1_interval and
+prochot2_interval.  The values in these files specify the intervals for
+#P1_PROCHOT and #P2_PROCHOT, respectively.  Selecting a value not in this
+list will cause the driver to use the next largest interval.  The available
+intervals are:
+
+#PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372
+
+It is possible to configure the LM93 to logically short the two #PROCHOT
+signals.  I.e. when #P1_PROCHOT is asserted, the LM93 will automatically
+assert #P2_PROCHOT, and vice-versa.  This mode is enabled by writing a
+non-zero integer to the sysfs file prochot_short.
+
+The LM93 can also override the #PROCHOT pins by driving a PWM signal onto
+one or both of them.  When overridden, the signal has a period of 3.56 mS,
+a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and
+a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle).
+
+The sysfs files prochot1_override and prochot2_override contain boolean
+intgers which enable or disable the override function for #P1_PROCHOT and
+#P2_PROCHOT, respectively.  The sysfs file prochot_override_duty_cycle
+contains a value controlling the duty cycle for the PWM signal used when
+the override function is enabled.  This value ranges from 0 to 15, with 0
+indicating minimum duty cycle and 15 indicating maximum.
+
+#VRD_HOT:
+
+The LM93 can monitor two #VRD_HOT signals. The results are found in the
+sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for
+which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These
+files are read-only.
+
+Smart Tach Mode:
+
+(from the datasheet)
+
+        If a fan is driven using a low-side drive PWM, the tachometer
+        output of the fan is corrupted. The LM93 includes smart tachometer
+        circuitry that allows an accurate tachometer reading to be
+        achieved despite the signal corruption.  In smart tach mode all
+        four signals are measured within 4 seconds.
+
+Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
+the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach.  A zero
+will disable the function for that fan.  Note that Smart tach mode cannot be
+enabled if the PWM output frequency is 22500 Hz (see below).
+
+Manual PWM:
+
+The LM93 has a fixed or override mode for the two PWM outputs (although, there
+are still some conditions that will override even this mode - see section
+15.10.6 of the datasheet for details.)  The sysfs files pwm1_override
+and pwm2_override are used to enable this mode; each is a boolean integer
+where 0 disables and 1 enables the manual control mode.  The sysfs files pwm1
+and pwm2 are used to set the manual duty cycle; each is an integer (0-255)
+where 0 is 0% duty cycle, and 255 is 100%.  Note that the duty cycle values
+are constrained by the hardware. Selecting a value which is not available
+will cause the driver to use the next largest value.  Also note: when manual
+PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty
+cycle chosen by the h/w.
+
+PWM Output Frequency:
+
+The LM93 supports several different frequencies for the PWM output channels.
+The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The
+frequency values are constrained by the hardware.  Selecting a value which is
+not available will cause the driver to use the next largest value.  Also note
+that this parameter has implications for the Smart Tach Mode (see above).
+
+PWM Output Frequencies: 12, 36, 48, 60, 72, 84, 96, 22500 (h/w default)
+
+Automatic PWM:
+
+The LM93 is capable of complex automatic fan control, with many different
+points of configuration.  To start, each PWM output can be bound to any
+combination of eight control sources.  The final PWM is the largest of all
+individual control sources to which the PWM output is bound.
+
+The eight control sources are: temp1-temp4 (aka "zones" in the datasheet),
+#PROCHOT 1 & 2, and #VRDHOT 1 & 2.  The bindings are expressed as a bitmask
+in the sysfs files pwm<n>_auto_channels, where a "1" enables the binding, and
+ a "0" disables it. The h/w default is 0x0f (all temperatures bound).
+
+        0x01 - Temp 1
+        0x02 - Temp 2
+        0x04 - Temp 3
+        0x08 - Temp 4
+        0x10 - #PROCHOT 1
+        0x20 - #PROCHOT 2
+        0x40 - #VRDHOT 1
+        0x80 - #VRDHOT 2
+
+The function y = f(x) takes a source temperature x to a PWM output y.  This
+function of the LM93 is derived from a base temperature and a table of 12
+temperature offsets.  The base temperature is expressed in degrees C in the
+sysfs files temp<n>_auto_base.  The offsets are expressed in cumulative
+degrees C, with the value of offset <i> for temperature value <n> being
+contained in the file temp<n>_auto_offset<i>.  E.g. if the base temperature
+is 40C:
+
+     offset #   temp<n>_auto_offset<i>  range           pwm
+         1              0               -                25.00%
+         2              0               -                28.57%
+         3              1               40C - 41C        32.14%
+         4              1               41C - 42C        35.71%
+         5              2               42C - 44C        39.29%
+         6              2               44C - 46C        42.86%
+         7              2               48C - 50C        46.43%
+         8              2               50C - 52C        50.00%
+         9              2               52C - 54C        53.57%
+        10              2               54C - 56C        57.14%
+        11              2               56C - 58C        71.43%
+        12              2               58C - 60C        85.71%
+                                        > 60C           100.00%
+
+Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments.
+
+There is an independent base temperature for each temperature channel. Note,
+however, there are only two tables of offsets: one each for temp[12] and
+temp[34].  Therefore, any change to e.g. temp1_auto_offset<i> will also
+affect temp2_auto_offset<i>.
+
+The LM93 can also apply hysteresis to the offset table, to prevent unwanted
+oscillation between two steps in the offsets table.  These values are found in
+the sysfs files temp<n>_auto_offset_hyst.  The value in this file has the
+same representation as in temp<n>_auto_offset<i>.
+
+If a temperature reading falls below the base value for that channel, the LM93
+will use the minimum PWM value.  These values are found in the sysfs files
+temp<n>_auto_pwm_min.  Note, there are only two minimums: one each for temp[12]
+and temp[34].  Therefore, any change to e.g. temp1_auto_pwm_min will also
+affect temp2_auto_pwm_min.
+
+PWM Spin-Up Cycle:
+
+A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to
+some value > 0%.  The LM93 supports a minimum duty cycle during spin-up.  These
+values are found in the sysfs files pwm<n>_auto_spinup_min. The value in this
+file has the same representation as other PWM duty cycle values. The
+duration of the spin-up cycle is also configurable.  These values are found in
+the sysfs files pwm<n>_auto_spinup_time. The value in this file is
+the spin-up time in seconds.  The available spin-up times are constrained by
+the hardware.  Selecting a value which is not available will cause the driver
+to use the next largest value.
+
+Spin-up Durations: 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0,
+                   2.0, 4.0
+
+#PROCHOT and #VRDHOT PWM Ramping:
+
+If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output
+channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete
+steps. The duration of each step is configurable. There are two files, with
+one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp.
+The available ramp times are constrained by the hardware.  Selecting a value
+which is not available will cause the driver to use the next largest value.
+
+Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals
+
+Fan Boost:
+
+For each temperature channel, there is a boost temperature: if the channel
+exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%.
+This limit is expressed in degrees C in the sysfs files temp<n>_auto_boost.
+There is also a hysteresis temperature for this function: after the boost
+limit is reached, the temperature channel must drop below this value before
+the boost function is disabled.  This temperature is also expressed in degrees
+C in the sysfs files temp<n>_auto_boost_hyst.
+
+GPIO Pins:
+
+The LM93 can monitor the logic level of four dedicated GPIO pins as well as the
+four tach input pins.  GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively.
+All eight GPIOs are read by reading the bitmask in the sysfs file gpio.  The
+LSB is GPIO0, and the MSB is GPIO7.
+
+
+LM93 Unique sysfs Files
+-----------------------
+
+        file                    description
+        -------------------------------------------------------------
+
+        prochot<n>              current #PROCHOT %
+
+        prochot<n>_avg          moving average #PROCHOT %
+
+        prochot<n>_max          limit #PROCHOT %
+
+        prochot_short           enable or disable logical #PROCHOT pin short
+
+        prochot<n>_override     force #PROCHOT assertion as PWM
+
+        prochot_override_duty_cycle
+                                duty cycle for the PWM signal used when
+                                #PROCHOT is overridden
+
+        prochot<n>_interval     #PROCHOT PWM sampling interval
+
+        vrdhot<n>               0 means negated, 1 means asserted
+
+        fan<n>_smart_tach       enable or disable smart tach mode
+
+        pwm<n>_auto_channels    select control sources for PWM outputs
+
+        pwm<n>_auto_spinup_min  minimum duty cycle during spin-up
+
+        pwm<n>_auto_spinup_time duration of spin-up
+
+        pwm_auto_prochot_ramp   ramp time per step when #PROCHOT asserted
+
+        pwm_auto_vrdhot_ramp    ramp time per step when #VRDHOT asserted
+
+        temp<n>_auto_base       temperature channel base
+
+        temp<n>_auto_offset[1-12]
+                                temperature channel offsets
+
+        temp<n>_auto_offset_hyst
+                                temperature channel offset hysteresis
+
+        temp<n>_auto_boost      temperature channel boost (PWMs to 100%) limit
+
+        temp<n>_auto_boost_hyst temperature channel boost hysteresis
+
+        gpio                    input state of 8 GPIO pins; read-only
+
+
+Sample Configuration File
+-------------------------
+
+Here is a sample LM93 chip config for sensors.conf:
+
+---------- cut here ----------
+chip "lm93-*"
+
+# VOLTAGE INPUTS
+
+        # labels and scaling based on datasheet recommendations
+        label in1       "+12V1"
+        compute in1     @ * 12.945, @ / 12.945
+        set in1_min     12 * 0.90
+        set in1_max     12 * 1.10
+
+        label in2       "+12V2"
+        compute in2     @ * 12.945, @ / 12.945
+        set in2_min     12 * 0.90
+        set in2_max     12 * 1.10
+
+        label in3       "+12V3"
+        compute in3     @ * 12.945, @ / 12.945
+        set in3_min     12 * 0.90
+        set in3_max     12 * 1.10
+
+        label in4       "FSB_Vtt"
+
+        label in5       "3GIO"
+
+        label in6       "ICH_Core"
+
+        label in7       "Vccp1"
+
+        label in8       "Vccp2"
+
+        label in9       "+3.3V"
+        set in9_min     3.3 * 0.90
+        set in9_max     3.3 * 1.10
+
+        label in10      "+5V"
+        set in10_min    5.0 * 0.90
+        set in10_max    5.0 * 1.10
+
+        label in11      "SCSI_Core"
+
+        label in12      "Mem_Core"
+
+        label in13      "Mem_Vtt"
+
+        label in14      "Gbit_Core"
+
+        # Assuming R1/R2 = 4.1143, and 3.3V reference
+        # -12V = (4.1143 + 1) * (@ - 3.3) + 3.3
+        label in15      "-12V"
+        compute in15 @ * 5.1143 - 13.57719, (@ + 13.57719) / 5.1143
+        set in15_min    -12 * 0.90
+        set in15_max    -12 * 1.10
+
+        label in16      "+3.3VSB"
+        set in16_min    3.3 * 0.90
+        set in16_max    3.3 * 1.10
+
+# TEMPERATURE INPUTS
+
+        label temp1     "CPU1"
+        label temp2     "CPU2"
+        label temp3     "LM93"
+
+# TACHOMETER INPUTS
+
+        label fan1      "Fan1"
+        set fan1_min    3000
+        label fan2      "Fan2"
+        set fan2_min    3000
+        label fan3      "Fan3"
+        set fan3_min    3000
+        label fan4      "Fan4"
+        set fan4_min    3000
+
+# PWM OUTPUTS
+
+        label pwm1      "CPU1"
+        label pwm2      "CPU2"
+