360 lines
16 KiB
ReStructuredText
360 lines
16 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0-or-later
|
|
|
|
.. include:: <isonum.txt>
|
|
|
|
Kernel driver dell-smm-hwmon
|
|
============================
|
|
|
|
:Copyright: |copy| 2002-2005 Massimo Dal Zotto <dz@debian.org>
|
|
:Copyright: |copy| 2019 Giovanni Mascellani <gio@debian.org>
|
|
|
|
Description
|
|
-----------
|
|
|
|
On many Dell laptops the System Management Mode (SMM) BIOS can be
|
|
queried for the status of fans and temperature sensors. Userspace
|
|
utilities like ``sensors`` can be used to return the readings. The
|
|
userspace suite `i8kutils`__ can also be used to read the sensors and
|
|
automatically adjust fan speed (please notice that it currently uses
|
|
the deprecated ``/proc/i8k`` interface).
|
|
|
|
__ https://github.com/vitorafsr/i8kutils
|
|
|
|
``sysfs`` interface
|
|
-------------------
|
|
|
|
Temperature sensors and fans can be queried and set via the standard
|
|
``hwmon`` interface on ``sysfs``, under the directory
|
|
``/sys/class/hwmon/hwmonX`` for some value of ``X`` (search for the
|
|
``X`` such that ``/sys/class/hwmon/hwmonX/name`` has content
|
|
``dell_smm``). A number of other attributes can be read or written:
|
|
|
|
=============================== ======= =======================================
|
|
Name Perm Description
|
|
=============================== ======= =======================================
|
|
fan[1-3]_input RO Fan speed in RPM.
|
|
fan[1-3]_label RO Fan label.
|
|
fan[1-3]_min RO Minimal Fan speed in RPM
|
|
fan[1-3]_max RO Maximal Fan speed in RPM
|
|
fan[1-3]_target RO Expected Fan speed in RPM
|
|
pwm[1-3] RW Control the fan PWM duty-cycle.
|
|
pwm1_enable WO Enable or disable automatic BIOS fan
|
|
control (not supported on all laptops,
|
|
see below for details).
|
|
temp[1-10]_input RO Temperature reading in milli-degrees
|
|
Celsius.
|
|
temp[1-10]_label RO Temperature sensor label.
|
|
=============================== ======= =======================================
|
|
|
|
Due to the nature of the SMM interface, each pwmX attribute controls
|
|
fan number X.
|
|
|
|
Disabling automatic BIOS fan control
|
|
------------------------------------
|
|
|
|
On some laptops the BIOS automatically sets fan speed every few
|
|
seconds. Therefore the fan speed set by mean of this driver is quickly
|
|
overwritten.
|
|
|
|
There is experimental support for disabling automatic BIOS fan
|
|
control, at least on laptops where the corresponding SMM command is
|
|
known, by writing the value ``1`` in the attribute ``pwm1_enable``
|
|
(writing ``2`` enables automatic BIOS control again). Even if you have
|
|
more than one fan, all of them are set to either enabled or disabled
|
|
automatic fan control at the same time and, notwithstanding the name,
|
|
``pwm1_enable`` sets automatic control for all fans.
|
|
|
|
If ``pwm1_enable`` is not available, then it means that SMM codes for
|
|
enabling and disabling automatic BIOS fan control are not whitelisted
|
|
for your hardware. It is possible that codes that work for other
|
|
laptops actually work for yours as well, or that you have to discover
|
|
new codes.
|
|
|
|
Check the list ``i8k_whitelist_fan_control`` in file
|
|
``drivers/hwmon/dell-smm-hwmon.c`` in the kernel tree: as a first
|
|
attempt you can try to add your machine and use an already-known code
|
|
pair. If, after recompiling the kernel, you see that ``pwm1_enable``
|
|
is present and works (i.e., you can manually control the fan speed),
|
|
then please submit your finding as a kernel patch, so that other users
|
|
can benefit from it. Please see
|
|
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
|
|
for information on submitting patches.
|
|
|
|
If no known code works on your machine, you need to resort to do some
|
|
probing, because unfortunately Dell does not publish datasheets for
|
|
its SMM. You can experiment with the code in `this repository`__ to
|
|
probe the BIOS on your machine and discover the appropriate codes.
|
|
|
|
__ https://github.com/clopez/dellfan/
|
|
|
|
Again, when you find new codes, we'd be happy to have your patches!
|
|
|
|
``thermal`` interface
|
|
---------------------------
|
|
|
|
The driver also exports the fans as thermal cooling devices with
|
|
``type`` set to ``dell-smm-fan[1-3]``. This allows for easy fan control
|
|
using one of the thermal governors.
|
|
|
|
Module parameters
|
|
-----------------
|
|
|
|
* force:bool
|
|
Force loading without checking for supported
|
|
models. (default: 0)
|
|
|
|
* ignore_dmi:bool
|
|
Continue probing hardware even if DMI data does not
|
|
match. (default: 0)
|
|
|
|
* restricted:bool
|
|
Allow fan control only to processes with the
|
|
``CAP_SYS_ADMIN`` capability set or processes run
|
|
as root when using the legacy ``/proc/i8k``
|
|
interface. In this case normal users will be able
|
|
to read temperature and fan status but not to
|
|
control the fan. If your notebook is shared with
|
|
other users and you don't trust them you may want
|
|
to use this option. (default: 1, only available
|
|
with ``CONFIG_I8K``)
|
|
|
|
* power_status:bool
|
|
Report AC status in ``/proc/i8k``. (default: 0,
|
|
only available with ``CONFIG_I8K``)
|
|
|
|
* fan_mult:uint
|
|
Factor to multiply fan speed with. (default:
|
|
autodetect)
|
|
|
|
* fan_max:uint
|
|
Maximum configurable fan speed. (default:
|
|
autodetect)
|
|
|
|
Legacy ``/proc`` interface
|
|
--------------------------
|
|
|
|
.. warning:: This interface is obsolete and deprecated and should not
|
|
used in new applications. This interface is only
|
|
available when kernel is compiled with option
|
|
``CONFIG_I8K``.
|
|
|
|
The information provided by the kernel driver can be accessed by
|
|
simply reading the ``/proc/i8k`` file. For example::
|
|
|
|
$ cat /proc/i8k
|
|
1.0 A17 2J59L02 52 2 1 8040 6420 1 2
|
|
|
|
The fields read from ``/proc/i8k`` are::
|
|
|
|
1.0 A17 2J59L02 52 2 1 8040 6420 1 2
|
|
| | | | | | | | | |
|
|
| | | | | | | | | +------- 10. buttons status
|
|
| | | | | | | | +--------- 9. AC status
|
|
| | | | | | | +-------------- 8. fan0 RPM
|
|
| | | | | | +------------------- 7. fan1 RPM
|
|
| | | | | +--------------------- 6. fan0 status
|
|
| | | | +----------------------- 5. fan1 status
|
|
| | | +-------------------------- 4. temp0 reading (Celsius)
|
|
| | +---------------------------------- 3. Dell service tag (later known as 'serial number')
|
|
| +-------------------------------------- 2. BIOS version
|
|
+------------------------------------------ 1. /proc/i8k format version
|
|
|
|
A negative value, for example -22, indicates that the BIOS doesn't
|
|
return the corresponding information. This is normal on some
|
|
models/BIOSes.
|
|
|
|
For performance reasons the ``/proc/i8k`` doesn't report by default
|
|
the AC status since this SMM call takes a long time to execute and is
|
|
not really needed. If you want to see the ac status in ``/proc/i8k``
|
|
you must explictitly enable this option by passing the
|
|
``power_status=1`` parameter to insmod. If AC status is not
|
|
available -1 is printed instead.
|
|
|
|
The driver provides also an ioctl interface which can be used to
|
|
obtain the same information and to control the fan status. The ioctl
|
|
interface can be accessed from C programs or from shell using the
|
|
i8kctl utility. See the source file of ``i8kutils`` for more
|
|
information on how to use the ioctl interface.
|
|
|
|
SMM Interface
|
|
-------------
|
|
|
|
.. warning:: The SMM interface was reverse-engineered by trial-and-error
|
|
since Dell did not provide any Documentation,
|
|
please keep that in mind.
|
|
|
|
The driver uses the SMM interface to send commands to the system BIOS.
|
|
This interface is normally used by Dell's 32-bit diagnostic program or
|
|
on newer notebook models by the buildin BIOS diagnostics.
|
|
The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``,
|
|
and may cause short hangs when the BIOS code is taking too long to
|
|
execute.
|
|
|
|
The SMM handler inside the system BIOS looks at the contents of the
|
|
``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.
|
|
Each register has a special purpose:
|
|
|
|
=============== ==================================
|
|
Register Purpose
|
|
=============== ==================================
|
|
eax Holds the command code before SMM,
|
|
holds the first result after SMM.
|
|
ebx Holds the arguments.
|
|
ecx Unknown, set to 0.
|
|
edx Holds the second result after SMM.
|
|
esi Unknown, set to 0.
|
|
edi Unknown, set to 0.
|
|
=============== ==================================
|
|
|
|
The SMM handler can signal a failure by either:
|
|
|
|
- setting the lower sixteen bits of ``eax`` to ``0xffff``
|
|
- not modifying ``eax`` at all
|
|
- setting the carry flag
|
|
|
|
SMM command codes
|
|
-----------------
|
|
|
|
=============== ======================= ================================================
|
|
Command Code Command Name Description
|
|
=============== ======================= ================================================
|
|
``0x0025`` Get Fn key status Returns the Fn key pressed after SMM:
|
|
|
|
- 9th bit in ``eax`` indicates Volume up
|
|
- 10th bit in ``eax`` indicates Volume down
|
|
- both bits indicate Volume mute
|
|
|
|
``0xa069`` Get power status Returns current power status after SMM:
|
|
|
|
- 1st bit in ``eax`` indicates Battery connected
|
|
- 3th bit in ``eax`` indicates AC connected
|
|
|
|
``0x00a3`` Get fan state Returns current fan state after SMM:
|
|
|
|
- 1st byte in ``eax`` holds the current
|
|
fan state (0 - 2 or 3)
|
|
|
|
``0x01a3`` Set fan state Sets the fan speed:
|
|
|
|
- 1st byte in ``ebx`` holds the fan number
|
|
- 2nd byte in ``ebx`` holds the desired
|
|
fan state (0 - 2 or 3)
|
|
|
|
``0x02a3`` Get fan speed Returns the current fan speed in RPM:
|
|
|
|
- 1st byte in ``ebx`` holds the fan number
|
|
- 1st word in ``eax`` holds the current
|
|
fan speed in RPM (after SMM)
|
|
|
|
``0x03a3`` Get fan type Returns the fan type:
|
|
|
|
- 1st byte in ``ebx`` holds the fan number
|
|
- 1st byte in ``eax`` holds the
|
|
fan type (after SMM):
|
|
|
|
- 5th bit indicates docking fan
|
|
- 1 indicates Processor fan
|
|
- 2 indicates Motherboard fan
|
|
- 3 indicates Video fan
|
|
- 4 indicates Power supply fan
|
|
- 5 indicates Chipset fan
|
|
- 6 indicates other fan type
|
|
|
|
``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state:
|
|
|
|
- 1st byte in ``ebx`` holds the fan number
|
|
- 2nd byte in ``ebx`` holds the fan state
|
|
in question (0 - 2 or 3)
|
|
- 1st word in ``eax`` holds the nominal
|
|
fan speed in RPM (after SMM)
|
|
|
|
``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state:
|
|
|
|
- 1st byte in ``ebx`` holds the fan number
|
|
- 2nd byte in ``ebx`` holds the fan state
|
|
in question (0 - 2 or 3)
|
|
- 1st byte in ``eax`` returns the speed
|
|
tolerance
|
|
|
|
``0x10a3`` Get sensor temperature Returns the measured temperature:
|
|
|
|
- 1st byte in ``ebx`` holds the sensor number
|
|
- 1st byte in ``eax`` holds the measured
|
|
temperature (after SMM)
|
|
|
|
``0x11a3`` Get sensor type Returns the sensor type:
|
|
|
|
- 1st byte in ``ebx`` holds the sensor number
|
|
- 1st byte in ``eax`` holds the
|
|
temperature type (after SMM):
|
|
|
|
- 1 indicates CPU sensor
|
|
- 2 indicates GPU sensor
|
|
- 3 indicates SODIMM sensor
|
|
- 4 indicates other sensor type
|
|
- 5 indicates Ambient sensor
|
|
- 6 indicates other sensor type
|
|
|
|
``0xfea3`` Get SMM signature Returns Dell signature if interface
|
|
is supported (after SMM):
|
|
|
|
- ``eax`` holds 1145651527
|
|
(0x44494147 or "DIAG")
|
|
- ``edx`` holds 1145392204
|
|
(0x44454c4c or "DELL")
|
|
|
|
``0xffa3`` Get SMM signature Same as ``0xfea3``, check both.
|
|
=============== ======================= ================================================
|
|
|
|
There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and
|
|
disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.
|
|
The commands are however causing severe sideeffects on many machines, so
|
|
they are not used by default.
|
|
|
|
On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the
|
|
fans supports a 4th "magic" state, which signals the BIOS that automatic
|
|
fan control should be enabled for a specific fan.
|
|
However there are also some machines who do support a 4th regular fan state too,
|
|
but in case of the "magic" state, the nominal RPM reported for this state is a
|
|
placeholder value, which however is not always detectable.
|
|
|
|
Firmware Bugs
|
|
-------------
|
|
|
|
The SMM calls can behave erratic on some machines:
|
|
|
|
======================================================= =================
|
|
Firmware Bug Affected Machines
|
|
======================================================= =================
|
|
Reading of fan states return spurious errors. Precision 490
|
|
|
|
Reading of fan types causes erratic fan behaviour. Studio XPS 8000
|
|
|
|
Studio XPS 8100
|
|
|
|
Inspiron 580
|
|
|
|
Inspiron 3505
|
|
|
|
Fan-related SMM calls take too long (about 500ms). Inspiron 7720
|
|
|
|
Vostro 3360
|
|
|
|
XPS 13 9333
|
|
|
|
XPS 15 L502X
|
|
======================================================= =================
|
|
|
|
In case you experience similar issues on your Dell machine, please
|
|
submit a bugreport on bugzilla to we can apply workarounds.
|
|
|
|
Limitations
|
|
-----------
|
|
|
|
The SMM calls can take too long to execute on some machines, causing
|
|
short hangs and/or audio glitches.
|
|
Also the fan state needs to be restored after suspend, as well as
|
|
the automatic mode settings.
|
|
When reading a temperature sensor, values above 127 degrees indicate
|
|
a BIOS read error or a deactivated sensor.
|