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