korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-11-11 21:38:32 +08:00
Code Issues Packages Projects Releases Wiki Activity

dell-smm-hwmon: Add documentation

Browse Source 
Part of the documentation is taken from the README of the userspace
utils (https://github.com/vitorafsr/i8kutils). The license is GPL-2+
and the author Massimo Dal Zotto is already credited as author of
the module. Therefore there should be no copyright problem.

I also added a paragraph with specific information on the experimental
support for automatic BIOS fan control.

Signed-off-by: Giovanni Mascellani <gio@debian.org>
Link: https://lore.kernel.org/r/20191122101519.1246458-2-gio@debian.org
[groeck: Fixed some of the documentation warnings]
Signed-off-by: Guenter Roeck <linux@roeck-us.net>
This commit is contained in:
Giovanni Mascellani 2019-11-22 11:15:19 +01:00 committed by Guenter Roeck
parent afe45277ad
commit 4a1288f1c1
2 changed files with 165 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
Documentation/hwmon/dell-smm-hwmon.rst Normal file
View File

@ -0,0 +1,164 @@
.. 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.
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.
=============================== ======= =======================================
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!
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.

1
Documentation/hwmon/index.rst
View File

@ -45,6 +45,7 @@ Hardware Monitoring Kernel Drivers
coretemp
da9052
da9055
dell-smm-hwmon
dme1737
ds1621
ds620