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