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