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