394 lines · plain
1.. SPDX-License-Identifier: GPL-2.0-or-later2 3.. include:: <isonum.txt>4 5Kernel driver dell-smm-hwmon6============================7 8:Copyright: |copy| 2002-2005 Massimo Dal Zotto <dz@debian.org>9:Copyright: |copy| 2019 Giovanni Mascellani <gio@debian.org>10 11Description12-----------13 14On many Dell laptops the System Management Mode (SMM) BIOS can be15queried for the status of fans and temperature sensors. Userspace16utilities like ``sensors`` can be used to return the readings. The17userspace suite `i8kutils`__ can also be used to read the sensors and18automatically adjust fan speed (please notice that it currently uses19the deprecated ``/proc/i8k`` interface).20 21 __ https://github.com/vitorafsr/i8kutils22 23``sysfs`` interface24-------------------25 26Temperature sensors and fans can be queried and set via the standard27``hwmon`` interface on ``sysfs``, under the directory28``/sys/class/hwmon/hwmonX`` for some value of ``X`` (search for the29``X`` such that ``/sys/class/hwmon/hwmonX/name`` has content30``dell_smm``). A number of other attributes can be read or written:31 32=============================== ======= =======================================33Name Perm Description34=============================== ======= =======================================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 RPM38fan[1-3]_max RO Maximal Fan speed in RPM39fan[1-3]_target RO Expected Fan speed in RPM40pwm[1-3] RW Control the fan PWM duty-cycle.41pwm1_enable WO Enable or disable automatic BIOS fan42 control (not supported on all laptops,43 see below for details).44temp[1-10]_input RO Temperature reading in milli-degrees45 Celsius.46temp[1-10]_label RO Temperature sensor label.47=============================== ======= =======================================48 49Due to the nature of the SMM interface, each pwmX attribute controls50fan number X.51 52Disabling automatic BIOS fan control53------------------------------------54 55On some laptops the BIOS automatically sets fan speed every few56seconds. Therefore the fan speed set by mean of this driver is quickly57overwritten.58 59There is experimental support for disabling automatic BIOS fan60control, at least on laptops where the corresponding SMM command is61known, by writing the value ``1`` in the attribute ``pwm1_enable``62(writing ``2`` enables automatic BIOS control again). Even if you have63more than one fan, all of them are set to either enabled or disabled64automatic 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 for68enabling and disabling automatic BIOS fan control are not whitelisted69for your hardware. It is possible that codes that work for other70laptops actually work for yours as well, or that you have to discover71new codes.72 73Check the list ``i8k_whitelist_fan_control`` in file74``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first75attempt you can try to add your machine and use an already-known code76pair. 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 users79can benefit from it. Please see80: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 some84probing, because unfortunately Dell does not publish datasheets for85its SMM. You can experiment with the code in `this repository`__ to86probe 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`` interface93---------------------------94 95The driver also exports the fans as thermal cooling devices with96``type`` set to ``dell-smm-fan[1-3]``. This allows for easy fan control97using one of the thermal governors.98 99Module parameters100-----------------101 102* force:bool103 Force loading without checking for supported104 models. (default: 0)105 106* ignore_dmi:bool107 Continue probing hardware even if DMI data does not108 match. (default: 0)109 110* restricted:bool111 Allow fan control only to processes with the112 ``CAP_SYS_ADMIN`` capability set or processes run113 as root when using the legacy ``/proc/i8k``114 interface. In this case normal users will be able115 to read temperature and fan status but not to116 control the fan. If your notebook is shared with117 other users and you don't trust them you may want118 to use this option. (default: 1, only available119 with ``CONFIG_I8K``)120 121* power_status:bool122 Report AC status in ``/proc/i8k``. (default: 0,123 only available with ``CONFIG_I8K``)124 125* fan_mult:uint126 Factor to multiply fan speed with. (default:127 autodetect)128 129* fan_max:uint130 Maximum configurable fan speed. (default:131 autodetect)132 133Legacy ``/proc`` interface134--------------------------135 136.. warning:: This interface is obsolete and deprecated and should not137 used in new applications. This interface is only138 available when kernel is compiled with option139 ``CONFIG_I8K``.140 141The information provided by the kernel driver can be accessed by142simply reading the ``/proc/i8k`` file. For example::143 144 $ cat /proc/i8k145 1.0 A17 2J59L02 52 2 1 8040 6420 1 2146 147The fields read from ``/proc/i8k`` are::148 149 1.0 A17 2J59L02 52 2 1 8040 6420 1 2150 | | | | | | | | | |151 | | | | | | | | | +------- 10. buttons status152 | | | | | | | | +--------- 9. AC status153 | | | | | | | +-------------- 8. fan0 RPM154 | | | | | | +------------------- 7. fan1 RPM155 | | | | | +--------------------- 6. fan0 status156 | | | | +----------------------- 5. fan1 status157 | | | +-------------------------- 4. temp0 reading (Celsius)158 | | +---------------------------------- 3. Dell service tag (later known as 'serial number')159 | +-------------------------------------- 2. BIOS version160 +------------------------------------------ 1. /proc/i8k format version161 162A negative value, for example -22, indicates that the BIOS doesn't163return the corresponding information. This is normal on some164models/BIOSes.165 166For performance reasons the ``/proc/i8k`` doesn't report by default167the AC status since this SMM call takes a long time to execute and is168not really needed. If you want to see the ac status in ``/proc/i8k``169you must explictitly enable this option by passing the170``power_status=1`` parameter to insmod. If AC status is not171available -1 is printed instead.172 173The driver provides also an ioctl interface which can be used to174obtain the same information and to control the fan status. The ioctl175interface can be accessed from C programs or from shell using the176i8kctl utility. See the source file of ``i8kutils`` for more177information on how to use the ioctl interface.178 179SMM Interface180-------------181 182.. warning:: The SMM interface was reverse-engineered by trial-and-error183 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 or188on newer notebook models by the buildin BIOS diagnostics.189The SMM may cause short hangs when the BIOS code is taking too long to190execute.191 192The SMM handler inside the system BIOS looks at the contents of the193``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.194Each register has a special purpose:195 196=============== ==================================197Register Purpose198=============== ==================================199eax Holds the command code before SMM,200 holds the first result after SMM.201ebx Holds the arguments.202ecx Unknown, set to 0.203edx Holds the second result after SMM.204esi Unknown, set to 0.205edi Unknown, set to 0.206=============== ==================================207 208The SMM handler can signal a failure by either:209 210- setting the lower sixteen bits of ``eax`` to ``0xffff``211- not modifying ``eax`` at all212- setting the carry flag (legacy SMM interface only)213 214Legacy SMM Interface215--------------------216 217When using the legacy SMM interface, a SMM is triggered by writing the least significant byte218of the command code to the special ioports ``0xb2`` and ``0x84``. This interface is not219described inside the ACPI tables and can thus only be detected by issuing a test SMM call.220 221WMI SMM Interface222-----------------223 224On modern Dell machines, the SMM calls are done over ACPI WMI:225 226::227 228 #pragma namespace("\\\\.\\root\\dcim\\sysman\\diagnostics")229 [WMI, Provider("Provider_DiagnosticsServices"), Dynamic, Locale("MS\\0x409"),230 Description("RunDellDiag"), guid("{F1DDEE52-063C-4784-A11E-8A06684B9B01}")]231 class LegacyDiags {232 [key, read] string InstanceName;233 [read] boolean Active;234 235 [WmiMethodId(1), Implemented, read, write, Description("Legacy Method ")]236 void Execute([in, out] uint32 EaxLen, [in, out, WmiSizeIs("EaxLen") : ToInstance] uint8 EaxVal[],237 [in, out] uint32 EbxLen, [in, out, WmiSizeIs("EbxLen") : ToInstance] uint8 EbxVal[],238 [in, out] uint32 EcxLen, [in, out, WmiSizeIs("EcxLen") : ToInstance] uint8 EcxVal[],239 [in, out] uint32 EdxLen, [in, out, WmiSizeIs("EdxLen") : ToInstance] uint8 EdxVal[]);240 };241 242Some machines support only the WMI SMM interface, while some machines support both interfaces.243The driver automatically detects which interfaces are present and will use the WMI SMM interface244if the legacy SMM interface is not present. The WMI SMM interface is usually slower than the245legacy SMM interface since ACPI methods need to be called in order to trigger a SMM.246 247SMM command codes248-----------------249 250=============== ======================= ================================================251Command Code Command Name Description252=============== ======================= ================================================253``0x0025`` Get Fn key status Returns the Fn key pressed after SMM:254 255 - 9th bit in ``eax`` indicates Volume up256 - 10th bit in ``eax`` indicates Volume down257 - both bits indicate Volume mute258 259``0xa069`` Get power status Returns current power status after SMM:260 261 - 1st bit in ``eax`` indicates Battery connected262 - 3th bit in ``eax`` indicates AC connected263 264``0x00a3`` Get fan state Returns current fan state after SMM:265 266 - 1st byte in ``eax`` holds the current267 fan state (0 - 2 or 3)268 269``0x01a3`` Set fan state Sets the fan speed:270 271 - 1st byte in ``ebx`` holds the fan number272 - 2nd byte in ``ebx`` holds the desired273 fan state (0 - 2 or 3)274 275``0x02a3`` Get fan speed Returns the current fan speed in RPM:276 277 - 1st byte in ``ebx`` holds the fan number278 - 1st word in ``eax`` holds the current279 fan speed in RPM (after SMM)280 281``0x03a3`` Get fan type Returns the fan type:282 283 - 1st byte in ``ebx`` holds the fan number284 - 1st byte in ``eax`` holds the285 fan type (after SMM):286 287 - 5th bit indicates docking fan288 - 1 indicates Processor fan289 - 2 indicates Motherboard fan290 - 3 indicates Video fan291 - 4 indicates Power supply fan292 - 5 indicates Chipset fan293 - 6 indicates other fan type294 295``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state:296 297 - 1st byte in ``ebx`` holds the fan number298 - 2nd byte in ``ebx`` holds the fan state299 in question (0 - 2 or 3)300 - 1st word in ``eax`` holds the nominal301 fan speed in RPM (after SMM)302 303``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state:304 305 - 1st byte in ``ebx`` holds the fan number306 - 2nd byte in ``ebx`` holds the fan state307 in question (0 - 2 or 3)308 - 1st byte in ``eax`` returns the speed309 tolerance310 311``0x10a3`` Get sensor temperature Returns the measured temperature:312 313 - 1st byte in ``ebx`` holds the sensor number314 - 1st byte in ``eax`` holds the measured315 temperature (after SMM)316 317``0x11a3`` Get sensor type Returns the sensor type:318 319 - 1st byte in ``ebx`` holds the sensor number320 - 1st byte in ``eax`` holds the321 temperature type (after SMM):322 323 - 1 indicates CPU sensor324 - 2 indicates GPU sensor325 - 3 indicates SODIMM sensor326 - 4 indicates other sensor type327 - 5 indicates Ambient sensor328 - 6 indicates other sensor type329 330``0xfea3`` Get SMM signature Returns Dell signature if interface331 is supported (after SMM):332 333 - ``eax`` holds 1145651527334 (0x44494147 or "DIAG")335 - ``edx`` holds 1145392204336 (0x44454c4c or "DELL")337 338``0xffa3`` Get SMM signature Same as ``0xfea3``, check both.339=============== ======================= ================================================340 341There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and342disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.343The commands are however causing severe sideeffects on many machines, so344they are not used by default.345 346On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the347fans supports a 4th "magic" state, which signals the BIOS that automatic348fan control should be enabled for a specific fan.349However there are also some machines who do support a 4th regular fan state too,350but in case of the "magic" state, the nominal RPM reported for this state is a351placeholder value, which however is not always detectable.352 353Firmware Bugs354-------------355 356The SMM calls can behave erratic on some machines:357 358======================================================= =================359Firmware Bug Affected Machines360======================================================= =================361Reading of fan states return spurious errors. Precision 490362 363 OptiPlex 7060364 365Reading of fan types causes erratic fan behaviour. Studio XPS 8000366 367 Studio XPS 8100368 369 Inspiron 580370 371 Inspiron 3505372 373Fan-related SMM calls take too long (about 500ms). Inspiron 7720374 375 Vostro 3360376 377 XPS 13 9333378 379 XPS 15 L502X380======================================================= =================381 382In case you experience similar issues on your Dell machine, please383submit a bugreport on bugzilla to we can apply workarounds.384 385Limitations386-----------387 388The SMM calls can take too long to execute on some machines, causing389short hangs and/or audio glitches.390Also the fan state needs to be restored after suspend, as well as391the automatic mode settings.392When reading a temperature sensor, values above 127 degrees indicate393a BIOS read error or a deactivated sensor.394