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 pwm[1-3]                        RW      Control the fan PWM duty-cycle.
  38 pwm1_enable                     WO      Enable or disable automatic BIOS fan
  39                                         control (not supported on all laptops,
  40                                         see below for details).
  41 temp[1-10]_input                RO      Temperature reading in milli-degrees
  42                                         Celsius.
  43 temp[1-10]_label                RO      Temperature sensor label.
  44 =============================== ======= =======================================
  45
  46 Disabling automatic BIOS fan control
  47 ------------------------------------
  48
  49 On some laptops the BIOS automatically sets fan speed every few
  50 seconds. Therefore the fan speed set by mean of this driver is quickly
  51 overwritten.
  52
  53 There is experimental support for disabling automatic BIOS fan
  54 control, at least on laptops where the corresponding SMM command is
  55 known, by writing the value ``1`` in the attribute ``pwm1_enable``
  56 (writing ``2`` enables automatic BIOS control again). Even if you have
  57 more than one fan, all of them are set to either enabled or disabled
  58 automatic fan control at the same time and, notwithstanding the name,
  59 ``pwm1_enable`` sets automatic control for all fans.
  60
  61 If ``pwm1_enable`` is not available, then it means that SMM codes for
  62 enabling and disabling automatic BIOS fan control are not whitelisted
  63 for your hardware. It is possible that codes that work for other
  64 laptops actually work for yours as well, or that you have to discover
  65 new codes.
  66
  67 Check the list ``i8k_whitelist_fan_control`` in file
  68 ``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first
  69 attempt you can try to add your machine and use an already-known code
  70 pair. If, after recompiling the kernel, you see that ``pwm1_enable``
  71 is present and works (i.e., you can manually control the fan speed),
  72 then please submit your finding as a kernel patch, so that other users
  73 can benefit from it. Please see
  74 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
  75 for information on submitting patches.
  76
  77 If no known code works on your machine, you need to resort to do some
  78 probing, because unfortunately Dell does not publish datasheets for
  79 its SMM. You can experiment with the code in `this repository`__ to
  80 probe the BIOS on your machine and discover the appropriate codes.
  81
  82  __ https://github.com/clopez/dellfan/
  83
  84 Again, when you find new codes, we'd be happy to have your patches!
  85
  86 Module parameters
  87 -----------------
  88
  89 * force:bool
  90                    Force loading without checking for supported
  91                    models. (default: 0)
  92
  93 * ignore_dmi:bool
  94                    Continue probing hardware even if DMI data does not
  95                    match. (default: 0)
  96
  97 * restricted:bool
  98                    Allow fan control only to processes with the
  99                    ``CAP_SYS_ADMIN`` capability set or processes run
 100                    as root when using the legacy ``/proc/i8k``
 101                    interface. In this case normal users will be able
 102                    to read temperature and fan status but not to
 103                    control the fan.  If your notebook is shared with
 104                    other users and you don't trust them you may want
 105                    to use this option. (default: 1, only available
 106                    with ``CONFIG_I8K``)
 107
 108 * power_status:bool
 109                    Report AC status in ``/proc/i8k``. (default: 0,
 110                    only available with ``CONFIG_I8K``)
 111
 112 * fan_mult:uint
 113                    Factor to multiply fan speed with. (default:
 114                    autodetect)
 115
 116 * fan_max:uint
 117                    Maximum configurable fan speed. (default:
 118                    autodetect)
 119
 120 Legacy ``/proc`` interface
 121 --------------------------
 122
 123 .. warning:: This interface is obsolete and deprecated and should not
 124              used in new applications. This interface is only
 125              available when kernel is compiled with option
 126              ``CONFIG_I8K``.
 127
 128 The information provided by the kernel driver can be accessed by
 129 simply reading the ``/proc/i8k`` file. For example::
 130
 131     $ cat /proc/i8k
 132     1.0 A17 2J59L02 52 2 1 8040 6420 1 2
 133
 134 The fields read from ``/proc/i8k`` are::
 135
 136     1.0 A17 2J59L02 52 2 1 8040 6420 1 2
 137     |   |   |       |  | | |    |    | |
 138     |   |   |       |  | | |    |    | +------- 10. buttons status
 139     |   |   |       |  | | |    |    +--------- 9.  AC status
 140     |   |   |       |  | | |    +-------------- 8.  fan0 RPM
 141     |   |   |       |  | | +------------------- 7.  fan1 RPM
 142     |   |   |       |  | +--------------------- 6.  fan0 status
 143     |   |   |       |  +----------------------- 5.  fan1 status
 144     |   |   |       +-------------------------- 4.  temp0 reading (Celsius)
 145     |   |   +---------------------------------- 3.  Dell service tag (later known as 'serial number')
 146     |   +-------------------------------------- 2.  BIOS version
 147     +------------------------------------------ 1.  /proc/i8k format version
 148
 149 A negative value, for example -22, indicates that the BIOS doesn't
 150 return the corresponding information. This is normal on some
 151 models/BIOSes.
 152
 153 For performance reasons the ``/proc/i8k`` doesn't report by default
 154 the AC status since this SMM call takes a long time to execute and is
 155 not really needed.  If you want to see the ac status in ``/proc/i8k``
 156 you must explictitly enable this option by passing the
 157 ``power_status=1`` parameter to insmod. If AC status is not
 158 available -1 is printed instead.
 159
 160 The driver provides also an ioctl interface which can be used to
 161 obtain the same information and to control the fan status. The ioctl
 162 interface can be accessed from C programs or from shell using the
 163 i8kctl utility. See the source file of ``i8kutils`` for more
 164 information on how to use the ioctl interface.