1.. SPDX-License-Identifier: GPL-2.0-or-later
2
3.. include:: <isonum.txt>
4
5Kernel 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
11Description
12-----------
13
14On many Dell laptops the System Management Mode (SMM) BIOS can be
15queried for the status of fans and temperature sensors.  Userspace
16utilities like ``sensors`` can be used to return the readings. The
17userspace suite `i8kutils`__ can also be used to read the sensors and
18automatically adjust fan speed (please notice that it currently uses
19the deprecated ``/proc/i8k`` interface).
20
21 __ https://github.com/vitorafsr/i8kutils
22
23``sysfs`` interface
24-------------------
25
26Temperature 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=============================== ======= =======================================
33Name				Perm	Description
34=============================== ======= =======================================
35fan[1-3]_input                  RO      Fan speed in RPM.
36fan[1-3]_label                  RO      Fan label.
37fan[1-3]_min                    RO      Minimal Fan speed in RPM
38fan[1-3]_max                    RO      Maximal Fan speed in RPM
39fan[1-3]_target                 RO      Expected Fan speed in RPM
40pwm[1-3]                        RW      Control the fan PWM duty-cycle.
41pwm1_enable                     WO      Enable or disable automatic BIOS fan
42                                        control (not supported on all laptops,
43                                        see below for details).
44temp[1-10]_input                RO      Temperature reading in milli-degrees
45                                        Celsius.
46temp[1-10]_label                RO      Temperature sensor label.
47=============================== ======= =======================================
48
49Due to the nature of the SMM interface, each pwmX attribute controls
50fan number X.
51
52Disabling automatic BIOS fan control
53------------------------------------
54
55On some laptops the BIOS automatically sets fan speed every few
56seconds. Therefore the fan speed set by mean of this driver is quickly
57overwritten.
58
59There is experimental support for disabling automatic BIOS fan
60control, at least on laptops where the corresponding SMM command is
61known, by writing the value ``1`` in the attribute ``pwm1_enable``
62(writing ``2`` enables automatic BIOS control again). Even if you have
63more than one fan, all of them are set to either enabled or disabled
64automatic fan control at the same time and, notwithstanding the name,
65``pwm1_enable`` sets automatic control for all fans.
66
67If ``pwm1_enable`` is not available, then it means that SMM codes for
68enabling and disabling automatic BIOS fan control are not whitelisted
69for your hardware. It is possible that codes that work for other
70laptops actually work for yours as well, or that you have to discover
71new codes.
72
73Check the list ``i8k_whitelist_fan_control`` in file
74``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first
75attempt you can try to add your machine and use an already-known code
76pair. If, after recompiling the kernel, you see that ``pwm1_enable``
77is present and works (i.e., you can manually control the fan speed),
78then please submit your finding as a kernel patch, so that other users
79can benefit from it. Please see
80:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
81for information on submitting patches.
82
83If no known code works on your machine, you need to resort to do some
84probing, because unfortunately Dell does not publish datasheets for
85its SMM. You can experiment with the code in `this repository`__ to
86probe the BIOS on your machine and discover the appropriate codes.
87
88 __ https://github.com/clopez/dellfan/
89
90Again, when you find new codes, we'd be happy to have your patches!
91
92``thermal`` interface
93---------------------------
94
95The 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
97using one of the thermal governors.
98
99Module 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
133Legacy ``/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
141The information provided by the kernel driver can be accessed by
142simply 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
147The 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
162A negative value, for example -22, indicates that the BIOS doesn't
163return the corresponding information. This is normal on some
164models/BIOSes.
165
166For performance reasons the ``/proc/i8k`` doesn't report by default
167the AC status since this SMM call takes a long time to execute and is
168not really needed.  If you want to see the ac status in ``/proc/i8k``
169you must explictitly enable this option by passing the
170``power_status=1`` parameter to insmod. If AC status is not
171available -1 is printed instead.
172
173The driver provides also an ioctl interface which can be used to
174obtain the same information and to control the fan status. The ioctl
175interface can be accessed from C programs or from shell using the
176i8kctl utility. See the source file of ``i8kutils`` for more
177information on how to use the ioctl interface.
178
179SMM 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
186The driver uses the SMM interface to send commands to the system BIOS.
187This interface is normally used by Dell's 32-bit diagnostic program or
188on newer notebook models by the buildin BIOS diagnostics.
189The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``,
190and may cause short hangs when the BIOS code is taking too long to
191execute.
192
193The SMM handler inside the system BIOS looks at the contents of the
194``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.
195Each register has a special purpose:
196
197=============== ==================================
198Register        Purpose
199=============== ==================================
200eax             Holds the command code before SMM,
201                holds the first result after SMM.
202ebx             Holds the arguments.
203ecx             Unknown, set to 0.
204edx             Holds the second result after SMM.
205esi             Unknown, set to 0.
206edi             Unknown, set to 0.
207=============== ==================================
208
209The 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
215SMM command codes
216-----------------
217
218=============== ======================= ================================================
219Command 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
309There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and
310disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.
311The commands are however causing severe sideeffects on many machines, so
312they are not used by default.
313
314On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the
315fans supports a 4th "magic" state, which signals the BIOS that automatic
316fan control should be enabled for a specific fan.
317However there are also some machines who do support a 4th regular fan state too,
318but in case of the "magic" state, the nominal RPM reported for this state is a
319placeholder value, which however is not always detectable.
320
321Firmware Bugs
322-------------
323
324The SMM calls can behave erratic on some machines:
325
326======================================================= =================
327Firmware Bug                                            Affected Machines
328======================================================= =================
329Reading of fan states return spurious errors.           Precision 490
330
331Reading of fan types causes erratic fan behaviour.      Studio XPS 8000
332
333                                                        Studio XPS 8100
334
335                                                        Inspiron 580
336
337                                                        Inspiron 3505
338
339Fan-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
348In case you experience similar issues on your Dell machine, please
349submit a bugreport on bugzilla to we can apply workarounds.
350
351Limitations
352-----------
353
354The SMM calls can take too long to execute on some machines, causing
355short hangs and/or audio glitches.
356Also the fan state needs to be restored after suspend, as well as
357the automatic mode settings.
358When reading a temperature sensor, values above 127 degrees indicate
359a BIOS read error or a deactivated sensor.
360