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-4]_input RO Fan speed in RPM. 36fan[1-4]_label RO Fan label. 37fan[1-4]_min RO Minimal Fan speed in RPM 38fan[1-4]_max RO Maximal Fan speed in RPM 39fan[1-4]_target RO Expected Fan speed in RPM 40pwm[1-4] RW Control the fan PWM duty-cycle. 41pwm[1-4]_enable RW/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 52Enabling/Disabling automatic BIOS fan control 53--------------------------------------------- 54 55There exist two methods for enabling/disabling automatic BIOS fan control: 56 571. Separate SMM commands to enable/disable automatic BIOS fan control for all fans. 58 592. A special fan state that enables automatic BIOS fan control for a individual fan. 60 61The driver cannot reliably detect what method should be used on a given 62device, so instead the following heuristic is used: 63 64- use fan state 3 for enabling BIOS fan control if the maximum fan state 65 setable by the user is smaller than 3 (default setting). 66 67- use separate SMM commands if device is whitelisted to support them. 68 69When using the first method, each fan will have a standard ``pwmX_enable`` 70sysfs attribute. Writing ``1`` into this attribute will disable automatic 71BIOS fan control for the associated fan and set it to maximum speed. Enabling 72BIOS fan control again can be achieved by writing ``2`` into this attribute. 73Reading this sysfs attributes returns the current setting as reported by 74the underlying hardware. 75 76When using the second method however, only the ``pwm1_enable`` sysfs attribute 77will be available to enable/disable automatic BIOS fan control globaly for all 78fans available on a given device. Additionally, this sysfs attribute is write-only 79as there exists no SMM command for reading the current fan control setting. 80 81If no ``pwmX_enable`` attributes are available, then it means that the driver 82cannot use the first method and the SMM codes for enabling and disabling automatic 83BIOS fan control are not whitelisted for your device. It is possible that codes 84that work for other laptops actually work for yours as well, or that you have to 85discover new codes. 86 87Check the list ``i8k_whitelist_fan_control`` in file 88``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first 89attempt you can try to add your machine and use an already-known code 90pair. If, after recompiling the kernel, you see that ``pwm1_enable`` 91is present and works (i.e., you can manually control the fan speed), 92then please submit your finding as a kernel patch, so that other users 93can benefit from it. Please see 94:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 95for information on submitting patches. 96 97If no known code works on your machine, you need to resort to do some 98probing, because unfortunately Dell does not publish datasheets for 99its SMM. You can experiment with the code in `this repository`__ to 100probe the BIOS on your machine and discover the appropriate codes. 101 102 __ https://github.com/clopez/dellfan/ 103 104Again, when you find new codes, we'd be happy to have your patches! 105 106``thermal`` interface 107--------------------------- 108 109The driver also exports the fans as thermal cooling devices with 110``type`` set to ``dell-smm-fan[1-4]``. This allows for easy fan control 111using one of the thermal governors. 112 113Module parameters 114----------------- 115 116* force:bool 117 Force loading without checking for supported 118 models. (default: 0) 119 120* ignore_dmi:bool 121 Continue probing hardware even if DMI data does not 122 match. (default: 0) 123 124* restricted:bool 125 Allow fan control only to processes with the 126 ``CAP_SYS_ADMIN`` capability set or processes run 127 as root when using the legacy ``/proc/i8k`` 128 interface. In this case normal users will be able 129 to read temperature and fan status but not to 130 control the fan. If your notebook is shared with 131 other users and you don't trust them you may want 132 to use this option. (default: 1, only available 133 with ``CONFIG_I8K``) 134 135* power_status:bool 136 Report AC status in ``/proc/i8k``. (default: 0, 137 only available with ``CONFIG_I8K``) 138 139* fan_mult:uint 140 Factor to multiply fan speed with. (default: 141 autodetect) 142 143* fan_max:uint 144 Maximum configurable fan speed. (default: 145 autodetect) 146 147Legacy ``/proc`` interface 148-------------------------- 149 150.. warning:: This interface is obsolete and deprecated and should not 151 used in new applications. This interface is only 152 available when kernel is compiled with option 153 ``CONFIG_I8K``. 154 155The information provided by the kernel driver can be accessed by 156simply reading the ``/proc/i8k`` file. For example:: 157 158 $ cat /proc/i8k 159 1.0 A17 2J59L02 52 2 1 8040 6420 1 2 160 161The fields read from ``/proc/i8k`` are:: 162 163 1.0 A17 2J59L02 52 2 1 8040 6420 1 2 164 | | | | | | | | | | 165 | | | | | | | | | +------- 10. buttons status 166 | | | | | | | | +--------- 9. AC status 167 | | | | | | | +-------------- 8. fan0 RPM 168 | | | | | | +------------------- 7. fan1 RPM 169 | | | | | +--------------------- 6. fan0 status 170 | | | | +----------------------- 5. fan1 status 171 | | | +-------------------------- 4. temp0 reading (Celsius) 172 | | +---------------------------------- 3. Dell service tag (later known as 'serial number') 173 | +-------------------------------------- 2. BIOS version 174 +------------------------------------------ 1. /proc/i8k format version 175 176A negative value, for example -22, indicates that the BIOS doesn't 177return the corresponding information. This is normal on some 178models/BIOSes. 179 180For performance reasons the ``/proc/i8k`` doesn't report by default 181the AC status since this SMM call takes a long time to execute and is 182not really needed. If you want to see the ac status in ``/proc/i8k`` 183you must explictitly enable this option by passing the 184``power_status=1`` parameter to insmod. If AC status is not 185available -1 is printed instead. 186 187The driver provides also an ioctl interface which can be used to 188obtain the same information and to control the fan status. The ioctl 189interface can be accessed from C programs or from shell using the 190i8kctl utility. See the source file of ``i8kutils`` for more 191information on how to use the ioctl interface. 192 193SMM Interface 194------------- 195 196.. warning:: The SMM interface was reverse-engineered by trial-and-error 197 since Dell did not provide any Documentation, 198 please keep that in mind. 199 200The driver uses the SMM interface to send commands to the system BIOS. 201This interface is normally used by Dell's 32-bit diagnostic program or 202on newer notebook models by the buildin BIOS diagnostics. 203The SMM may cause short hangs when the BIOS code is taking too long to 204execute. 205 206The SMM handler inside the system BIOS looks at the contents of the 207``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers. 208Each register has a special purpose: 209 210=============== ================================== 211Register Purpose 212=============== ================================== 213eax Holds the command code before SMM, 214 holds the first result after SMM. 215ebx Holds the arguments. 216ecx Unknown, set to 0. 217edx Holds the second result after SMM. 218esi Unknown, set to 0. 219edi Unknown, set to 0. 220=============== ================================== 221 222The SMM handler can signal a failure by either: 223 224- setting the lower sixteen bits of ``eax`` to ``0xffff`` 225- not modifying ``eax`` at all 226- setting the carry flag (legacy SMM interface only) 227 228Legacy SMM Interface 229-------------------- 230 231When using the legacy SMM interface, a SMM is triggered by writing the least significant byte 232of the command code to the special ioports ``0xb2`` and ``0x84``. This interface is not 233described inside the ACPI tables and can thus only be detected by issuing a test SMM call. 234 235WMI SMM Interface 236----------------- 237 238On modern Dell machines, the SMM calls are done over ACPI WMI: 239 240:: 241 242 #pragma namespace("\\\\.\\root\\dcim\\sysman\\diagnostics") 243 [WMI, Provider("Provider_DiagnosticsServices"), Dynamic, Locale("MS\\0x409"), 244 Description("RunDellDiag"), guid("{F1DDEE52-063C-4784-A11E-8A06684B9B01}")] 245 class LegacyDiags { 246 [key, read] string InstanceName; 247 [read] boolean Active; 248 249 [WmiMethodId(1), Implemented, read, write, Description("Legacy Method ")] 250 void Execute([in, out] uint32 EaxLen, [in, out, WmiSizeIs("EaxLen") : ToInstance] uint8 EaxVal[], 251 [in, out] uint32 EbxLen, [in, out, WmiSizeIs("EbxLen") : ToInstance] uint8 EbxVal[], 252 [in, out] uint32 EcxLen, [in, out, WmiSizeIs("EcxLen") : ToInstance] uint8 EcxVal[], 253 [in, out] uint32 EdxLen, [in, out, WmiSizeIs("EdxLen") : ToInstance] uint8 EdxVal[]); 254 }; 255 256Some machines support only the WMI SMM interface, while some machines support both interfaces. 257The driver automatically detects which interfaces are present and will use the WMI SMM interface 258if the legacy SMM interface is not present. The WMI SMM interface is usually slower than the 259legacy SMM interface since ACPI methods need to be called in order to trigger a SMM. 260 261SMM command codes 262----------------- 263 264=============== ======================= ================================================ 265Command Code Command Name Description 266=============== ======================= ================================================ 267``0x0025`` Get Fn key status Returns the Fn key pressed after SMM: 268 269 - 9th bit in ``eax`` indicates Volume up 270 - 10th bit in ``eax`` indicates Volume down 271 - both bits indicate Volume mute 272 273``0xa069`` Get power status Returns current power status after SMM: 274 275 - 1st bit in ``eax`` indicates Battery connected 276 - 3th bit in ``eax`` indicates AC connected 277 278``0x00a3`` Get fan state Returns current fan state after SMM: 279 280 - 1st byte in ``eax`` holds the current 281 fan state (0 - 2 or 3) 282 283``0x01a3`` Set fan state Sets the fan speed: 284 285 - 1st byte in ``ebx`` holds the fan number 286 - 2nd byte in ``ebx`` holds the desired 287 fan state (0 - 2 or 3) 288 289``0x02a3`` Get fan speed Returns the current fan speed in RPM: 290 291 - 1st byte in ``ebx`` holds the fan number 292 - 1st word in ``eax`` holds the current 293 fan speed in RPM (after SMM) 294 295``0x03a3`` Get fan type Returns the fan type: 296 297 - 1st byte in ``ebx`` holds the fan number 298 - 1st byte in ``eax`` holds the 299 fan type (after SMM): 300 301 - 5th bit indicates docking fan 302 - 1 indicates Processor fan 303 - 2 indicates Motherboard fan 304 - 3 indicates Video fan 305 - 4 indicates Power supply fan 306 - 5 indicates Chipset fan 307 - 6 indicates other fan type 308 309``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state: 310 311 - 1st byte in ``ebx`` holds the fan number 312 - 2nd byte in ``ebx`` holds the fan state 313 in question (0 - 2 or 3) 314 - 1st word in ``eax`` holds the nominal 315 fan speed in RPM (after SMM) 316 317``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state: 318 319 - 1st byte in ``ebx`` holds the fan number 320 - 2nd byte in ``ebx`` holds the fan state 321 in question (0 - 2 or 3) 322 - 1st byte in ``eax`` returns the speed 323 tolerance 324 325``0x10a3`` Get sensor temperature Returns the measured temperature: 326 327 - 1st byte in ``ebx`` holds the sensor number 328 - 1st byte in ``eax`` holds the measured 329 temperature (after SMM) 330 331``0x11a3`` Get sensor type Returns the sensor type: 332 333 - 1st byte in ``ebx`` holds the sensor number 334 - 1st byte in ``eax`` holds the 335 temperature type (after SMM): 336 337 - 1 indicates CPU sensor 338 - 2 indicates GPU sensor 339 - 3 indicates SODIMM sensor 340 - 4 indicates other sensor type 341 - 5 indicates Ambient sensor 342 - 6 indicates other sensor type 343 344``0xfea3`` Get SMM signature Returns Dell signature if interface 345 is supported (after SMM): 346 347 - ``eax`` holds 1145651527 348 (0x44494147 or "DIAG") 349 - ``edx`` holds 1145392204 350 (0x44454c4c or "DELL") 351 352``0xffa3`` Get SMM signature Same as ``0xfea3``, check both. 353=============== ======================= ================================================ 354 355There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and 356disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control. 357The commands are however causing severe sideeffects on many machines, so 358they are not used by default. 359 360On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the 361fans supports a 4th "magic" state, which signals the BIOS that automatic 362fan control should be enabled for a specific fan. 363However there are also some machines who do support a 4th regular fan state too, 364but in case of the "magic" state, the nominal RPM reported for this state is a 365placeholder value, which however is not always detectable. 366 367Firmware Bugs 368------------- 369 370The SMM calls can behave erratic on some machines: 371 372======================================================= ================= 373Firmware Bug Affected Machines 374======================================================= ================= 375Reading of fan states return spurious errors. Precision 490 376 377 OptiPlex 7060 378 379Reading of fan types causes erratic fan behaviour. Studio XPS 8000 380 381 Studio XPS 8100 382 383 Inspiron 580 384 385 Inspiron 3505 386 387Fan-related SMM calls take too long (about 500ms). Inspiron 7720 388 389 Vostro 3360 390 391 XPS 13 9333 392 393 XPS 15 L502X 394======================================================= ================= 395 396In case you experience similar issues on your Dell machine, please 397submit a bugreport on bugzilla to we can apply workarounds. 398 399Limitations 400----------- 401 402The SMM calls can take too long to execute on some machines, causing 403short hangs and/or audio glitches. 404Also the fan state needs to be restored after suspend, as well as 405the automatic mode settings. 406When reading a temperature sensor, values above 127 degrees indicate 407a BIOS read error or a deactivated sensor. 408