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