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 Module 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
 123 Legacy ``/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
 131 The information provided by the kernel driver can be accessed by
 132 simply 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
 137 The 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
 152 A negative value, for example -22, indicates that the BIOS doesn't
 153 return the corresponding information. This is normal on some
 154 models/BIOSes.
 155
 156 For performance reasons the ``/proc/i8k`` doesn't report by default
 157 the AC status since this SMM call takes a long time to execute and is
 158 not really needed.  If you want to see the ac status in ``/proc/i8k``
 159 you must explictitly enable this option by passing the
 160 ``power_status=1`` parameter to insmod. If AC status is not
 161 available -1 is printed instead.
 162
 163 The driver provides also an ioctl interface which can be used to
 164 obtain the same information and to control the fan status. The ioctl
 165 interface can be accessed from C programs or from shell using the
 166 i8kctl utility. See the source file of ``i8kutils`` for more
 167 information on how to use the ioctl interface.