Documentation/hwmon/dell-smm-hwmon.rst

   1 .. SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 .. include:: <isonum.txt>
   4
   5 Kernel 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
  11 Description
  12 -----------
  13
  14 On many Dell laptops the System Management Mode (SMM) BIOS can be
  15 queried for the status of fans and temperature sensors.  Userspace
  16 utilities like ``sensors`` can be used to return the readings. The
  17 userspace suite `i8kutils`__ can also be used to read the sensors and
  18 automatically adjust fan speed (please notice that it currently uses
  19 the deprecated ``/proc/i8k`` interface).
  20
  21  __ https://github.com/vitorafsr/i8kutils
  22
  23 ``sysfs`` interface
  24 -------------------
  25
  26 Temperature 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 =============================== ======= =======================================
  33 Name                            Perm    Description
  34 =============================== ======= =======================================
  35 fan[1-3]_input                  RO      Fan speed in RPM.
  36 fan[1-3]_label                  RO      Fan label.
  37 fan[1-3]_min                    RO      Minimal Fan speed in RPM
  38 fan[1-3]_max                    RO      Maximal Fan speed in RPM
  39 fan[1-3]_target                 RO      Expected Fan speed in RPM
  40 pwm[1-3]                        RW      Control the fan PWM duty-cycle.
  41 pwm1_enable                     WO      Enable or disable automatic BIOS fan
  42                                         control (not supported on all laptops,
  43                                         see below for details).
  44 temp[1-10]_input                RO      Temperature reading in milli-degrees
  45                                         Celsius.
  46 temp[1-10]_label                RO      Temperature sensor label.
  47 =============================== ======= =======================================
  48
  49 Due to the nature of the SMM interface, each pwmX attribute controls
  50 fan number X.
  51
  52 Disabling automatic BIOS fan control
  53 ------------------------------------
  54
  55 On some laptops the BIOS automatically sets fan speed every few
  56 seconds. Therefore the fan speed set by mean of this driver is quickly
  57 overwritten.
  58
  59 There is experimental support for disabling automatic BIOS fan
  60 control, at least on laptops where the corresponding SMM command is
  61 known, by writing the value ``1`` in the attribute ``pwm1_enable``
  62 (writing ``2`` enables automatic BIOS control again). Even if you have
  63 more than one fan, all of them are set to either enabled or disabled
  64 automatic fan control at the same time and, notwithstanding the name,
  65 ``pwm1_enable`` sets automatic control for all fans.
  66
  67 If ``pwm1_enable`` is not available, then it means that SMM codes for
  68 enabling and disabling automatic BIOS fan control are not whitelisted
  69 for your hardware. It is possible that codes that work for other
  70 laptops actually work for yours as well, or that you have to discover
  71 new codes.
  72
  73 Check the list ``i8k_whitelist_fan_control`` in file
  74 ``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first
  75 attempt you can try to add your machine and use an already-known code
  76 pair. If, after recompiling the kernel, you see that ``pwm1_enable``
  77 is present and works (i.e., you can manually control the fan speed),
  78 then please submit your finding as a kernel patch, so that other users
  79 can benefit from it. Please see
  80 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
  81 for information on submitting patches.
  82
  83 If no known code works on your machine, you need to resort to do some
  84 probing, because unfortunately Dell does not publish datasheets for
  85 its SMM. You can experiment with the code in `this repository`__ to
  86 probe the BIOS on your machine and discover the appropriate codes.
  87
  88  __ https://github.com/clopez/dellfan/
  89
  90 Again, when you find new codes, we'd be happy to have your patches!
  91
  92 ``thermal`` interface
  93 ---------------------------
  94
  95 The 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
  97 using one of the thermal governors.
  98
  99 Module 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
 133 Legacy ``/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
 141 The information provided by the kernel driver can be accessed by
 142 simply 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
 147 The 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
 162 A negative value, for example -22, indicates that the BIOS doesn't
 163 return the corresponding information. This is normal on some
 164 models/BIOSes.
 165
 166 For performance reasons the ``/proc/i8k`` doesn't report by default
 167 the AC status since this SMM call takes a long time to execute and is
 168 not really needed.  If you want to see the ac status in ``/proc/i8k``
 169 you must explictitly enable this option by passing the
 170 ``power_status=1`` parameter to insmod. If AC status is not
 171 available -1 is printed instead.
 172
 173 The driver provides also an ioctl interface which can be used to
 174 obtain the same information and to control the fan status. The ioctl
 175 interface can be accessed from C programs or from shell using the
 176 i8kctl utility. See the source file of ``i8kutils`` for more
 177 information on how to use the ioctl interface.
 178
 179 SMM 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
 186 The driver uses the SMM interface to send commands to the system BIOS.
 187 This interface is normally used by Dell's 32-bit diagnostic program or
 188 on newer notebook models by the buildin BIOS diagnostics.
 189 The SMM may cause short hangs when the BIOS code is taking too long to
 190 execute.
 191
 192 The SMM handler inside the system BIOS looks at the contents of the
 193 ``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.
 194 Each register has a special purpose:
 195
 196 =============== ==================================
 197 Register        Purpose
 198 =============== ==================================
 199 eax             Holds the command code before SMM,
 200                 holds the first result after SMM.
 201 ebx             Holds the arguments.
 202 ecx             Unknown, set to 0.
 203 edx             Holds the second result after SMM.
 204 esi             Unknown, set to 0.
 205 edi             Unknown, set to 0.
 206 =============== ==================================
 207
 208 The SMM handler can signal a failure by either:
 209
 210 - setting the lower sixteen bits of ``eax`` to ``0xffff``
 211 - not modifying ``eax`` at all
 212 - setting the carry flag (legacy SMM interface only)
 213
 214 Legacy SMM Interface
 215 --------------------
 216
 217 When using the legacy SMM interface, a SMM is triggered by writing the least significant byte
 218 of the command code to the special ioports ``0xb2`` and ``0x84``. This interface is not
 219 described inside the ACPI tables and can thus only be detected by issuing a test SMM call.
 220
 221 WMI SMM Interface
 222 -----------------
 223
 224 On 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
 242 Some machines support only the WMI SMM interface, while some machines support both interfaces.
 243 The driver automatically detects which interfaces are present and will use the WMI SMM interface
 244 if the legacy SMM interface is not present. The WMI SMM interface is usually slower than the
 245 legacy SMM interface since ACPI methods need to be called in order to trigger a SMM.
 246
 247 SMM command codes
 248 -----------------
 249
 250 =============== ======================= ================================================
 251 Command Code    Command Name            Description
 252 =============== ======================= ================================================
 253 ``0x0025``      Get Fn key status       Returns the Fn key pressed after SMM:
 254
 255                                         - 9th bit in ``eax`` indicates Volume up
 256                                         - 10th bit in ``eax`` indicates Volume down
 257                                         - both bits indicate Volume mute
 258
 259 ``0xa069``      Get power status        Returns current power status after SMM:
 260
 261                                         - 1st bit in ``eax`` indicates Battery connected
 262                                         - 3th bit in ``eax`` indicates AC connected
 263
 264 ``0x00a3``      Get fan state           Returns current fan state after SMM:
 265
 266                                         - 1st byte in ``eax`` holds the current
 267                                           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 number
 272                                         - 2nd byte in ``ebx`` holds the desired
 273                                           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 number
 278                                         - 1st word in ``eax`` holds the current
 279                                           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 number
 284                                         - 1st byte in ``eax`` holds the
 285                                           fan type (after SMM):
 286
 287                                           - 5th bit indicates docking fan
 288                                           - 1 indicates Processor fan
 289                                           - 2 indicates Motherboard fan
 290                                           - 3 indicates Video fan
 291                                           - 4 indicates Power supply fan
 292                                           - 5 indicates Chipset fan
 293                                           - 6 indicates other fan type
 294
 295 ``0x04a3``      Get nominal fan speed   Returns the nominal RPM in each fan state:
 296
 297                                         - 1st byte in ``ebx`` holds the fan number
 298                                         - 2nd byte in ``ebx`` holds the fan state
 299                                           in question (0 - 2 or 3)
 300                                         - 1st word in ``eax`` holds the nominal
 301                                           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 number
 306                                         - 2nd byte in ``ebx`` holds the fan state
 307                                           in question (0 - 2 or 3)
 308                                         - 1st byte in ``eax`` returns the speed
 309                                           tolerance
 310
 311 ``0x10a3``      Get sensor temperature  Returns the measured temperature:
 312
 313                                         - 1st byte in ``ebx`` holds the sensor number
 314                                         - 1st byte in ``eax`` holds the measured
 315                                           temperature (after SMM)
 316
 317 ``0x11a3``      Get sensor type         Returns the sensor type:
 318
 319                                         - 1st byte in ``ebx`` holds the sensor number
 320                                         - 1st byte in ``eax`` holds the
 321                                           temperature type (after SMM):
 322
 323                                           - 1 indicates CPU sensor
 324                                           - 2 indicates GPU sensor
 325                                           - 3 indicates SODIMM sensor
 326                                           - 4 indicates other sensor type
 327                                           - 5 indicates Ambient sensor
 328                                           - 6 indicates other sensor type
 329
 330 ``0xfea3``      Get SMM signature       Returns Dell signature if interface
 331                                         is supported (after SMM):
 332
 333                                         - ``eax`` holds 1145651527
 334                                           (0x44494147 or "DIAG")
 335                                         - ``edx`` holds 1145392204
 336                                           (0x44454c4c or "DELL")
 337
 338 ``0xffa3``      Get SMM signature       Same as ``0xfea3``, check both.
 339 =============== ======================= ================================================
 340
 341 There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and
 342 disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.
 343 The commands are however causing severe sideeffects on many machines, so
 344 they are not used by default.
 345
 346 On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the
 347 fans supports a 4th "magic" state, which signals the BIOS that automatic
 348 fan control should be enabled for a specific fan.
 349 However there are also some machines who do support a 4th regular fan state too,
 350 but in case of the "magic" state, the nominal RPM reported for this state is a
 351 placeholder value, which however is not always detectable.
 352
 353 Firmware Bugs
 354 -------------
 355
 356 The SMM calls can behave erratic on some machines:
 357
 358 ======================================================= =================
 359 Firmware Bug                                            Affected Machines
 360 ======================================================= =================
 361 Reading of fan states return spurious errors.           Precision 490
 362
 363                                                         OptiPlex 7060
 364
 365 Reading of fan types causes erratic fan behaviour.      Studio XPS 8000
 366
 367                                                         Studio XPS 8100
 368
 369                                                         Inspiron 580
 370
 371                                                         Inspiron 3505
 372
 373 Fan-related SMM calls take too long (about 500ms).      Inspiron 7720
 374
 375                                                         Vostro 3360
 376
 377                                                         XPS 13 9333
 378
 379                                                         XPS 15 L502X
 380 ======================================================= =================
 381
 382 In case you experience similar issues on your Dell machine, please
 383 submit a bugreport on bugzilla to we can apply workarounds.
 384
 385 Limitations
 386 -----------
 387
 388 The SMM calls can take too long to execute on some machines, causing
 389 short hangs and/or audio glitches.
 390 Also the fan state needs to be restored after suspend, as well as
 391 the automatic mode settings.
 392 When reading a temperature sensor, values above 127 degrees indicate
 393 a BIOS read error or a deactivated sensor.