[linux-block.git] / Documentation / hwmon / dell-smm-hwmon.rst

.. 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.
=============================== ======= =======================================

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