Rewrite lm-sensors installation and usage guidelines
and mark the list of third-party utilities as outdated.
Fix minor issues (typos, grammar, etc.) and add markup.
Signed-off-by: James Seo <[email protected]>
---
Documentation/hwmon/userspace-tools.rst | 129 +++++++++++++++++++-----
1 file changed, 103 insertions(+), 26 deletions(-)
diff --git a/Documentation/hwmon/userspace-tools.rst b/Documentation/hwmon/userspace-tools.rst
index bf3797c8e734..79c932954e4a 100644
--- a/Documentation/hwmon/userspace-tools.rst
+++ b/Documentation/hwmon/userspace-tools.rst
@@ -1,43 +1,120 @@
+===============
Userspace tools
===============
+.. contents::
+
Introduction
+============
+
+Hardware monitoring information is pertinent to almost every Linux system.
+For instance, most computer mainboards manufactured since the late 1990s have
+reported system health data such as temperatures, voltages, and fan speeds.
+All modern CPUs, GPUs, and SoCs have built-in internal temperature sensors and
+often have other types of sensors as well. In addition, an increasing number
+of components, such as power supplies and liquid CPU coolers, are now embedded
+systems ("smart devices") capable of measuring and providing relevant sensor
+data themselves.
+
+The Linux Hardware Monitoring subsystem (``hwmon``) supports most common types
+of hardware monitoring sensors, regardless of how they are connected to the
+system. Sensor measurements are made available in the ``/sys`` virtual
+filesystem at ``/sys/class/hwmon``. Userspace tools are then used to display
+the measured values or configure the sensors and data sources in a more
+friendly manner.
+
+``lm-sensors``
+==============
+
+``lm-sensors`` is a collection of command-line utilities that allows you to
+view hardware monitoring information and set monitoring limits. On some
+systems, it is used to process raw sensor data into a usable form. It may also
+be used to probe the system at a low level to help detect available sensors.
+
+While active development has largely ceased as of 2023, its status is closer
+to "finished" than "abandoned". It has strong historical ties to ``hwmon``,
+and a properly configured installation of ``lm-sensors`` (or its
+``libsensors`` library component) is often required by other hardware
+monitoring utilities.
+
+Installation
------------
-Most mainboards have sensor chips to monitor system health (like temperatures,
-voltages, fans speed). They are often connected through an I2C bus, but some
-are also connected directly through the ISA bus.
+Most Linux distributions provide the ``lm-sensors`` suite as a package.
+It is recommended that you use this package for ease of installation.
+Please consult your Linux distribution's documentation for more information.
+
+If needed, sources may be found at https://hwmon.wiki.kernel.org/lm_sensors.
+Basic compilation, installation, and uninstallation may be accomplished with
+``make all``, ``make install``, and ``make uninstall``, respectively.
+
+Usage
+-----
+
+General hints to get things working after installation:
-The kernel drivers make the data from the sensor chips available in the /sys
-virtual filesystem. Userspace tools are then used to display the measured
-values or configure the chips in a more friendly manner.
+* Run the ``sensors`` command. Note the available sensors on your system.
-Lm-sensors
-----------
+* If you don't see the sensors you expect, here are a few possibilities:
-Core set of utilities that will allow you to obtain health information,
-setup monitoring limits etc. You can get them on their homepage
-http://www.lm-sensors.org/ or as a package from your Linux distribution.
+ * You must run the ``sensors-detect`` command to detect available sensors.
+ It will try to find the correct kernel modules (i.e. ``hwmon`` drivers)
+ for your hardware and make the necessary changes to load them
+ automatically. You may have to make these changes yourself in some cases.
-If from website:
-Get lm-sensors from project web site. Please note, you need only userspace
-part, so compile with "make user" and install with "make user_install".
+ .. attention::
+ Though unlikely, ``sensors-detect`` may damage your system while
+ conducting certain low-level checks. You will have the chance to refuse.
-General hints to get things working:
+ * You are missing the kernel module(s) you need, but it is just a matter of
+ installing it.
-0) get lm-sensors userspace utils
-1) compile all drivers in I2C and Hardware Monitoring sections as modules
- in your kernel
-2) run sensors-detect script, it will tell you what modules you need to load.
-3) load them and run "sensors" command, you should see some results.
-4) fix sensors.conf, labels, limits, fan divisors
-5) if any more problems consult FAQ, or documentation
+ Some Linux distributions already include all in-kernel ``hwmon`` drivers
+ as part of a base installation, but others may only provide them in a
+ "kernel modules" or "extra kernel modules" package. Please consult your
+ Linux distribution's documentation for more information.
+
+ If you are using a self-compiled kernel, ensure that the necessary driver
+ is set to be compiled as modules in the kernel config, then recompile and
+ reinstall.
+
+ In some cases, a hardware vendor or an open-source developer provides an
+ unofficial third-party driver for your hardware. Please refer to the
+ documentation for that driver for more information.
+
+ * The module that you need exists and has been updated to work with your
+ hardware, but only for a later kernel version, or it has not been updated
+ yet, or it does not exist.
+
+ Unfortunately, you will need to upgrade your kernel or Linux distribution,
+ or wait and do so later, or implement support for your hardware yourself.
+
+* Once ``sensors`` is working, you may still need to edit its configuration
+ file (most likely ``/etc/sensors3.conf``) before its output becomes usable.
+
+ For example, this is necessary if several mainboards use the same sensor
+ chip for hardware monitoring duties, but due to design differences between
+ boards, the same measured value means different things on each.
+
+ You may also want to edit the config file to change sensor names, change how
+ displayed values are calculated, and/or hide sensors from view.
+
+ For more information, please refer to the ``man`` pages for ``sensors`` and
+ ``sensors.conf``.
+
+* If you run into more problems, consult FAQs and documentation as needed, or
+ try searching for your particular mainboard or computer system to see what
+ has worked for others.
Other utilities
----------------
+===============
+
+.. warning ::
+ This section is outdated and in need of attention. Please use this
+ information with caution, and please consider sending patches to update it.
If you want some graphical indicators of system health look for applications
-like: gkrellm, ksensors, xsensors, wmtemp, wmsensors, wmgtemp, ksysguardd,
-hardware-monitor
+like: ``gkrellm``, ``ksensors``, ``xsensors``, ``wmtemp``, ``wmsensors``,
+``wmgtemp``, ``ksysguardd``, ``hardware-monitor``
-If you are server administrator you can try snmpd or mrtgutils.
+If you are server administrator you can try ``snmpd`` or ``mrtgutils``.
--
2.34.1
On Thu, May 04, 2023 at 12:57:49AM -0700, James Seo wrote:
> +If needed, sources may be found at https://hwmon.wiki.kernel.org/lm_sensors.
> +Basic compilation, installation, and uninstallation may be accomplished with
> +``make all``, ``make install``, and ``make uninstall``, respectively.
> +
The sources is on GitHub:
---- >8 ----
diff --git a/Documentation/hwmon/userspace-tools.rst b/Documentation/hwmon/userspace-tools.rst
index 79c932954e4af5..fd96ea92f72eea 100644
--- a/Documentation/hwmon/userspace-tools.rst
+++ b/Documentation/hwmon/userspace-tools.rst
@@ -44,9 +44,9 @@ Most Linux distributions provide the ``lm-sensors`` suite as a package.
It is recommended that you use this package for ease of installation.
Please consult your Linux distribution's documentation for more information.
-If needed, sources may be found at https://hwmon.wiki.kernel.org/lm_sensors.
-Basic compilation, installation, and uninstallation may be accomplished with
-``make all``, ``make install``, and ``make uninstall``, respectively.
+If the distribution package isn't available, sources can be obtained at
+`GitHub <https://github.com/lm-sensors/lm-sensors>`_.
+See ``INSTALL`` in the sources for how to build the suite.
Usage
-----
Thanks.
--
An old man doll... just what I always wanted! - Clara
On Fri, May 05, 2023 at 12:03:29PM +0700, Bagas Sanjaya wrote:
> On Thu, May 04, 2023 at 12:57:49AM -0700, James Seo wrote:
> > +If needed, sources may be found at https://hwmon.wiki.kernel.org/lm_sensors.
> > +Basic compilation, installation, and uninstallation may be accomplished with
> > +``make all``, ``make install``, and ``make uninstall``, respectively.
> > +
>
> The sources is on GitHub:
>
> ---- >8 ----
> diff --git a/Documentation/hwmon/userspace-tools.rst b/Documentation/hwmon/userspace-tools.rst
> index 79c932954e4af5..fd96ea92f72eea 100644
> --- a/Documentation/hwmon/userspace-tools.rst
> +++ b/Documentation/hwmon/userspace-tools.rst
> @@ -44,9 +44,9 @@ Most Linux distributions provide the ``lm-sensors`` suite as a package.
> It is recommended that you use this package for ease of installation.
> Please consult your Linux distribution's documentation for more information.
>
> -If needed, sources may be found at https://hwmon.wiki.kernel.org/lm_sensors.
> -Basic compilation, installation, and uninstallation may be accomplished with
> -``make all``, ``make install``, and ``make uninstall``, respectively.
> +If the distribution package isn't available, sources can be obtained at
> +`GitHub <https://github.com/lm-sensors/lm-sensors>`_.
> +See ``INSTALL`` in the sources for how to build the suite.
>
> Usage
> -----
>
> Thanks.
>
> --
> An old man doll... just what I always wanted! - Clara
The document previously mentioned the old official lm-sensors site,
so I thought I should mention the current one, which has a GitHub link
anyway. But I will change this and add a link to the current site
separately.
Thanks.
James
On 5/5/23 08:12, James Seo wrote:
> On Fri, May 05, 2023 at 12:03:29PM +0700, Bagas Sanjaya wrote:
>> On Thu, May 04, 2023 at 12:57:49AM -0700, James Seo wrote:
>>> +If needed, sources may be found at https://hwmon.wiki.kernel.org/lm_sensors.
>>> +Basic compilation, installation, and uninstallation may be accomplished with
>>> +``make all``, ``make install``, and ``make uninstall``, respectively.
>>> +
>>
>> The sources is on GitHub:
>>
Above page has a "Download" link which points to the github repository.
Personally I think it is better to have a reference to a more generic
location such as to kernel.org in the kenrel and point to the
actual repository (which is more likely to change, after all)
from there.
Guenter
>> ---- >8 ----
>> diff --git a/Documentation/hwmon/userspace-tools.rst b/Documentation/hwmon/userspace-tools.rst
>> index 79c932954e4af5..fd96ea92f72eea 100644
>> --- a/Documentation/hwmon/userspace-tools.rst
>> +++ b/Documentation/hwmon/userspace-tools.rst
>> @@ -44,9 +44,9 @@ Most Linux distributions provide the ``lm-sensors`` suite as a package.
>> It is recommended that you use this package for ease of installation.
>> Please consult your Linux distribution's documentation for more information.
>>
>> -If needed, sources may be found at https://hwmon.wiki.kernel.org/lm_sensors.
>> -Basic compilation, installation, and uninstallation may be accomplished with
>> -``make all``, ``make install``, and ``make uninstall``, respectively.
>> +If the distribution package isn't available, sources can be obtained at
>> +`GitHub <https://github.com/lm-sensors/lm-sensors>`_.
>> +See ``INSTALL`` in the sources for how to build the suite.
>>
>> Usage
>> -----
>>
>> Thanks.
>>
>> --
>> An old man doll... just what I always wanted! - Clara
>
> The document previously mentioned the old official lm-sensors site,
> so I thought I should mention the current one, which has a GitHub link
> anyway. But I will change this and add a link to the current site
> separately.
>
> Thanks.
>
> James