Commit | Line | Data |
---|---|---|
4a1288f1 GM |
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. | |
b1986c8e AW |
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 | |
4a1288f1 GM |
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 | ||
41cd4373 AW |
49 | Due to the nature of the SMM interface, each pwmX attribute controls |
50 | fan number X. | |
51 | ||
4a1288f1 GM |
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 | ||
e0d3f7cb AW |
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 | ||
4a1288f1 GM |
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. | |
ec3db1ec AW |
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 is triggered by writing to the special ioports ``0xb2`` and ``0x84``, | |
190 | and may cause short hangs when the BIOS code is taking too long to | |
191 | execute. | |
192 | ||
193 | The SMM handler inside the system BIOS looks at the contents of the | |
194 | ``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers. | |
195 | Each register has a special purpose: | |
196 | ||
197 | =============== ================================== | |
198 | Register Purpose | |
199 | =============== ================================== | |
200 | eax Holds the command code before SMM, | |
201 | holds the first result after SMM. | |
202 | ebx Holds the arguments. | |
203 | ecx Unknown, set to 0. | |
204 | edx Holds the second result after SMM. | |
205 | esi Unknown, set to 0. | |
206 | edi Unknown, set to 0. | |
207 | =============== ================================== | |
208 | ||
209 | The SMM handler can signal a failure by either: | |
210 | ||
211 | - setting the lower sixteen bits of ``eax`` to ``0xffff`` | |
212 | - not modifying ``eax`` at all | |
213 | - setting the carry flag | |
214 | ||
215 | SMM command codes | |
216 | ----------------- | |
217 | ||
218 | =============== ======================= ================================================ | |
219 | Command Code Command Name Description | |
220 | =============== ======================= ================================================ | |
221 | ``0x0025`` Get Fn key status Returns the Fn key pressed after SMM: | |
222 | ||
223 | - 9th bit in ``eax`` indicates Volume up | |
224 | - 10th bit in ``eax`` indicates Volume down | |
225 | - both bits indicate Volume mute | |
226 | ||
227 | ``0xa069`` Get power status Returns current power status after SMM: | |
228 | ||
229 | - 1st bit in ``eax`` indicates Battery connected | |
230 | - 3th bit in ``eax`` indicates AC connected | |
231 | ||
232 | ``0x00a3`` Get fan state Returns current fan state after SMM: | |
233 | ||
234 | - 1st byte in ``eax`` holds the current | |
235 | fan state (0 - 2 or 3) | |
236 | ||
237 | ``0x01a3`` Set fan state Sets the fan speed: | |
238 | ||
239 | - 1st byte in ``ebx`` holds the fan number | |
240 | - 2nd byte in ``ebx`` holds the desired | |
241 | fan state (0 - 2 or 3) | |
242 | ||
243 | ``0x02a3`` Get fan speed Returns the current fan speed in RPM: | |
244 | ||
245 | - 1st byte in ``ebx`` holds the fan number | |
246 | - 1st word in ``eax`` holds the current | |
247 | fan speed in RPM (after SMM) | |
248 | ||
249 | ``0x03a3`` Get fan type Returns the fan type: | |
250 | ||
251 | - 1st byte in ``ebx`` holds the fan number | |
252 | - 1st byte in ``eax`` holds the | |
253 | fan type (after SMM): | |
254 | ||
255 | - 5th bit indicates docking fan | |
256 | - 1 indicates Processor fan | |
257 | - 2 indicates Motherboard fan | |
258 | - 3 indicates Video fan | |
259 | - 4 indicates Power supply fan | |
260 | - 5 indicates Chipset fan | |
261 | - 6 indicates other fan type | |
262 | ||
263 | ``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state: | |
264 | ||
265 | - 1st byte in ``ebx`` holds the fan number | |
266 | - 2nd byte in ``ebx`` holds the fan state | |
267 | in question (0 - 2 or 3) | |
268 | - 1st word in ``eax`` holds the nominal | |
269 | fan speed in RPM (after SMM) | |
270 | ||
271 | ``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state: | |
272 | ||
273 | - 1st byte in ``ebx`` holds the fan number | |
274 | - 2nd byte in ``ebx`` holds the fan state | |
275 | in question (0 - 2 or 3) | |
276 | - 1st byte in ``eax`` returns the speed | |
277 | tolerance | |
278 | ||
279 | ``0x10a3`` Get sensor temperature Returns the measured temperature: | |
280 | ||
281 | - 1st byte in ``ebx`` holds the sensor number | |
282 | - 1st byte in ``eax`` holds the measured | |
283 | temperature (after SMM) | |
284 | ||
285 | ``0x11a3`` Get sensor type Returns the sensor type: | |
286 | ||
287 | - 1st byte in ``ebx`` holds the sensor number | |
288 | - 1st byte in ``eax`` holds the | |
289 | temperature type (after SMM): | |
290 | ||
291 | - 1 indicates CPU sensor | |
292 | - 2 indicates GPU sensor | |
293 | - 3 indicates SODIMM sensor | |
294 | - 4 indicates other sensor type | |
295 | - 5 indicates Ambient sensor | |
296 | - 6 indicates other sensor type | |
297 | ||
298 | ``0xfea3`` Get SMM signature Returns Dell signature if interface | |
299 | is supported (after SMM): | |
300 | ||
301 | - ``eax`` holds 1145651527 | |
302 | (0x44494147 or "DIAG") | |
303 | - ``edx`` holds 1145392204 | |
304 | (0x44454c4c or "DELL") | |
305 | ||
306 | ``0xffa3`` Get SMM signature Same as ``0xfea3``, check both. | |
307 | =============== ======================= ================================================ | |
308 | ||
309 | There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and | |
310 | disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control. | |
311 | The commands are however causing severe sideeffects on many machines, so | |
312 | they are not used by default. | |
313 | ||
314 | On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the | |
315 | fans supports a 4th "magic" state, which signals the BIOS that automatic | |
316 | fan control should be enabled for a specific fan. | |
317 | However there are also some machines who do support a 4th regular fan state too, | |
318 | but in case of the "magic" state, the nominal RPM reported for this state is a | |
319 | placeholder value, which however is not always detectable. | |
320 | ||
321 | Firmware Bugs | |
322 | ------------- | |
323 | ||
324 | The SMM calls can behave erratic on some machines: | |
325 | ||
326 | ======================================================= ================= | |
327 | Firmware Bug Affected Machines | |
328 | ======================================================= ================= | |
329 | Reading of fan states return spurious errors. Precision 490 | |
330 | ||
331 | Reading of fan types causes erratic fan behaviour. Studio XPS 8000 | |
332 | ||
333 | Studio XPS 8100 | |
334 | ||
335 | Inspiron 580 | |
336 | ||
c8e5e37a AW |
337 | Inspiron 3505 |
338 | ||
ec3db1ec AW |
339 | Fan-related SMM calls take too long (about 500ms). Inspiron 7720 |
340 | ||
341 | Vostro 3360 | |
342 | ||
343 | XPS 13 9333 | |
344 | ||
345 | XPS 15 L502X | |
346 | ======================================================= ================= | |
347 | ||
348 | In case you experience similar issues on your Dell machine, please | |
349 | submit a bugreport on bugzilla to we can apply workarounds. | |
350 | ||
351 | Limitations | |
352 | ----------- | |
353 | ||
354 | The SMM calls can take too long to execute on some machines, causing | |
355 | short hangs and/or audio glitches. | |
356 | Also the fan state needs to be restored after suspend, as well as | |
357 | the automatic mode settings. | |
358 | When reading a temperature sensor, values above 127 degrees indicate | |
359 | a BIOS read error or a deactivated sensor. |