0001 .. SPDX-License-Identifier: GPL-2.0-or-later
0002
0003 .. include:: <isonum.txt>
0004
0005 Kernel driver dell-smm-hwmon
0006 ============================
0007
0008 :Copyright: |copy| 2002-2005 Massimo Dal Zotto <dz@debian.org>
0009 :Copyright: |copy| 2019 Giovanni Mascellani <gio@debian.org>
0010
0011 Description
0012 -----------
0013
0014 On many Dell laptops the System Management Mode (SMM) BIOS can be
0015 queried for the status of fans and temperature sensors. Userspace
0016 utilities like ``sensors`` can be used to return the readings. The
0017 userspace suite `i8kutils`__ can also be used to read the sensors and
0018 automatically adjust fan speed (please notice that it currently uses
0019 the deprecated ``/proc/i8k`` interface).
0020
0021 __ https://github.com/vitorafsr/i8kutils
0022
0023 ``sysfs`` interface
0024 -------------------
0025
0026 Temperature sensors and fans can be queried and set via the standard
0027 ``hwmon`` interface on ``sysfs``, under the directory
0028 ``/sys/class/hwmon/hwmonX`` for some value of ``X`` (search for the
0029 ``X`` such that ``/sys/class/hwmon/hwmonX/name`` has content
0030 ``dell_smm``). A number of other attributes can be read or written:
0031
0032 =============================== ======= =======================================
0033 Name Perm Description
0034 =============================== ======= =======================================
0035 fan[1-3]_input RO Fan speed in RPM.
0036 fan[1-3]_label RO Fan label.
0037 fan[1-3]_min RO Minimal Fan speed in RPM
0038 fan[1-3]_max RO Maximal Fan speed in RPM
0039 fan[1-3]_target RO Expected Fan speed in RPM
0040 pwm[1-3] RW Control the fan PWM duty-cycle.
0041 pwm1_enable WO Enable or disable automatic BIOS fan
0042 control (not supported on all laptops,
0043 see below for details).
0044 temp[1-10]_input RO Temperature reading in milli-degrees
0045 Celsius.
0046 temp[1-10]_label RO Temperature sensor label.
0047 =============================== ======= =======================================
0048
0049 Due to the nature of the SMM interface, each pwmX attribute controls
0050 fan number X.
0051
0052 Disabling automatic BIOS fan control
0053 ------------------------------------
0054
0055 On some laptops the BIOS automatically sets fan speed every few
0056 seconds. Therefore the fan speed set by mean of this driver is quickly
0057 overwritten.
0058
0059 There is experimental support for disabling automatic BIOS fan
0060 control, at least on laptops where the corresponding SMM command is
0061 known, by writing the value ``1`` in the attribute ``pwm1_enable``
0062 (writing ``2`` enables automatic BIOS control again). Even if you have
0063 more than one fan, all of them are set to either enabled or disabled
0064 automatic fan control at the same time and, notwithstanding the name,
0065 ``pwm1_enable`` sets automatic control for all fans.
0066
0067 If ``pwm1_enable`` is not available, then it means that SMM codes for
0068 enabling and disabling automatic BIOS fan control are not whitelisted
0069 for your hardware. It is possible that codes that work for other
0070 laptops actually work for yours as well, or that you have to discover
0071 new codes.
0072
0073 Check the list ``i8k_whitelist_fan_control`` in file
0074 ``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first
0075 attempt you can try to add your machine and use an already-known code
0076 pair. If, after recompiling the kernel, you see that ``pwm1_enable``
0077 is present and works (i.e., you can manually control the fan speed),
0078 then please submit your finding as a kernel patch, so that other users
0079 can benefit from it. Please see
0080 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
0081 for information on submitting patches.
0082
0083 If no known code works on your machine, you need to resort to do some
0084 probing, because unfortunately Dell does not publish datasheets for
0085 its SMM. You can experiment with the code in `this repository`__ to
0086 probe the BIOS on your machine and discover the appropriate codes.
0087
0088 __ https://github.com/clopez/dellfan/
0089
0090 Again, when you find new codes, we'd be happy to have your patches!
0091
0092 ``thermal`` interface
0093 ---------------------------
0094
0095 The driver also exports the fans as thermal cooling devices with
0096 ``type`` set to ``dell-smm-fan[1-3]``. This allows for easy fan control
0097 using one of the thermal governors.
0098
0099 Module parameters
0100 -----------------
0101
0102 * force:bool
0103 Force loading without checking for supported
0104 models. (default: 0)
0105
0106 * ignore_dmi:bool
0107 Continue probing hardware even if DMI data does not
0108 match. (default: 0)
0109
0110 * restricted:bool
0111 Allow fan control only to processes with the
0112 ``CAP_SYS_ADMIN`` capability set or processes run
0113 as root when using the legacy ``/proc/i8k``
0114 interface. In this case normal users will be able
0115 to read temperature and fan status but not to
0116 control the fan. If your notebook is shared with
0117 other users and you don't trust them you may want
0118 to use this option. (default: 1, only available
0119 with ``CONFIG_I8K``)
0120
0121 * power_status:bool
0122 Report AC status in ``/proc/i8k``. (default: 0,
0123 only available with ``CONFIG_I8K``)
0124
0125 * fan_mult:uint
0126 Factor to multiply fan speed with. (default:
0127 autodetect)
0128
0129 * fan_max:uint
0130 Maximum configurable fan speed. (default:
0131 autodetect)
0132
0133 Legacy ``/proc`` interface
0134 --------------------------
0135
0136 .. warning:: This interface is obsolete and deprecated and should not
0137 used in new applications. This interface is only
0138 available when kernel is compiled with option
0139 ``CONFIG_I8K``.
0140
0141 The information provided by the kernel driver can be accessed by
0142 simply reading the ``/proc/i8k`` file. For example::
0143
0144 $ cat /proc/i8k
0145 1.0 A17 2J59L02 52 2 1 8040 6420 1 2
0146
0147 The fields read from ``/proc/i8k`` are::
0148
0149 1.0 A17 2J59L02 52 2 1 8040 6420 1 2
0150 | | | | | | | | | |
0151 | | | | | | | | | +------- 10. buttons status
0152 | | | | | | | | +--------- 9. AC status
0153 | | | | | | | +-------------- 8. fan0 RPM
0154 | | | | | | +------------------- 7. fan1 RPM
0155 | | | | | +--------------------- 6. fan0 status
0156 | | | | +----------------------- 5. fan1 status
0157 | | | +-------------------------- 4. temp0 reading (Celsius)
0158 | | +---------------------------------- 3. Dell service tag (later known as 'serial number')
0159 | +-------------------------------------- 2. BIOS version
0160 +------------------------------------------ 1. /proc/i8k format version
0161
0162 A negative value, for example -22, indicates that the BIOS doesn't
0163 return the corresponding information. This is normal on some
0164 models/BIOSes.
0165
0166 For performance reasons the ``/proc/i8k`` doesn't report by default
0167 the AC status since this SMM call takes a long time to execute and is
0168 not really needed. If you want to see the ac status in ``/proc/i8k``
0169 you must explictitly enable this option by passing the
0170 ``power_status=1`` parameter to insmod. If AC status is not
0171 available -1 is printed instead.
0172
0173 The driver provides also an ioctl interface which can be used to
0174 obtain the same information and to control the fan status. The ioctl
0175 interface can be accessed from C programs or from shell using the
0176 i8kctl utility. See the source file of ``i8kutils`` for more
0177 information on how to use the ioctl interface.
0178
0179 SMM Interface
0180 -------------
0181
0182 .. warning:: The SMM interface was reverse-engineered by trial-and-error
0183 since Dell did not provide any Documentation,
0184 please keep that in mind.
0185
0186 The driver uses the SMM interface to send commands to the system BIOS.
0187 This interface is normally used by Dell's 32-bit diagnostic program or
0188 on newer notebook models by the buildin BIOS diagnostics.
0189 The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``,
0190 and may cause short hangs when the BIOS code is taking too long to
0191 execute.
0192
0193 The SMM handler inside the system BIOS looks at the contents of the
0194 ``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.
0195 Each register has a special purpose:
0196
0197 =============== ==================================
0198 Register Purpose
0199 =============== ==================================
0200 eax Holds the command code before SMM,
0201 holds the first result after SMM.
0202 ebx Holds the arguments.
0203 ecx Unknown, set to 0.
0204 edx Holds the second result after SMM.
0205 esi Unknown, set to 0.
0206 edi Unknown, set to 0.
0207 =============== ==================================
0208
0209 The SMM handler can signal a failure by either:
0210
0211 - setting the lower sixteen bits of ``eax`` to ``0xffff``
0212 - not modifying ``eax`` at all
0213 - setting the carry flag
0214
0215 SMM command codes
0216 -----------------
0217
0218 =============== ======================= ================================================
0219 Command Code Command Name Description
0220 =============== ======================= ================================================
0221 ``0x0025`` Get Fn key status Returns the Fn key pressed after SMM:
0222
0223 - 9th bit in ``eax`` indicates Volume up
0224 - 10th bit in ``eax`` indicates Volume down
0225 - both bits indicate Volume mute
0226
0227 ``0xa069`` Get power status Returns current power status after SMM:
0228
0229 - 1st bit in ``eax`` indicates Battery connected
0230 - 3th bit in ``eax`` indicates AC connected
0231
0232 ``0x00a3`` Get fan state Returns current fan state after SMM:
0233
0234 - 1st byte in ``eax`` holds the current
0235 fan state (0 - 2 or 3)
0236
0237 ``0x01a3`` Set fan state Sets the fan speed:
0238
0239 - 1st byte in ``ebx`` holds the fan number
0240 - 2nd byte in ``ebx`` holds the desired
0241 fan state (0 - 2 or 3)
0242
0243 ``0x02a3`` Get fan speed Returns the current fan speed in RPM:
0244
0245 - 1st byte in ``ebx`` holds the fan number
0246 - 1st word in ``eax`` holds the current
0247 fan speed in RPM (after SMM)
0248
0249 ``0x03a3`` Get fan type Returns the fan type:
0250
0251 - 1st byte in ``ebx`` holds the fan number
0252 - 1st byte in ``eax`` holds the
0253 fan type (after SMM):
0254
0255 - 5th bit indicates docking fan
0256 - 1 indicates Processor fan
0257 - 2 indicates Motherboard fan
0258 - 3 indicates Video fan
0259 - 4 indicates Power supply fan
0260 - 5 indicates Chipset fan
0261 - 6 indicates other fan type
0262
0263 ``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state:
0264
0265 - 1st byte in ``ebx`` holds the fan number
0266 - 2nd byte in ``ebx`` holds the fan state
0267 in question (0 - 2 or 3)
0268 - 1st word in ``eax`` holds the nominal
0269 fan speed in RPM (after SMM)
0270
0271 ``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state:
0272
0273 - 1st byte in ``ebx`` holds the fan number
0274 - 2nd byte in ``ebx`` holds the fan state
0275 in question (0 - 2 or 3)
0276 - 1st byte in ``eax`` returns the speed
0277 tolerance
0278
0279 ``0x10a3`` Get sensor temperature Returns the measured temperature:
0280
0281 - 1st byte in ``ebx`` holds the sensor number
0282 - 1st byte in ``eax`` holds the measured
0283 temperature (after SMM)
0284
0285 ``0x11a3`` Get sensor type Returns the sensor type:
0286
0287 - 1st byte in ``ebx`` holds the sensor number
0288 - 1st byte in ``eax`` holds the
0289 temperature type (after SMM):
0290
0291 - 1 indicates CPU sensor
0292 - 2 indicates GPU sensor
0293 - 3 indicates SODIMM sensor
0294 - 4 indicates other sensor type
0295 - 5 indicates Ambient sensor
0296 - 6 indicates other sensor type
0297
0298 ``0xfea3`` Get SMM signature Returns Dell signature if interface
0299 is supported (after SMM):
0300
0301 - ``eax`` holds 1145651527
0302 (0x44494147 or "DIAG")
0303 - ``edx`` holds 1145392204
0304 (0x44454c4c or "DELL")
0305
0306 ``0xffa3`` Get SMM signature Same as ``0xfea3``, check both.
0307 =============== ======================= ================================================
0308
0309 There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and
0310 disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.
0311 The commands are however causing severe sideeffects on many machines, so
0312 they are not used by default.
0313
0314 On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the
0315 fans supports a 4th "magic" state, which signals the BIOS that automatic
0316 fan control should be enabled for a specific fan.
0317 However there are also some machines who do support a 4th regular fan state too,
0318 but in case of the "magic" state, the nominal RPM reported for this state is a
0319 placeholder value, which however is not always detectable.
0320
0321 Firmware Bugs
0322 -------------
0323
0324 The SMM calls can behave erratic on some machines:
0325
0326 ======================================================= =================
0327 Firmware Bug Affected Machines
0328 ======================================================= =================
0329 Reading of fan states return spurious errors. Precision 490
0330
0331 Reading of fan types causes erratic fan behaviour. Studio XPS 8000
0332
0333 Studio XPS 8100
0334
0335 Inspiron 580
0336
0337 Inspiron 3505
0338
0339 Fan-related SMM calls take too long (about 500ms). Inspiron 7720
0340
0341 Vostro 3360
0342
0343 XPS 13 9333
0344
0345 XPS 15 L502X
0346 ======================================================= =================
0347
0348 In case you experience similar issues on your Dell machine, please
0349 submit a bugreport on bugzilla to we can apply workarounds.
0350
0351 Limitations
0352 -----------
0353
0354 The SMM calls can take too long to execute on some machines, causing
0355 short hangs and/or audio glitches.
0356 Also the fan state needs to be restored after suspend, as well as
0357 the automatic mode settings.
0358 When reading a temperature sensor, values above 127 degrees indicate
0359 a BIOS read error or a deactivated sensor.
