Merge tag 'bitmain-soc-5.2' of git://git.kernel.org/pub/scm/linux/kernel/git/mani...
[sfrench/cifs-2.6.git] / Documentation / hwmon / lm85
1 Kernel driver lm85
2 ==================
3
4 Supported chips:
5   * National Semiconductor LM85 (B and C versions)
6     Prefix: 'lm85b' or 'lm85c'
7     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
8     Datasheet: http://www.national.com/pf/LM/LM85.html
9   * Texas Instruments LM96000
10     Prefix: 'lm9600'
11     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
12     Datasheet: http://www.ti.com/lit/ds/symlink/lm96000.pdf
13   * Analog Devices ADM1027
14     Prefix: 'adm1027'
15     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
16     Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADM1027
17   * Analog Devices ADT7463
18     Prefix: 'adt7463'
19     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
20     Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7463
21   * Analog Devices ADT7468
22     Prefix: 'adt7468'
23     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
24     Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7468
25   * SMSC EMC6D100, SMSC EMC6D101
26     Prefix: 'emc6d100'
27     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
28     Datasheet: http://www.smsc.com/media/Downloads_Public/discontinued/6d100.pdf 
29   * SMSC EMC6D102
30     Prefix: 'emc6d102'
31     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
32     Datasheet: http://www.smsc.com/main/catalog/emc6d102.html
33   * SMSC EMC6D103
34     Prefix: 'emc6d103'
35     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
36     Datasheet: http://www.smsc.com/main/catalog/emc6d103.html
37   * SMSC EMC6D103S
38     Prefix: 'emc6d103s'
39     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
40     Datasheet: http://www.smsc.com/main/catalog/emc6d103s.html
41
42 Authors:
43         Philip Pokorny <ppokorny@penguincomputing.com>,
44         Frodo Looijaard <frodol@dds.nl>,
45         Richard Barrington <rich_b_nz@clear.net.nz>,
46         Margit Schubert-While <margitsw@t-online.de>,
47         Justin Thiessen <jthiessen@penguincomputing.com>
48
49 Description
50 -----------
51
52 This driver implements support for the National Semiconductor LM85 and
53 compatible chips including the Analog Devices ADM1027, ADT7463, ADT7468 and
54 SMSC EMC6D10x chips family.
55
56 The LM85 uses the 2-wire interface compatible with the SMBUS 2.0
57 specification. Using an analog to digital converter it measures three (3)
58 temperatures and five (5) voltages. It has four (4) 16-bit counters for
59 measuring fan speed. Five (5) digital inputs are provided for sampling the
60 VID signals from the processor to the VRM. Lastly, there are three (3) PWM
61 outputs that can be used to control fan speed.
62
63 The voltage inputs have internal scaling resistors so that the following
64 voltage can be measured without external resistors:
65
66   2.5V, 3.3V, 5V, 12V, and CPU core voltage (2.25V)
67
68 The temperatures measured are one internal diode, and two remote diodes.
69 Remote 1 is generally the CPU temperature. These inputs are designed to
70 measure a thermal diode like the one in a Pentium 4 processor in a socket
71 423 or socket 478 package. They can also measure temperature using a
72 transistor like the 2N3904.
73
74 A sophisticated control system for the PWM outputs is designed into the
75 LM85 that allows fan speed to be adjusted automatically based on any of the
76 three temperature sensors. Each PWM output is individually adjustable and
77 programmable. Once configured, the LM85 will adjust the PWM outputs in
78 response to the measured temperatures without further host intervention.
79 This feature can also be disabled for manual control of the PWM's.
80
81 Each of the measured inputs (voltage, temperature, fan speed) has
82 corresponding high/low limit values. The LM85 will signal an ALARM if any
83 measured value exceeds either limit.
84
85 The LM85 samples all inputs continuously. The lm85 driver will not read
86 the registers more often than once a second. Further, configuration data is
87 only read once each 5 minutes. There is twice as much config data as
88 measurements, so this would seem to be a worthwhile optimization.
89
90 Special Features
91 ----------------
92
93 The LM85 has four fan speed monitoring modes. The ADM1027 has only two.
94 Both have special circuitry to compensate for PWM interactions with the
95 TACH signal from the fans. The ADM1027 can be configured to measure the
96 speed of a two wire fan, but the input conditioning circuitry is different
97 for 3-wire and 2-wire mode. For this reason, the 2-wire fan modes are not
98 exposed to user control. The BIOS should initialize them to the correct
99 mode. If you've designed your own ADM1027, you'll have to modify the
100 init_client function and add an insmod parameter to set this up.
101
102 To smooth the response of fans to changes in temperature, the LM85 has an
103 optional filter for smoothing temperatures. The ADM1027 has the same
104 config option but uses it to rate limit the changes to fan speed instead.
105
106 The ADM1027, ADT7463 and ADT7468 have a 10-bit ADC and can therefore
107 measure temperatures with 0.25 degC resolution. They also provide an offset
108 to the temperature readings that is automatically applied during
109 measurement. This offset can be used to zero out any errors due to traces
110 and placement. The documentation says that the offset is in 0.25 degC
111 steps, but in initial testing of the ADM1027 it was 1.00 degC steps. Analog
112 Devices has confirmed this "bug". The ADT7463 is reported to work as
113 described in the documentation. The current lm85 driver does not show the
114 offset register.
115
116 The ADT7468 has a high-frequency PWM mode, where all PWM outputs are
117 driven by a 22.5 kHz clock. This is a global mode, not per-PWM output,
118 which means that setting any PWM frequency above 11.3 kHz will switch
119 all 3 PWM outputs to a 22.5 kHz frequency. Conversely, setting any PWM
120 frequency below 11.3 kHz will switch all 3 PWM outputs to a frequency
121 between 10 and 100 Hz, which can then be tuned separately.
122
123 See the vendor datasheets for more information. There is application note
124 from National (AN-1260) with some additional information about the LM85.
125 The Analog Devices datasheet is very detailed and describes a procedure for
126 determining an optimal configuration for the automatic PWM control.
127
128 The SMSC EMC6D100 & EMC6D101 monitor external voltages, temperatures, and
129 fan speeds. They use this monitoring capability to alert the system to out
130 of limit conditions and can automatically control the speeds of multiple
131 fans in a PC or embedded system. The EMC6D101, available in a 24-pin SSOP
132 package, and the EMC6D100, available in a 28-pin SSOP package, are designed
133 to be register compatible. The EMC6D100 offers all the features of the
134 EMC6D101 plus additional voltage monitoring and system control features.
135 Unfortunately it is not possible to distinguish between the package
136 versions on register level so these additional voltage inputs may read
137 zero. EMC6D102 and EMC6D103 feature additional ADC bits thus extending precision
138 of voltage and temperature channels.
139
140 SMSC EMC6D103S is similar to EMC6D103, but does not support pwm#_auto_pwm_minctl
141 and temp#_auto_temp_off.
142
143 The LM96000 supports additional high frequency PWM modes (22.5 kHz, 24 kHz,
144 25.7 kHz, 27.7 kHz and 30 kHz), which can be configured on a per-PWM basis.
145
146 Hardware Configurations
147 -----------------------
148
149 The LM85 can be jumpered for 3 different SMBus addresses. There are
150 no other hardware configuration options for the LM85.
151
152 The lm85 driver detects both LM85B and LM85C revisions of the chip. See the
153 datasheet for a complete description of the differences. Other than
154 identifying the chip, the driver behaves no differently with regard to
155 these two chips. The LM85B is recommended for new designs.
156
157 The ADM1027, ADT7463 and ADT7468 chips have an optional SMBALERT output
158 that can be used to signal the chipset in case a limit is exceeded or the
159 temperature sensors fail. Individual sensor interrupts can be masked so
160 they won't trigger SMBALERT. The SMBALERT output if configured replaces one
161 of the other functions (PWM2 or IN0). This functionality is not implemented
162 in current driver.
163
164 The ADT7463 and ADT7468 also have an optional THERM output/input which can
165 be connected to the processor PROC_HOT output. If available, the autofan
166 control dynamic Tmin feature can be enabled to keep the system temperature
167 within spec (just?!) with the least possible fan noise.
168
169 Configuration Notes
170 -------------------
171
172 Besides standard interfaces driver adds following:
173
174 * Temperatures and Zones
175
176 Each temperature sensor is associated with a Zone. There are three
177 sensors and therefore three zones (# 1, 2 and 3). Each zone has the following
178 temperature configuration points:
179
180 * temp#_auto_temp_off - temperature below which fans should be off or spinning very low.
181 * temp#_auto_temp_min - temperature over which fans start to spin.
182 * temp#_auto_temp_max - temperature when fans spin at full speed.
183 * temp#_auto_temp_crit - temperature when all fans will run full speed.
184
185 * PWM Control
186
187 There are three PWM outputs. The LM85 datasheet suggests that the
188 pwm3 output control both fan3 and fan4. Each PWM can be individually
189 configured and assigned to a zone for its control value. Each PWM can be
190 configured individually according to the following options.
191
192 * pwm#_auto_pwm_min - this specifies the PWM value for temp#_auto_temp_off
193                       temperature. (PWM value from 0 to 255)
194
195 * pwm#_auto_pwm_minctl - this flags selects for temp#_auto_temp_off temperature
196                          the behaviour of fans. Write 1 to let fans spinning at
197                          pwm#_auto_pwm_min or write 0 to let them off.
198
199 NOTE: It has been reported that there is a bug in the LM85 that causes the flag
200 to be associated with the zones not the PWMs. This contradicts all the
201 published documentation. Setting pwm#_min_ctl in this case actually affects all
202 PWMs controlled by zone '#'.
203
204 * PWM Controlling Zone selection
205
206 * pwm#_auto_channels - controls zone that is associated with PWM
207
208 Configuration choices:
209
210    Value     Meaning
211   ------  ------------------------------------------------
212       1    Controlled by Zone 1
213       2    Controlled by Zone 2
214       3    Controlled by Zone 3
215      23    Controlled by higher temp of Zone 2 or 3
216     123    Controlled by highest temp of Zone 1, 2 or 3
217       0    PWM always 0%  (off)
218      -1    PWM always 100%  (full on)
219      -2    Manual control (write to 'pwm#' to set)
220
221 The National LM85's have two vendor specific configuration
222 features. Tach. mode and Spinup Control. For more details on these,
223 see the LM85 datasheet or Application Note AN-1260. These features
224 are not currently supported by the lm85 driver.
225
226 The Analog Devices ADM1027 has several vendor specific enhancements.
227 The number of pulses-per-rev of the fans can be set, Tach monitoring
228 can be optimized for PWM operation, and an offset can be applied to
229 the temperatures to compensate for systemic errors in the
230 measurements. These features are not currently supported by the lm85
231 driver.
232
233 In addition to the ADM1027 features, the ADT7463 and ADT7468 also have
234 Tmin control and THERM asserted counts. Automatic Tmin control acts to
235 adjust the Tmin value to maintain the measured temperature sensor at a
236 specified temperature. There isn't much documentation on this feature in
237 the ADT7463 data sheet. This is not supported by current driver.