[RFC 08/11] Documentation/hwmon: Revise userspace tools documentation

[James Seo]

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 <james@xxxxxxxxxx>
---
 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