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 89``thermal`` interface 90--------------------------- 91 92The driver also exports the fans as thermal cooling devices with 93``type`` set to ``dell-smm-fan[1-3]``. This allows for easy fan control 94using one of the thermal governors. 95 96Module parameters 97----------------- 98 99* force:bool 100 Force loading without checking for supported 101 models. (default: 0) 102 103* ignore_dmi:bool 104 Continue probing hardware even if DMI data does not 105 match. (default: 0) 106 107* restricted:bool 108 Allow fan control only to processes with the 109 ``CAP_SYS_ADMIN`` capability set or processes run 110 as root when using the legacy ``/proc/i8k`` 111 interface. In this case normal users will be able 112 to read temperature and fan status but not to 113 control the fan. If your notebook is shared with 114 other users and you don't trust them you may want 115 to use this option. (default: 1, only available 116 with ``CONFIG_I8K``) 117 118* power_status:bool 119 Report AC status in ``/proc/i8k``. (default: 0, 120 only available with ``CONFIG_I8K``) 121 122* fan_mult:uint 123 Factor to multiply fan speed with. (default: 124 autodetect) 125 126* fan_max:uint 127 Maximum configurable fan speed. (default: 128 autodetect) 129 130Legacy ``/proc`` interface 131-------------------------- 132 133.. warning:: This interface is obsolete and deprecated and should not 134 used in new applications. This interface is only 135 available when kernel is compiled with option 136 ``CONFIG_I8K``. 137 138The information provided by the kernel driver can be accessed by 139simply reading the ``/proc/i8k`` file. For example:: 140 141 $ cat /proc/i8k 142 1.0 A17 2J59L02 52 2 1 8040 6420 1 2 143 144The fields read from ``/proc/i8k`` are:: 145 146 1.0 A17 2J59L02 52 2 1 8040 6420 1 2 147 | | | | | | | | | | 148 | | | | | | | | | +------- 10. buttons status 149 | | | | | | | | +--------- 9. AC status 150 | | | | | | | +-------------- 8. fan0 RPM 151 | | | | | | +------------------- 7. fan1 RPM 152 | | | | | +--------------------- 6. fan0 status 153 | | | | +----------------------- 5. fan1 status 154 | | | +-------------------------- 4. temp0 reading (Celsius) 155 | | +---------------------------------- 3. Dell service tag (later known as 'serial number') 156 | +-------------------------------------- 2. BIOS version 157 +------------------------------------------ 1. /proc/i8k format version 158 159A negative value, for example -22, indicates that the BIOS doesn't 160return the corresponding information. This is normal on some 161models/BIOSes. 162 163For performance reasons the ``/proc/i8k`` doesn't report by default 164the AC status since this SMM call takes a long time to execute and is 165not really needed. If you want to see the ac status in ``/proc/i8k`` 166you must explictitly enable this option by passing the 167``power_status=1`` parameter to insmod. If AC status is not 168available -1 is printed instead. 169 170The driver provides also an ioctl interface which can be used to 171obtain the same information and to control the fan status. The ioctl 172interface can be accessed from C programs or from shell using the 173i8kctl utility. See the source file of ``i8kutils`` for more 174information on how to use the ioctl interface. 175 176SMM Interface 177------------- 178 179.. warning:: The SMM interface was reverse-engineered by trial-and-error 180 since Dell did not provide any Documentation, 181 please keep that in mind. 182 183The driver uses the SMM interface to send commands to the system BIOS. 184This interface is normally used by Dell's 32-bit diagnostic program or 185on newer notebook models by the buildin BIOS diagnostics. 186The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``, 187and may cause short hangs when the BIOS code is taking too long to 188execute. 189 190The SMM handler inside the system BIOS looks at the contents of the 191``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers. 192Each register has a special purpose: 193 194=============== ================================== 195Register Purpose 196=============== ================================== 197eax Holds the command code before SMM, 198 holds the first result after SMM. 199ebx Holds the arguments. 200ecx Unknown, set to 0. 201edx Holds the second result after SMM. 202esi Unknown, set to 0. 203edi Unknown, set to 0. 204=============== ================================== 205 206The SMM handler can signal a failure by either: 207 208- setting the lower sixteen bits of ``eax`` to ``0xffff`` 209- not modifying ``eax`` at all 210- setting the carry flag 211 212SMM command codes 213----------------- 214 215=============== ======================= ================================================ 216Command Code Command Name Description 217=============== ======================= ================================================ 218``0x0025`` Get Fn key status Returns the Fn key pressed after SMM: 219 220 - 9th bit in ``eax`` indicates Volume up 221 - 10th bit in ``eax`` indicates Volume down 222 - both bits indicate Volume mute 223 224``0xa069`` Get power status Returns current power status after SMM: 225 226 - 1st bit in ``eax`` indicates Battery connected 227 - 3th bit in ``eax`` indicates AC connected 228 229``0x00a3`` Get fan state Returns current fan state after SMM: 230 231 - 1st byte in ``eax`` holds the current 232 fan state (0 - 2 or 3) 233 234``0x01a3`` Set fan state Sets the fan speed: 235 236 - 1st byte in ``ebx`` holds the fan number 237 - 2nd byte in ``ebx`` holds the desired 238 fan state (0 - 2 or 3) 239 240``0x02a3`` Get fan speed Returns the current fan speed in RPM: 241 242 - 1st byte in ``ebx`` holds the fan number 243 - 1st word in ``eax`` holds the current 244 fan speed in RPM (after SMM) 245 246``0x03a3`` Get fan type Returns the fan type: 247 248 - 1st byte in ``ebx`` holds the fan number 249 - 1st byte in ``eax`` holds the 250 fan type (after SMM): 251 252 - 5th bit indicates docking fan 253 - 1 indicates Processor fan 254 - 2 indicates Motherboard fan 255 - 3 indicates Video fan 256 - 4 indicates Power supply fan 257 - 5 indicates Chipset fan 258 - 6 indicates other fan type 259 260``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state: 261 262 - 1st byte in ``ebx`` holds the fan number 263 - 2nd byte in ``ebx`` holds the fan state 264 in question (0 - 2 or 3) 265 - 1st word in ``eax`` holds the nominal 266 fan speed in RPM (after SMM) 267 268``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state: 269 270 - 1st byte in ``ebx`` holds the fan number 271 - 2nd byte in ``ebx`` holds the fan state 272 in question (0 - 2 or 3) 273 - 1st byte in ``eax`` returns the speed 274 tolerance 275 276``0x10a3`` Get sensor temperature Returns the measured temperature: 277 278 - 1st byte in ``ebx`` holds the sensor number 279 - 1st byte in ``eax`` holds the measured 280 temperature (after SMM) 281 282``0x11a3`` Get sensor type Returns the sensor type: 283 284 - 1st byte in ``ebx`` holds the sensor number 285 - 1st byte in ``eax`` holds the 286 temperature type (after SMM): 287 288 - 1 indicates CPU sensor 289 - 2 indicates GPU sensor 290 - 3 indicates SODIMM sensor 291 - 4 indicates other sensor type 292 - 5 indicates Ambient sensor 293 - 6 indicates other sensor type 294 295``0xfea3`` Get SMM signature Returns Dell signature if interface 296 is supported (after SMM): 297 298 - ``eax`` holds 1145651527 299 (0x44494147 or "DIAG") 300 - ``edx`` holds 1145392204 301 (0x44454c4c or "DELL") 302 303``0xffa3`` Get SMM signature Same as ``0xfea3``, check both. 304=============== ======================= ================================================ 305 306There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and 307disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control. 308The commands are however causing severe sideeffects on many machines, so 309they are not used by default. 310 311On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the 312fans supports a 4th "magic" state, which signals the BIOS that automatic 313fan control should be enabled for a specific fan. 314However there are also some machines who do support a 4th regular fan state too, 315but in case of the "magic" state, the nominal RPM reported for this state is a 316placeholder value, which however is not always detectable. 317 318Firmware Bugs 319------------- 320 321The SMM calls can behave erratic on some machines: 322 323======================================================= ================= 324Firmware Bug Affected Machines 325======================================================= ================= 326Reading of fan states return spurious errors. Precision 490 327 328Reading of fan types causes erratic fan behaviour. Studio XPS 8000 329 330 Studio XPS 8100 331 332 Inspiron 580 333 334 Inspiron 3505 335 336Fan-related SMM calls take too long (about 500ms). Inspiron 7720 337 338 Vostro 3360 339 340 XPS 13 9333 341 342 XPS 15 L502X 343======================================================= ================= 344 345In case you experience similar issues on your Dell machine, please 346submit a bugreport on bugzilla to we can apply workarounds. 347 348Limitations 349----------- 350 351The SMM calls can take too long to execute on some machines, causing 352short hangs and/or audio glitches. 353Also the fan state needs to be restored after suspend, as well as 354the automatic mode settings. 355When reading a temperature sensor, values above 127 degrees indicate 356a BIOS read error or a deactivated sensor. 357