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