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@xxxxxxxxxx> --- Documentation/hwmon/dell-smm-hwmon.rst | 164 +++++++++++++++++++++++++ Documentation/hwmon/index.rst | 1 + 2 files changed, 165 insertions(+) create mode 100644 Documentation/hwmon/dell-smm-hwmon.rst diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst new file mode 100644 index 000000000000..6e51de2c7dc3 --- /dev/null +++ b/Documentation/hwmon/dell-smm-hwmon.rst @@ -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@xxxxxxxxxx> +:Copyright: |copy| 2019 Giovanni Mascellani <gio@xxxxxxxxxx> + +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 <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. diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 230ad59b462b..092435ad6bb8 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -44,6 +44,7 @@ Hardware Monitoring Kernel Drivers coretemp da9052 da9055 + dell-smm-hwmon dme1737 ds1621 ds620 -- 2.24.0
