bsdhwmon.8

.\"
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
.\"
.Dd January 15, 2024
.Dt BSDHWMON 8
.Sh NAME
.Nm bsdhwmon
.Nd hardware sensor monitoring utility
.Sh SYNOPSIS
.Nm
.Op Fl Jchlv
.Op Fl f Ar device
.Sh DESCRIPTION
.Nm
is a user-land application which communicates via SMBus with hardware
monitoring ICs on motherboards.  Many different pieces of information
can be returned, but the most common are fan RPMs, processor and system
temperatures, and motherboard voltages.  All data is sent to standard
output.  Usage syntax and all errors are sent to standard error.
.Pp
The options are as follows:
.Pp
.Bl -tag -width indent
.It Fl J
Output data in a JSON-compliant format.
.It Fl c
Output data in a comma-delimited format.  Sensor name, its value, and
the associated unit (V for volts, C for Celsius, RPM for rotations per
minute, etc.) are individual parameters.
.It Fl f Ar device
Specify an alternate SMBus device.  Default is
.Pa /dev/smb0 .
.It Fl l
List motherboards supported by
.Nm .
.It Fl h
Help or usage syntax.
.It Fl v
Increase verbosity (includes debugging output).
.El
.Sh REQUIREMENTS
.Nm
requires a few hardware and software features to function:
.Bl -enum
.It
A hardware monitoring chipset that "ties" into SMBus.  This is
somewhat common on server-class motherboards, but greatly varies
per manufacturer.  Presently
.Nm
supports a multitude of Winbond (Nuvoton) hardware monitoring ICs,
predominantly on Supermicro motherboards.  If you're unsure your
motherboard is supported, running
.Nm
with the
.Fl l
option will display a list of supported motherboards.  You may also
wish to consult your user manual or contact the technical support
department for your product.
.It
A system BIOS that provides a SMBIOS table.  Specifically, the
existence of the
.Cd smbios.planar.maker
and
.Cd smbios.planar.product
.Xr kenv 2
kernel environment strings.  You can verify the existence of these
variables by using
.Xr kenv 1 .
This is needed for
.Nm
to reliably auto-detect your motherboard.
.It
.Cd "device smb"
built into your kernel or loaded using
.Xr kldload 8 ,
.It
.Cd "device smbus"
built into your kernel or loaded using
.Xr kldload 8 ,
.It
An appropriate SMBus chipset driver, such as
.Xr amdsmb 4 ,
.Xr ichsmb 4 ,
or
.Xr nfsmb 4 ,
built into your kernel or loaded via
.Xr kldload 8 .
.El
.Pp
Failure to meet all of the above requirements will result in
.Nm
not functioning.
.Sh OUTPUT
If
.Nm
emits a message indicating your motherboard is unsupported, please
follow the on-screen instructions.
.Pp
.Nm
attempts to mimic output formatting and sensor strings to that of
the BIOS's Hardware Monitoring menu option (if available).  However,
due to limited hardware availability and user beta testing, some
strings may not match the BIOS exactly (such as "PECI Agent" being
replaced with "CPU Core").  For example, a Supermicro PDSMi+
motherboard would output something resembling this:
.Pp
.Bd -literal -offset indent
CPU Temperature            34 C
System Temperature         36 C
FAN1                        0 RPM
FAN2                        0 RPM
FAN3                        0 RPM
FAN4                     2000 RPM
FAN5                     1527 RPM
FAN6                     1785 RPM
Vcore                   1.198 V
+1.5V                   1.540 V
-12V                  -12.288 V
Vdimm                   1.824 V
+3.3V                   3.344 V
+12V                   12.000 V
5Vsb                    5.046 V
5VDD                    4.974 V
P_VTT                   1.206 V
Vbat                    3.184 V
.Ed
.Pp
While an older Supermicro P8SC8 might output this:
.Pp
.Bd -literal -offset indent
CPU Temperature            33 C
System Temperature         37 C
FAN1                     4963 RPM
FAN2                        0 RPM
FAN3                        0 RPM
FAN4                        0 RPM
FAN5                        0 RPM
Processor Vcore(V)      1.360 V
3.3V Vcc(V)             3.320 V
5V Vcc(V)               3.044 V
-12V Vcc(V)           -12.288 V
12V Vcc(V)             12.432 V
5VSB                    4.896 V
VBAT                    3.104 V
.Ed
.Pp
Slight differentials in sensor values (e.g. a few degrees, voltage
fluctuations, or RPM variance) are normal.  Operating systems often
make use of system and processor which may halt processors while idling
(e.g. x86 "HLT" opcode), or make use of C1 through C4 power-saving
states;
.Xr powerd 8
on FreeBSD is known to do this.  System BIOSes are known to offer the
ability to throttle fan speed based on load.  Please refer to your
System User Manual for details.
.Pp
Large/severe differences between what the system BIOS and
.Nm
reports should be reported as a bug (e.g. -12.107 V shown in the BIOS,
while
.Nm
reports +37.000 V).
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr kenv 1 ,
.Xr amdsmb 4 ,
.Xr ichsmb 4 ,
.Xr nfsmb 4 ,
.Xr smb 4 ,
.Xr smbus 4 ,
.Xr kldload 8
.Sh AUTHOR
.An Jeremy Chadwick Aq jdc@koitsu.org
.Sh BUGS
Some Supermicro systems using the Winbond W83792D chipset may report
incorrect +5V voltages; the Supermicro P8SC8 and P8SCT motherboards are
such examples.  This is caused by a faulty formula used to calculate voltages
from IC registers.  The formulas used are not officially documented, and the
actual circuitry (resistors, etc.) tied to the pins on the Winbond chip do
not match what Winbond used in their documentation.  Formula documentation
has been requested of Supermicro, but no response has been received at this
time.
.Pp
There has been an isolated report of a Supermicro P8SCi system occasionally
reporting extremely high RPMs (in the tens of thousands) for some fans.
The reason for this is unknown, but the values being returned from the
Winbond chipset do appear correct.  If you're experiencing this bug, please
get in contact with the author.  Git commit ad3bbad may have rectified this
bug.
.Pp
Please report all issues at https://github.com/koitsu/bsdhwmon/issues
.Sh CONTRIBUTORS
The following individuals have made contributions to
.Nm , either by helping with the code, testing the software, or recommending
features:
.Pp
Tony Allevato, Mike Andrews, Alan Bryan, Gergely Czuczy, Michael Fuckner,
M. Giegerich, Matthew Herzog, Dan Naumov, Billy Newsom, Daniel O'Connor,
Alexey V. Panfilov, Jim Perry, Jim Pingle, Patrick Proniewski, Matt Reimer,
Larry Rosenman, Ulrich Spoerlein, Evren Yurtesen
.Pp
Additional thanks to SHIMIZU Yoshifumi, author of mbmon, for providing BSD
hardware monitoring support on older x86 hardware, and to the Linux
lm_sensors project, for providing an unofficial secondary source of IC
documentation and details of chip quirks.