1 .. SPDX-License-Identifier: GPL-2.0-or-later 1 .. SPDX-License-Identifier: GPL-2.0-or-later
2 2
3 .. include:: <isonum.txt> 3 .. include:: <isonum.txt>
4 4
5 Kernel driver dell-smm-hwmon 5 Kernel driver dell-smm-hwmon
6 ============================ 6 ============================
7 7
8 :Copyright: |copy| 2002-2005 Massimo Dal Zotto< 8 :Copyright: |copy| 2002-2005 Massimo Dal Zotto <dz@debian.org>
9 :Copyright: |copy| 2019 Giovanni Mascellani <gi 9 :Copyright: |copy| 2019 Giovanni Mascellani <gio@debian.org>
10 10
11 Description 11 Description
12 ----------- 12 -----------
13 13
14 On many Dell laptops the System Management Mod 14 On many Dell laptops the System Management Mode (SMM) BIOS can be
15 queried for the status of fans and temperature 15 queried for the status of fans and temperature sensors. Userspace
16 utilities like ``sensors`` can be used to retu 16 utilities like ``sensors`` can be used to return the readings. The
17 userspace suite `i8kutils`__ can also be used 17 userspace suite `i8kutils`__ can also be used to read the sensors and
18 automatically adjust fan speed (please notice 18 automatically adjust fan speed (please notice that it currently uses
19 the deprecated ``/proc/i8k`` interface). 19 the deprecated ``/proc/i8k`` interface).
20 20
21 __ https://github.com/vitorafsr/i8kutils 21 __ https://github.com/vitorafsr/i8kutils
22 22
23 ``sysfs`` interface 23 ``sysfs`` interface
24 ------------------- 24 -------------------
25 25
26 Temperature sensors and fans can be queried an 26 Temperature sensors and fans can be queried and set via the standard
27 ``hwmon`` interface on ``sysfs``, under the di 27 ``hwmon`` interface on ``sysfs``, under the directory
28 ``/sys/class/hwmon/hwmonX`` for some value of 28 ``/sys/class/hwmon/hwmonX`` for some value of ``X`` (search for the
29 ``X`` such that ``/sys/class/hwmon/hwmonX/name 29 ``X`` such that ``/sys/class/hwmon/hwmonX/name`` has content
30 ``dell_smm``). A number of other attributes ca 30 ``dell_smm``). A number of other attributes can be read or written:
31 31
32 =============================== ======= ====== 32 =============================== ======= =======================================
33 Name Perm Descri 33 Name Perm Description
34 =============================== ======= ====== 34 =============================== ======= =======================================
35 fan[1-3]_input RO Fan sp 35 fan[1-3]_input RO Fan speed in RPM.
36 fan[1-3]_label RO Fan la 36 fan[1-3]_label RO Fan label.
37 fan[1-3]_min RO Minima <<
38 fan[1-3]_max RO Maxima <<
39 fan[1-3]_target RO Expect <<
40 pwm[1-3] RW Contro 37 pwm[1-3] RW Control the fan PWM duty-cycle.
41 pwm1_enable WO Enable 38 pwm1_enable WO Enable or disable automatic BIOS fan
42 contro 39 control (not supported on all laptops,
43 see be 40 see below for details).
44 temp[1-10]_input RO Temper 41 temp[1-10]_input RO Temperature reading in milli-degrees
45 Celsiu 42 Celsius.
46 temp[1-10]_label RO Temper 43 temp[1-10]_label RO Temperature sensor label.
47 =============================== ======= ====== 44 =============================== ======= =======================================
48 45
49 Due to the nature of the SMM interface, each p <<
50 fan number X. <<
51 <<
52 Disabling automatic BIOS fan control 46 Disabling automatic BIOS fan control
53 ------------------------------------ 47 ------------------------------------
54 48
55 On some laptops the BIOS automatically sets fa 49 On some laptops the BIOS automatically sets fan speed every few
56 seconds. Therefore the fan speed set by mean o 50 seconds. Therefore the fan speed set by mean of this driver is quickly
57 overwritten. 51 overwritten.
58 52
59 There is experimental support for disabling au 53 There is experimental support for disabling automatic BIOS fan
60 control, at least on laptops where the corresp 54 control, at least on laptops where the corresponding SMM command is
61 known, by writing the value ``1`` in the attri 55 known, by writing the value ``1`` in the attribute ``pwm1_enable``
62 (writing ``2`` enables automatic BIOS control 56 (writing ``2`` enables automatic BIOS control again). Even if you have
63 more than one fan, all of them are set to eith 57 more than one fan, all of them are set to either enabled or disabled
64 automatic fan control at the same time and, no 58 automatic fan control at the same time and, notwithstanding the name,
65 ``pwm1_enable`` sets automatic control for all 59 ``pwm1_enable`` sets automatic control for all fans.
66 60
67 If ``pwm1_enable`` is not available, then it m 61 If ``pwm1_enable`` is not available, then it means that SMM codes for
68 enabling and disabling automatic BIOS fan cont 62 enabling and disabling automatic BIOS fan control are not whitelisted
69 for your hardware. It is possible that codes t 63 for your hardware. It is possible that codes that work for other
70 laptops actually work for yours as well, or th 64 laptops actually work for yours as well, or that you have to discover
71 new codes. 65 new codes.
72 66
73 Check the list ``i8k_whitelist_fan_control`` i 67 Check the list ``i8k_whitelist_fan_control`` in file
74 ``drivers/hwmon/dell-smm-hwmon.c`` in the kern 68 ``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first
75 attempt you can try to add your machine and us 69 attempt you can try to add your machine and use an already-known code
76 pair. If, after recompiling the kernel, you se 70 pair. If, after recompiling the kernel, you see that ``pwm1_enable``
77 is present and works (i.e., you can manually c 71 is present and works (i.e., you can manually control the fan speed),
78 then please submit your finding as a kernel pa 72 then please submit your finding as a kernel patch, so that other users
79 can benefit from it. Please see 73 can benefit from it. Please see
80 :ref:`Documentation/process/submitting-patches 74 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
81 for information on submitting patches. 75 for information on submitting patches.
82 76
83 If no known code works on your machine, you ne 77 If no known code works on your machine, you need to resort to do some
84 probing, because unfortunately Dell does not p 78 probing, because unfortunately Dell does not publish datasheets for
85 its SMM. You can experiment with the code in ` 79 its SMM. You can experiment with the code in `this repository`__ to
86 probe the BIOS on your machine and discover th 80 probe the BIOS on your machine and discover the appropriate codes.
87 81
88 __ https://github.com/clopez/dellfan/ 82 __ https://github.com/clopez/dellfan/
89 83
90 Again, when you find new codes, we'd be happy 84 Again, when you find new codes, we'd be happy to have your patches!
91 85
92 ``thermal`` interface <<
93 --------------------------- <<
94 <<
95 The driver also exports the fans as thermal co <<
96 ``type`` set to ``dell-smm-fan[1-3]``. This al <<
97 using one of the thermal governors. <<
98 <<
99 Module parameters 86 Module parameters
100 ----------------- 87 -----------------
101 88
102 * force:bool 89 * force:bool
103 Force loading without check 90 Force loading without checking for supported
104 models. (default: 0) 91 models. (default: 0)
105 92
106 * ignore_dmi:bool 93 * ignore_dmi:bool
107 Continue probing hardware e 94 Continue probing hardware even if DMI data does not
108 match. (default: 0) 95 match. (default: 0)
109 96
110 * restricted:bool 97 * restricted:bool
111 Allow fan control only to p 98 Allow fan control only to processes with the
112 ``CAP_SYS_ADMIN`` capabilit 99 ``CAP_SYS_ADMIN`` capability set or processes run
113 as root when using the lega 100 as root when using the legacy ``/proc/i8k``
114 interface. In this case nor 101 interface. In this case normal users will be able
115 to read temperature and fan 102 to read temperature and fan status but not to
116 control the fan. If your n 103 control the fan. If your notebook is shared with
117 other users and you don't t 104 other users and you don't trust them you may want
118 to use this option. (defaul 105 to use this option. (default: 1, only available
119 with ``CONFIG_I8K``) 106 with ``CONFIG_I8K``)
120 107
121 * power_status:bool 108 * power_status:bool
122 Report AC status in ``/proc 109 Report AC status in ``/proc/i8k``. (default: 0,
123 only available with ``CONFI 110 only available with ``CONFIG_I8K``)
124 111
125 * fan_mult:uint 112 * fan_mult:uint
126 Factor to multiply fan spee 113 Factor to multiply fan speed with. (default:
127 autodetect) 114 autodetect)
128 115
129 * fan_max:uint 116 * fan_max:uint
130 Maximum configurable fan sp 117 Maximum configurable fan speed. (default:
131 autodetect) 118 autodetect)
132 119
133 Legacy ``/proc`` interface 120 Legacy ``/proc`` interface
134 -------------------------- 121 --------------------------
135 122
136 .. warning:: This interface is obsolete and de 123 .. warning:: This interface is obsolete and deprecated and should not
137 used in new applications. This in 124 used in new applications. This interface is only
138 available when kernel is compiled 125 available when kernel is compiled with option
139 ``CONFIG_I8K``. 126 ``CONFIG_I8K``.
140 127
141 The information provided by the kernel driver 128 The information provided by the kernel driver can be accessed by
142 simply reading the ``/proc/i8k`` file. For exa 129 simply reading the ``/proc/i8k`` file. For example::
143 130
144 $ cat /proc/i8k 131 $ cat /proc/i8k
145 1.0 A17 2J59L02 52 2 1 8040 6420 1 2 132 1.0 A17 2J59L02 52 2 1 8040 6420 1 2
146 133
147 The fields read from ``/proc/i8k`` are:: 134 The fields read from ``/proc/i8k`` are::
148 135
149 1.0 A17 2J59L02 52 2 1 8040 6420 1 2 136 1.0 A17 2J59L02 52 2 1 8040 6420 1 2
150 | | | | | | | | | | 137 | | | | | | | | | |
151 | | | | | | | | | +------ 138 | | | | | | | | | +------- 10. buttons status
152 | | | | | | | | +-------- 139 | | | | | | | | +--------- 9. AC status
153 | | | | | | | +------------- 140 | | | | | | | +-------------- 8. fan0 RPM
154 | | | | | | +------------------ 141 | | | | | | +------------------- 7. fan1 RPM
155 | | | | | +-------------------- 142 | | | | | +--------------------- 6. fan0 status
156 | | | | +---------------------- 143 | | | | +----------------------- 5. fan1 status
157 | | | +------------------------- 144 | | | +-------------------------- 4. temp0 reading (Celsius)
158 | | +--------------------------------- 145 | | +---------------------------------- 3. Dell service tag (later known as 'serial number')
159 | +------------------------------------- 146 | +-------------------------------------- 2. BIOS version
160 +----------------------------------------- 147 +------------------------------------------ 1. /proc/i8k format version
161 148
162 A negative value, for example -22, indicates t 149 A negative value, for example -22, indicates that the BIOS doesn't
163 return the corresponding information. This is 150 return the corresponding information. This is normal on some
164 models/BIOSes. 151 models/BIOSes.
165 152
166 For performance reasons the ``/proc/i8k`` does 153 For performance reasons the ``/proc/i8k`` doesn't report by default
167 the AC status since this SMM call takes a long 154 the AC status since this SMM call takes a long time to execute and is
168 not really needed. If you want to see the ac 155 not really needed. If you want to see the ac status in ``/proc/i8k``
169 you must explictitly enable this option by pas 156 you must explictitly enable this option by passing the
170 ``power_status=1`` parameter to insmod. If AC 157 ``power_status=1`` parameter to insmod. If AC status is not
171 available -1 is printed instead. 158 available -1 is printed instead.
172 159
173 The driver provides also an ioctl interface wh 160 The driver provides also an ioctl interface which can be used to
174 obtain the same information and to control the 161 obtain the same information and to control the fan status. The ioctl
175 interface can be accessed from C programs or f 162 interface can be accessed from C programs or from shell using the
176 i8kctl utility. See the source file of ``i8kut 163 i8kctl utility. See the source file of ``i8kutils`` for more
177 information on how to use the ioctl interface. 164 information on how to use the ioctl interface.
178 <<
179 SMM Interface <<
180 ------------- <<
181 <<
182 .. warning:: The SMM interface was reverse-eng <<
183 since Dell did not provide any Do <<
184 please keep that in mind. <<
185 <<
186 The driver uses the SMM interface to send comm <<
187 This interface is normally used by Dell's 32-b <<
188 on newer notebook models by the buildin BIOS d <<
189 The SMM may cause short hangs when the BIOS co <<
190 execute. <<
191 <<
192 The SMM handler inside the system BIOS looks a <<
193 ``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` an <<
194 Each register has a special purpose: <<
195 <<
196 =============== ============================== <<
197 Register Purpose <<
198 =============== ============================== <<
199 eax Holds the command code before <<
200 holds the first result after S <<
201 ebx Holds the arguments. <<
202 ecx Unknown, set to 0. <<
203 edx Holds the second result after <<
204 esi Unknown, set to 0. <<
205 edi Unknown, set to 0. <<
206 =============== ============================== <<
207 <<
208 The SMM handler can signal a failure by either <<
209 <<
210 - setting the lower sixteen bits of ``eax`` to <<
211 - not modifying ``eax`` at all <<
212 - setting the carry flag (legacy SMM interface <<
213 <<
214 Legacy SMM Interface <<
215 -------------------- <<
216 <<
217 When using the legacy SMM interface, a SMM is <<
218 of the command code to the special ioports ``0 <<
219 described inside the ACPI tables and can thus <<
220 <<
221 WMI SMM Interface <<
222 ----------------- <<
223 <<
224 On modern Dell machines, the SMM calls are don <<
225 <<
226 :: <<
227 <<
228 #pragma namespace("\\\\.\\root\\dcim\\sysman\ <<
229 [WMI, Provider("Provider_DiagnosticsServices" <<
230 Description("RunDellDiag"), guid("{F1DDEE52- <<
231 class LegacyDiags { <<
232 [key, read] string InstanceName; <<
233 [read] boolean Active; <<
234 <<
235 [WmiMethodId(1), Implemented, read, write, D <<
236 void Execute([in, out] uint32 EaxLen, [in, o <<
237 [in, out] uint32 EbxLen, [in, o <<
238 [in, out] uint32 EcxLen, [in, o <<
239 [in, out] uint32 EdxLen, [in, o <<
240 }; <<
241 <<
242 Some machines support only the WMI SMM interfa <<
243 The driver automatically detects which interfa <<
244 if the legacy SMM interface is not present. Th <<
245 legacy SMM interface since ACPI methods need t <<
246 <<
247 SMM command codes <<
248 ----------------- <<
249 <<
250 =============== ======================= ====== <<
251 Command Code Command Name Descri <<
252 =============== ======================= ====== <<
253 ``0x0025`` Get Fn key status Return <<
254 <<
255 - 9th <<
256 - 10th <<
257 - both <<
258 <<
259 ``0xa069`` Get power status Return <<
260 <<
261 - 1st <<
262 - 3th <<
263 <<
264 ``0x00a3`` Get fan state Return <<
265 <<
266 - 1st <<
267 fan <<
268 <<
269 ``0x01a3`` Set fan state Sets t <<
270 <<
271 - 1st <<
272 - 2nd <<
273 fan <<
274 <<
275 ``0x02a3`` Get fan speed Return <<
276 <<
277 - 1st <<
278 - 1st <<
279 fan <<
280 <<
281 ``0x03a3`` Get fan type Return <<
282 <<
283 - 1st <<
284 - 1st <<
285 fan <<
286 <<
287 - 5t <<
288 - 1 <<
289 - 2 <<
290 - 3 <<
291 - 4 <<
292 - 5 <<
293 - 6 <<
294 <<
295 ``0x04a3`` Get nominal fan speed Return <<
296 <<
297 - 1st <<
298 - 2nd <<
299 in q <<
300 - 1st <<
301 fan <<
302 <<
303 ``0x05a3`` Get fan speed tolerance Return <<
304 <<
305 - 1st <<
306 - 2nd <<
307 in q <<
308 - 1st <<
309 tole <<
310 <<
311 ``0x10a3`` Get sensor temperature Return <<
312 <<
313 - 1st <<
314 - 1st <<
315 temp <<
316 <<
317 ``0x11a3`` Get sensor type Return <<
318 <<
319 - 1st <<
320 - 1st <<
321 temp <<
322 <<
323 - 1 <<
324 - 2 <<
325 - 3 <<
326 - 4 <<
327 - 5 <<
328 - 6 <<
329 <<
330 ``0xfea3`` Get SMM signature Return <<
331 is sup <<
332 <<
333 - ``ea <<
334 (0x4 <<
335 - ``ed <<
336 (0x4 <<
337 <<
338 ``0xffa3`` Get SMM signature Same a <<
339 =============== ======================= ====== <<
340 <<
341 There are additional commands for enabling (`` <<
342 disabling (``0x30a3`` or ``0x34a3``) automatic <<
343 The commands are however causing severe sideef <<
344 they are not used by default. <<
345 <<
346 On several machines (Inspiron 3505, Precision <<
347 fans supports a 4th "magic" state, which signa <<
348 fan control should be enabled for a specific f <<
349 However there are also some machines who do su <<
350 but in case of the "magic" state, the nominal <<
351 placeholder value, which however is not always <<
352 <<
353 Firmware Bugs <<
354 ------------- <<
355 <<
356 The SMM calls can behave erratic on some machi <<
357 <<
358 ============================================== <<
359 Firmware Bug <<
360 ============================================== <<
361 Reading of fan states return spurious errors. <<
362 <<
363 <<
364 <<
365 Reading of fan types causes erratic fan behavi <<
366 <<
367 <<
368 <<
369 <<
370 <<
371 <<
372 <<
373 Fan-related SMM calls take too long (about 500 <<
374 <<
375 <<
376 <<
377 <<
378 <<
379 <<
380 ============================================== <<
381 <<
382 In case you experience similar issues on your <<
383 submit a bugreport on bugzilla to we can apply <<
384 <<
385 Limitations <<
386 ----------- <<
387 <<
388 The SMM calls can take too long to execute on <<
389 short hangs and/or audio glitches. <<
390 Also the fan state needs to be restored after <<
391 the automatic mode settings. <<
392 When reading a temperature sensor, values abov <<
393 a BIOS read error or a deactivated sensor. <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.