Received: by 2002:a25:7ec1:0:0:0:0:0 with SMTP id z184csp3081596ybc; Mon, 18 Nov 2019 09:13:32 -0800 (PST) X-Google-Smtp-Source: APXvYqy3+nrMoIopmYxb0KfiYZG7NZeDVXLS7P1kzW3xvQ6s5Nh76XzAElw52elr+7Zwk5diPWGc X-Received: by 2002:a1c:5fc4:: with SMTP id t187mr66110wmb.142.1574097212256; Mon, 18 Nov 2019 09:13:32 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1574097212; cv=none; d=google.com; s=arc-20160816; b=pMsRmY/pDGMm3QG+Pc7Krl+LQmCyWqDlAc7pgh1GmJlIanJUe1MSVcK9yWpgU614rK PuxRpx9LHnyXYAx0/iizbLtvOID+zVZ0D9ejVthN2mTuOQqAiuDoA3JQ9hsLe6cOfkwK nRs6I/JYzxJ319muhT9Sfs4GMrYj0r3jpR5DG2mHHYplR7bGTMExqr0zGKroVz+ZbimF 5AHhTVFRJowyTi3LdlkhAM0QMPIlcDxqrmfn9BszeE2ROcSMJS0mylO2BUedSZk7BTeb IDQnaIS5QvZL8DA1BuymjHpDq0CGB7/NrQXp9fDQLHWvXQPA5Wd++292XG7c1X3BVgTJ J/RQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=vrM2GJ8zaZzMdACO+vfyKD2redc/C7VRdzjytgq4Q24=; b=yHbpccCYjqQFXgvAhJBaSiRsSJNp4kWceUHe5MbtS6AyORou5e1TN1/FiVHHl7tW2l QI6hHiM3QSpDUR988Wl0h9pkfF8xyEZsS9Um4xzEgAgqMFpHI5j8gnjuZnL7ChS+hEe8 L7bA4VIGHBi7HFp0vR1qr681r6AapZjcTyJRRB2VVWvN/8mQBbM7luVkN+TIwymFZocL Kcy1A6RUlLXrYIhGSEKJMXjCOmGFfHJPznZAerhgwQXdLpyaPwpH4/pgMHw2jaKYIfik 9bxlPKppO+HgJeTc9whOvJy08Nli/9TIWMA4A7Z8YAVKn/qAD6fDZ61uPZfH3GOpiojm Kc+Q== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id h37si14385251eda.249.2019.11.18.09.13.06; Mon, 18 Nov 2019 09:13:32 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727135AbfKRRMA (ORCPT + 99 others); Mon, 18 Nov 2019 12:12:00 -0500 Received: from pietrobattiston.it ([92.243.7.39]:50842 "EHLO jauntuale.pietrobattiston.it" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1726370AbfKRRL7 (ORCPT ); Mon, 18 Nov 2019 12:11:59 -0500 Received: from amalgama (pno-math-19.ulb.ac.be [164.15.133.19]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) (Authenticated sender: giovanni) by jauntuale.pietrobattiston.it (Postfix) with ESMTPSA id 16B0BE0546; Mon, 18 Nov 2019 18:11:57 +0100 (CET) Received: by amalgama (Postfix, from userid 1000) id CD1053C0244; Mon, 18 Nov 2019 18:11:56 +0100 (CET) From: Giovanni Mascellani To: Jean Delvare , Guenter Roeck , Jonathan Corbet , =?UTF-8?q?Pali=20Roh=C3=A1r?= , linux-hwmon@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Giovanni Mascellani Subject: [PATCH v4 2/2] dell-smm-hwmon: Add documentation Date: Mon, 18 Nov 2019 18:11:48 +0100 Message-Id: <20191118171148.76373-2-gio@debian.org> X-Mailer: git-send-email 2.24.0 In-Reply-To: <20191118171148.76373-1-gio@debian.org> References: <20191118171148.76373-1-gio@debian.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- Documentation/hwmon/dell-smm-hwmon.rst | 112 +++++++++++++++++++++++++ Documentation/hwmon/index.rst | 1 + 2 files changed, 113 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..f80d30d8a02a --- /dev/null +++ b/Documentation/hwmon/dell-smm-hwmon.rst @@ -0,0 +1,112 @@ +Kernel driver dell-smm-hwmon +============================ + +Description +----------- + +On many Dell laptops the System Management Mode (SMM) BIOS can be +queried for the status of fans and temperature sensors. The userspace +suite `i8kutils`__ can be used to read the sensors and automatically +adjust fan speed. + + __ https://github.com/vitorafsr/i8kutils + +``/proc`` interface +------------------- + +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. right fan rpm + | | | | | | +------------------- 7. left fan rpm + | | | | | +--------------------- 6. right fan status + | | | | +----------------------- 5. left fan status + | | | +-------------------------- 4. CPU temperature (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. + +``sysfs`` interface +------------------- + +Temperature sensors and fans can also be queried and set via the +standard ``hwmon`` interface on ``sysfs``. + +Disabling automatic BIOS fan control +------------------------------------ + +On some laptops, the BIOS automatically sets fan speed every few +seconds. Therefore the fan speed set via ``/proc/i8k`` or via the +``sysfs`` interface 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 known for +your laptop. 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/ + +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. 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) + +* power_status:bool + Report AC status in ``/proc/i8k``. (default: 0) + +* fan_mult:uint + Factor to multiply fan speed with. (default: + autodetect) + +* fan_max:uint + Maximum configurable fan speed. (default: + autodetect) 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