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 169SMM Interface 170------------- 171 172.. warning:: The SMM interface was reverse-engineered by trial-and-error 173 since Dell did not provide any Documentation, 174 please keep that in mind. 175 176The driver uses the SMM interface to send commands to the system BIOS. 177This interface is normally used by Dell's 32-bit diagnostic program or 178on newer notebook models by the buildin BIOS diagnostics. 179The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``, 180and may cause short hangs when the BIOS code is taking too long to 181execute. 182 183The SMM handler inside the system BIOS looks at the contents of the 184``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers. 185Each register has a special purpose: 186 187=============== ================================== 188Register Purpose 189=============== ================================== 190eax Holds the command code before SMM, 191 holds the first result after SMM. 192ebx Holds the arguments. 193ecx Unknown, set to 0. 194edx Holds the second result after SMM. 195esi Unknown, set to 0. 196edi Unknown, set to 0. 197=============== ================================== 198 199The SMM handler can signal a failure by either: 200 201- setting the lower sixteen bits of ``eax`` to ``0xffff`` 202- not modifying ``eax`` at all 203- setting the carry flag 204 205SMM command codes 206----------------- 207 208=============== ======================= ================================================ 209Command Code Command Name Description 210=============== ======================= ================================================ 211``0x0025`` Get Fn key status Returns the Fn key pressed after SMM: 212 213 - 9th bit in ``eax`` indicates Volume up 214 - 10th bit in ``eax`` indicates Volume down 215 - both bits indicate Volume mute 216 217``0xa069`` Get power status Returns current power status after SMM: 218 219 - 1st bit in ``eax`` indicates Battery connected 220 - 3th bit in ``eax`` indicates AC connected 221 222``0x00a3`` Get fan state Returns current fan state after SMM: 223 224 - 1st byte in ``eax`` holds the current 225 fan state (0 - 2 or 3) 226 227``0x01a3`` Set fan state Sets the fan speed: 228 229 - 1st byte in ``ebx`` holds the fan number 230 - 2nd byte in ``ebx`` holds the desired 231 fan state (0 - 2 or 3) 232 233``0x02a3`` Get fan speed Returns the current fan speed in RPM: 234 235 - 1st byte in ``ebx`` holds the fan number 236 - 1st word in ``eax`` holds the current 237 fan speed in RPM (after SMM) 238 239``0x03a3`` Get fan type Returns the fan type: 240 241 - 1st byte in ``ebx`` holds the fan number 242 - 1st byte in ``eax`` holds the 243 fan type (after SMM): 244 245 - 5th bit indicates docking fan 246 - 1 indicates Processor fan 247 - 2 indicates Motherboard fan 248 - 3 indicates Video fan 249 - 4 indicates Power supply fan 250 - 5 indicates Chipset fan 251 - 6 indicates other fan type 252 253``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state: 254 255 - 1st byte in ``ebx`` holds the fan number 256 - 2nd byte in ``ebx`` holds the fan state 257 in question (0 - 2 or 3) 258 - 1st word in ``eax`` holds the nominal 259 fan speed in RPM (after SMM) 260 261``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state: 262 263 - 1st byte in ``ebx`` holds the fan number 264 - 2nd byte in ``ebx`` holds the fan state 265 in question (0 - 2 or 3) 266 - 1st byte in ``eax`` returns the speed 267 tolerance 268 269``0x10a3`` Get sensor temperature Returns the measured temperature: 270 271 - 1st byte in ``ebx`` holds the sensor number 272 - 1st byte in ``eax`` holds the measured 273 temperature (after SMM) 274 275``0x11a3`` Get sensor type Returns the sensor type: 276 277 - 1st byte in ``ebx`` holds the sensor number 278 - 1st byte in ``eax`` holds the 279 temperature type (after SMM): 280 281 - 1 indicates CPU sensor 282 - 2 indicates GPU sensor 283 - 3 indicates SODIMM sensor 284 - 4 indicates other sensor type 285 - 5 indicates Ambient sensor 286 - 6 indicates other sensor type 287 288``0xfea3`` Get SMM signature Returns Dell signature if interface 289 is supported (after SMM): 290 291 - ``eax`` holds 1145651527 292 (0x44494147 or "DIAG") 293 - ``edx`` holds 1145392204 294 (0x44454c4c or "DELL") 295 296``0xffa3`` Get SMM signature Same as ``0xfea3``, check both. 297=============== ======================= ================================================ 298 299There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and 300disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control. 301The commands are however causing severe sideeffects on many machines, so 302they are not used by default. 303 304On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the 305fans supports a 4th "magic" state, which signals the BIOS that automatic 306fan control should be enabled for a specific fan. 307However there are also some machines who do support a 4th regular fan state too, 308but in case of the "magic" state, the nominal RPM reported for this state is a 309placeholder value, which however is not always detectable. 310 311Firmware Bugs 312------------- 313 314The SMM calls can behave erratic on some machines: 315 316======================================================= ================= 317Firmware Bug Affected Machines 318======================================================= ================= 319Reading of fan states return spurious errors. Precision 490 320 321Reading of fan types causes erratic fan behaviour. Studio XPS 8000 322 323 Studio XPS 8100 324 325 Inspiron 580 326 327Fan-related SMM calls take too long (about 500ms). Inspiron 7720 328 329 Vostro 3360 330 331 XPS 13 9333 332 333 XPS 15 L502X 334======================================================= ================= 335 336In case you experience similar issues on your Dell machine, please 337submit a bugreport on bugzilla to we can apply workarounds. 338 339Limitations 340----------- 341 342The SMM calls can take too long to execute on some machines, causing 343short hangs and/or audio glitches. 344Also the fan state needs to be restored after suspend, as well as 345the automatic mode settings. 346When reading a temperature sensor, values above 127 degrees indicate 347a BIOS read error or a deactivated sensor. 348