hwmon: Add Freescale MC13783 ADC driver
[linux-2.6.git] / Documentation / hwmon / dme1737
1 Kernel driver dme1737
2 =====================
3
4 Supported chips:
5   * SMSC DME1737 and compatibles (like Asus A8000)
6     Prefix: 'dme1737'
7     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
8     Datasheet: Provided by SMSC upon request and under NDA
9   * SMSC SCH3112, SCH3114, SCH3116
10     Prefix: 'sch311x'
11     Addresses scanned: none, address read from Super-I/O config space
12     Datasheet: http://www.nuhorizons.com/FeaturedProducts/Volume1/SMSC/311x.pdf
13   * SMSC SCH5027
14     Prefix: 'sch5027'
15     Addresses scanned: I2C 0x2c, 0x2d, 0x2e
16     Datasheet: Provided by SMSC upon request and under NDA
17
18 Authors:
19     Juerg Haefliger <juergh@gmail.com>
20
21
22 Module Parameters
23 -----------------
24
25 * force_start: bool     Enables the monitoring of voltage, fan and temp inputs
26                         and PWM output control functions. Using this parameter
27                         shouldn't be required since the BIOS usually takes care
28                         of this.
29 * probe_all_addr: bool  Include non-standard LPC addresses 0x162e and 0x164e
30                         when probing for ISA devices. This is required for the
31                         following boards:
32                         - VIA EPIA SN18000
33
34
35 Description
36 -----------
37
38 This driver implements support for the hardware monitoring capabilities of the
39 SMSC DME1737 and Asus A8000 (which are the same), SMSC SCH5027, and SMSC
40 SCH311x Super-I/O chips. These chips feature monitoring of 3 temp sensors
41 temp[1-3] (2 remote diodes and 1 internal), 7 voltages in[0-6] (6 external and
42 1 internal) and up to 6 fan speeds fan[1-6]. Additionally, the chips implement
43 up to 5 PWM outputs pwm[1-3,5-6] for controlling fan speeds both manually and
44 automatically.
45
46 For the DME1737, A8000 and SCH5027, fan[1-2] and pwm[1-2] are always present.
47 Fan[3-6] and pwm[3,5-6] are optional features and their availability depends on
48 the configuration of the chip. The driver will detect which features are
49 present during initialization and create the sysfs attributes accordingly.
50
51 For the SCH311x, fan[1-3] and pwm[1-3] are always present and fan[4-6] and
52 pwm[5-6] don't exist.
53
54 The hardware monitoring features of the DME1737, A8000, and SCH5027 are only
55 accessible via SMBus, while the SCH311x only provides access via the ISA bus.
56 The driver will therefore register itself as an I2C client driver if it detects
57 a DME1737, A8000, or SCH5027 and as a platform driver if it detects a SCH311x
58 chip.
59
60
61 Voltage Monitoring
62 ------------------
63
64 The voltage inputs are sampled with 12-bit resolution and have internal
65 scaling resistors. The values returned by the driver therefore reflect true
66 millivolts and don't need scaling. The voltage inputs are mapped as follows
67 (the last column indicates the input ranges):
68
69 DME1737, A8000:
70         in0: +5VTR      (+5V standby)           0V - 6.64V
71         in1: Vccp       (processor core)        0V - 3V
72         in2: VCC        (internal +3.3V)        0V - 4.38V
73         in3: +5V                                0V - 6.64V
74         in4: +12V                               0V - 16V
75         in5: VTR        (+3.3V standby)         0V - 4.38V
76         in6: Vbat       (+3.0V)                 0V - 4.38V
77
78 SCH311x:
79         in0: +2.5V                              0V - 6.64V
80         in1: Vccp       (processor core)        0V - 2V
81         in2: VCC        (internal +3.3V)        0V - 4.38V
82         in3: +5V                                0V - 6.64V
83         in4: +12V                               0V - 16V
84         in5: VTR        (+3.3V standby)         0V - 4.38V
85         in6: Vbat       (+3.0V)                 0V - 4.38V
86
87 SCH5027:
88         in0: +5VTR      (+5V standby)           0V - 6.64V
89         in1: Vccp       (processor core)        0V - 3V
90         in2: VCC        (internal +3.3V)        0V - 4.38V
91         in3: V2_IN                              0V - 1.5V
92         in4: V1_IN                              0V - 1.5V
93         in5: VTR        (+3.3V standby)         0V - 4.38V
94         in6: Vbat       (+3.0V)                 0V - 4.38V
95
96 Each voltage input has associated min and max limits which trigger an alarm
97 when crossed.
98
99
100 Temperature Monitoring
101 ----------------------
102
103 Temperatures are measured with 12-bit resolution and reported in millidegree
104 Celsius. The chip also features offsets for all 3 temperature inputs which -
105 when programmed - get added to the input readings. The chip does all the
106 scaling by itself and the driver therefore reports true temperatures that don't
107 need any user-space adjustments. The temperature inputs are mapped as follows
108 (the last column indicates the input ranges):
109
110         temp1: Remote diode 1 (3904 type) temperature   -127C - +127C
111         temp2: DME1737 internal temperature             -127C - +127C
112         temp3: Remote diode 2 (3904 type) temperature   -127C - +127C
113
114 Each temperature input has associated min and max limits which trigger an alarm
115 when crossed. Additionally, each temperature input has a fault attribute that
116 returns 1 when a faulty diode or an unconnected input is detected and 0
117 otherwise.
118
119
120 Fan Monitoring
121 --------------
122
123 Fan RPMs are measured with 16-bit resolution. The chip provides inputs for 6
124 fan tachometers. All 6 inputs have an associated min limit which triggers an
125 alarm when crossed. Fan inputs 1-4 provide type attributes that need to be set
126 to the number of pulses per fan revolution that the connected tachometer
127 generates. Supported values are 1, 2, and 4. Fan inputs 5-6 only support fans
128 that generate 2 pulses per revolution. Fan inputs 5-6 also provide a max
129 attribute that needs to be set to the maximum attainable RPM (fan at 100% duty-
130 cycle) of the input. The chip adjusts the sampling rate based on this value.
131
132
133 PWM Output Control
134 ------------------
135
136 This chip features 5 PWM outputs. PWM outputs 1-3 are associated with fan
137 inputs 1-3 and PWM outputs 5-6 are associated with fan inputs 5-6. PWM outputs
138 1-3 can be configured to operate either in manual or automatic mode by setting
139 the appropriate enable attribute accordingly. PWM outputs 5-6 can only operate
140 in manual mode, their enable attributes are therefore read-only. When set to
141 manual mode, the fan speed is set by writing the duty-cycle value to the
142 appropriate PWM attribute. In automatic mode, the PWM attribute returns the
143 current duty-cycle as set by the fan controller in the chip. All PWM outputs
144 support the setting of the output frequency via the freq attribute.
145
146 In automatic mode, the chip supports the setting of the PWM ramp rate which
147 defines how fast the PWM output is adjusting to changes of the associated
148 temperature input. Associating PWM outputs to temperature inputs is done via
149 temperature zones. The chip features 3 zones whose assignments to temperature
150 inputs is static and determined during initialization. These assignments can
151 be retrieved via the zone[1-3]_auto_channels_temp attributes. Each PWM output
152 is assigned to one (or hottest of multiple) temperature zone(s) through the
153 pwm[1-3]_auto_channels_zone attributes. Each PWM output has 3 distinct output
154 duty-cycles: full, low, and min. Full is internally hard-wired to 255 (100%)
155 and low and min can be programmed via pwm[1-3]_auto_point1_pwm and
156 pwm[1-3]_auto_pwm_min, respectively. The thermal thresholds of the zones are
157 programmed via zone[1-3]_auto_point[1-3]_temp and
158 zone[1-3]_auto_point1_temp_hyst:
159
160         pwm[1-3]_auto_point2_pwm        full-speed duty-cycle (255, i.e., 100%)
161         pwm[1-3]_auto_point1_pwm        low-speed duty-cycle
162         pwm[1-3]_auto_pwm_min           min-speed duty-cycle
163
164         zone[1-3]_auto_point3_temp      full-speed temp (all outputs)
165         zone[1-3]_auto_point2_temp      full-speed temp
166         zone[1-3]_auto_point1_temp      low-speed temp
167         zone[1-3]_auto_point1_temp_hyst min-speed temp
168
169 The chip adjusts the output duty-cycle linearly in the range of auto_point1_pwm
170 to auto_point2_pwm if the temperature of the associated zone is between
171 auto_point1_temp and auto_point2_temp. If the temperature drops below the
172 auto_point1_temp_hyst value, the output duty-cycle is set to the auto_pwm_min
173 value which only supports two values: 0 or auto_point1_pwm. That means that the
174 fan either turns completely off or keeps spinning with the low-speed
175 duty-cycle. If any of the temperatures rise above the auto_point3_temp value,
176 all PWM outputs are set to 100% duty-cycle.
177
178 Following is another representation of how the chip sets the output duty-cycle
179 based on the temperature of the associated thermal zone:
180
181                         Duty-Cycle      Duty-Cycle
182         Temperature     Rising Temp     Falling Temp
183         -----------     -----------     ------------
184         full-speed      full-speed      full-speed
185
186                         < linearly adjusted duty-cycle >
187
188         low-speed       low-speed       low-speed
189                         min-speed       low-speed
190         min-speed       min-speed       min-speed
191                         min-speed       min-speed
192
193
194 Sysfs Attributes
195 ----------------
196
197 Following is a list of all sysfs attributes that the driver provides, their
198 permissions and a short description:
199
200 Name                            Perm    Description
201 ----                            ----    -----------
202 cpu0_vid                        RO      CPU core reference voltage in
203                                         millivolts.
204 vrm                             RW      Voltage regulator module version
205                                         number.
206
207 in[0-6]_input                   RO      Measured voltage in millivolts.
208 in[0-6]_min                     RW      Low limit for voltage input.
209 in[0-6]_max                     RW      High limit for voltage input.
210 in[0-6]_alarm                   RO      Voltage input alarm. Returns 1 if
211                                         voltage input is or went outside the
212                                         associated min-max range, 0 otherwise.
213
214 temp[1-3]_input                 RO      Measured temperature in millidegree
215                                         Celsius.
216 temp[1-3]_min                   RW      Low limit for temp input.
217 temp[1-3]_max                   RW      High limit for temp input.
218 temp[1-3]_offset                RW      Offset for temp input. This value will
219                                         be added by the chip to the measured
220                                         temperature.
221 temp[1-3]_alarm                 RO      Alarm for temp input. Returns 1 if temp
222                                         input is or went outside the associated
223                                         min-max range, 0 otherwise.
224 temp[1-3]_fault                 RO      Temp input fault. Returns 1 if the chip
225                                         detects a faulty thermal diode or an
226                                         unconnected temp input, 0 otherwise.
227
228 zone[1-3]_auto_channels_temp    RO      Temperature zone to temperature input
229                                         mapping. This attribute is a bitfield
230                                         and supports the following values:
231                                                 1: temp1
232                                                 2: temp2
233                                                 4: temp3
234 zone[1-3]_auto_point1_temp_hyst RW      Auto PWM temp point1 hysteresis. The
235                                         output of the corresponding PWM is set
236                                         to the pwm_auto_min value if the temp
237                                         falls below the auto_point1_temp_hyst
238                                         value.
239 zone[1-3]_auto_point[1-3]_temp  RW      Auto PWM temp points. Auto_point1 is
240                                         the low-speed temp, auto_point2 is the
241                                         full-speed temp, and auto_point3 is the
242                                         temp at which all PWM outputs are set
243                                         to full-speed (100% duty-cycle).
244
245 fan[1-6]_input                  RO      Measured fan speed in RPM.
246 fan[1-6]_min                    RW      Low limit for fan input.
247 fan[1-6]_alarm                  RO      Alarm for fan input. Returns 1 if fan
248                                         input is or went below the associated
249                                         min value, 0 otherwise.
250 fan[1-4]_type                   RW      Type of attached fan. Expressed in
251                                         number of pulses per revolution that
252                                         the fan generates. Supported values are
253                                         1, 2, and 4.
254 fan[5-6]_max                    RW      Max attainable RPM at 100% duty-cycle.
255                                         Required for chip to adjust the
256                                         sampling rate accordingly.
257
258 pmw[1-3,5-6]                    RO/RW   Duty-cycle of PWM output. Supported
259                                         values are 0-255 (0%-100%). Only
260                                         writeable if the associated PWM is in
261                                         manual mode.
262 pwm[1-3]_enable                 RW      Enable of PWM outputs 1-3. Supported
263                                         values are:
264                                                  0: turned off (output @ 100%)
265                                                  1: manual mode
266                                                  2: automatic mode
267 pwm[5-6]_enable                 RO      Enable of PWM outputs 5-6. Always
268                                         returns 1 since these 2 outputs are
269                                         hard-wired to manual mode.
270 pmw[1-3,5-6]_freq               RW      Frequency of PWM output. Supported
271                                         values are in the range 11Hz-30000Hz
272                                         (default is 25000Hz).
273 pmw[1-3]_ramp_rate              RW      Ramp rate of PWM output. Determines how
274                                         fast the PWM duty-cycle will change
275                                         when the PWM is in automatic mode.
276                                         Expressed in ms per PWM step. Supported
277                                         values are in the range 0ms-206ms
278                                         (default is 0, which means the duty-
279                                         cycle changes instantly).
280 pwm[1-3]_auto_channels_zone     RW      PWM output to temperature zone mapping.
281                                         This attribute is a bitfield and
282                                         supports the following values:
283                                                 1: zone1
284                                                 2: zone2
285                                                 4: zone3
286                                                 6: highest of zone[2-3]
287                                                 7: highest of zone[1-3]
288 pwm[1-3]_auto_pwm_min           RW      Auto PWM min pwm. Minimum PWM duty-
289                                         cycle. Supported values are 0 or
290                                         auto_point1_pwm.
291 pwm[1-3]_auto_point1_pwm        RW      Auto PWM pwm point. Auto_point1 is the
292                                         low-speed duty-cycle.
293 pwm[1-3]_auto_point2_pwm        RO      Auto PWM pwm point. Auto_point2 is the
294                                         full-speed duty-cycle which is hard-
295                                         wired to 255 (100% duty-cycle).