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
49Disabling automatic BIOS fan control
50------------------------------------
51
52On some laptops the BIOS automatically sets fan speed every few
53seconds. Therefore the fan speed set by mean of this driver is quickly
54overwritten.
55
56There is experimental support for disabling automatic BIOS fan
57control, at least on laptops where the corresponding SMM command is
58known, by writing the value ``1`` in the attribute ``pwm1_enable``
59(writing ``2`` enables automatic BIOS control again). Even if you have
60more than one fan, all of them are set to either enabled or disabled
61automatic fan control at the same time and, notwithstanding the name,
62``pwm1_enable`` sets automatic control for all fans.
63
64If ``pwm1_enable`` is not available, then it means that SMM codes for
65enabling and disabling automatic BIOS fan control are not whitelisted
66for your hardware. It is possible that codes that work for other
67laptops actually work for yours as well, or that you have to discover
68new codes.
69
70Check the list ``i8k_whitelist_fan_control`` in file
71``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first
72attempt you can try to add your machine and use an already-known code
73pair. If, after recompiling the kernel, you see that ``pwm1_enable``
74is present and works (i.e., you can manually control the fan speed),
75then please submit your finding as a kernel patch, so that other users
76can benefit from it. Please see
77:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
78for information on submitting patches.
79
80If no known code works on your machine, you need to resort to do some
81probing, because unfortunately Dell does not publish datasheets for
82its SMM. You can experiment with the code in `this repository`__ to
83probe the BIOS on your machine and discover the appropriate codes.
84
85 __ https://github.com/clopez/dellfan/
86
87Again, when you find new codes, we'd be happy to have your patches!
88
89Module parameters
90-----------------
91
92* force:bool
93                   Force loading without checking for supported
94                   models. (default: 0)
95
96* ignore_dmi:bool
97                   Continue probing hardware even if DMI data does not
98                   match. (default: 0)
99
100* restricted:bool
101                   Allow fan control only to processes with the
102                   ``CAP_SYS_ADMIN`` capability set or processes run
103                   as root when using the legacy ``/proc/i8k``
104                   interface. In this case normal users will be able
105                   to read temperature and fan status but not to
106                   control the fan.  If your notebook is shared with
107                   other users and you don't trust them you may want
108                   to use this option. (default: 1, only available
109                   with ``CONFIG_I8K``)
110
111* power_status:bool
112                   Report AC status in ``/proc/i8k``. (default: 0,
113                   only available with ``CONFIG_I8K``)
114
115* fan_mult:uint
116                   Factor to multiply fan speed with. (default:
117                   autodetect)
118
119* fan_max:uint
120                   Maximum configurable fan speed. (default:
121                   autodetect)
122
123Legacy ``/proc`` interface
124--------------------------
125
126.. warning:: This interface is obsolete and deprecated and should not
127             used in new applications. This interface is only
128             available when kernel is compiled with option
129             ``CONFIG_I8K``.
130
131The information provided by the kernel driver can be accessed by
132simply reading the ``/proc/i8k`` file. For example::
133
134    $ cat /proc/i8k
135    1.0 A17 2J59L02 52 2 1 8040 6420 1 2
136
137The fields read from ``/proc/i8k`` are::
138
139    1.0 A17 2J59L02 52 2 1 8040 6420 1 2
140    |   |   |       |  | | |    |    | |
141    |   |   |       |  | | |    |    | +------- 10. buttons status
142    |   |   |       |  | | |    |    +--------- 9.  AC status
143    |   |   |       |  | | |    +-------------- 8.  fan0 RPM
144    |   |   |       |  | | +------------------- 7.  fan1 RPM
145    |   |   |       |  | +--------------------- 6.  fan0 status
146    |   |   |       |  +----------------------- 5.  fan1 status
147    |   |   |       +-------------------------- 4.  temp0 reading (Celsius)
148    |   |   +---------------------------------- 3.  Dell service tag (later known as 'serial number')
149    |   +-------------------------------------- 2.  BIOS version
150    +------------------------------------------ 1.  /proc/i8k format version
151
152A negative value, for example -22, indicates that the BIOS doesn't
153return the corresponding information. This is normal on some
154models/BIOSes.
155
156For performance reasons the ``/proc/i8k`` doesn't report by default
157the AC status since this SMM call takes a long time to execute and is
158not really needed.  If you want to see the ac status in ``/proc/i8k``
159you must explictitly enable this option by passing the
160``power_status=1`` parameter to insmod. If AC status is not
161available -1 is printed instead.
162
163The driver provides also an ioctl interface which can be used to
164obtain the same information and to control the fan status. The ioctl
165interface can be accessed from C programs or from shell using the
166i8kctl utility. See the source file of ``i8kutils`` for more
167information on how to use the ioctl interface.
168