*********************************************************
    Mother Board Monitor Program for X Window System

        XMBmon ver.1.06pl1

    for FreeBSD (and possibly Linux, but not checked).
 *********************************************************


<< 1. What's this software >>

  Recently there are a lot of mother boards available, which have
functionalities to monitor the CPU temperatures and the frequency
of CPU cooling fans etc.  Although some programs utilizing these
hardware monitoring facilities have been developed for the
Microsoft Windows platforms, no program seems to exist for PC-UNIX
and the X Windows System platforms.  Therefore, I have tried to
make small programs.  They have only least functionalities,
the one used at the command line reports the temperatures,
voltages and rpm (rounds per minute) of cooling fans, and the
other displays the temperatures and voltage as simple curves.


<< 2. Changes in the new version >>

 * The built-in hardware monitor chip in the VIA south chipset,
  VT82C686A/B, which is used for many Athlon mother boards,
  is supported.

 * The functions to directly perform input/output through SMBus
  are implemented.  Therefore, the programs work even if there
  is no power management device driver, like "intpm" driver for
  Intel PIIX4 (440BX chipset), in the FreeBSD system.

 * Automatic distinction of supported hardware monitor chips
  (this is not complete, though).

((NOTICE)) If the previous version (ver.1.05) is working fine,
   then you need not use this new version.  Functionality of
   the programs are exactly the same.


<< 3. Supported hardware monitor chips >>

  The following hardware monitor chips are supported and the
programs most possibly work if your mother board uses one of them.

   National Semiconductor co.  LM78/LM79
   WinBond co.                 W83781D, W83782D, W83783S
   ASUSTek co.                 AS99127F
   VIA co. south chipset       VT82C686A/B built-in

If your mother board uses other chips and they are compatible to
one of the above, then there is still a possibility.


<< 4. How to use >>

  By using "./configure" and "make" under the directory where this
package is unpacked, two binary programs

      mbmon      Mother Board Monitor for tty-terminal
      xmbmon     Mother Board Monitor for X

will be generated.

((NOTICE)) These programs access SMBus or ISA-IO port without
   any kind of checking.  It is, therefore, very dangerous and
   may cause system-crash in worst cases.  Especially, accesses of
   IO port 0x295, 0x296 may conflict NE2000 boards' IO ports.
   Users are requested to be sure that access to those ports are
   allowed.  I do not take any responsibilities for problems caused
   by using these programs.

  If you succeed compiling the programs, then it is better first 
to check they will work on your mother board.  Switch to the root
user, and execute "mbmon" like this,

   # ./mbmon -d

in the debug mode.  If you do NOT get the following error message,

   No Hardware Monitor found!!
   InitMBInfo: Undefined error: 0

but it displays information of the detected hardware monitor chip,
then the programs will most probable work.  Try to execute "mbmon"
now without "-d" option, and if the following output

   Temp.= 34.2, 57.0, 48.0; Rot.= 4623, 4420, 2060
    Vcore = 1.86, 3.54; Volt. = 3.54, 4.93, 12.13, -11.98, -5.01

comes every five seconds, congratulation!  The programs are working
on your system.  Just stop it by typing "^C" (CTRL-C), and install
these two programs (Only ^C can stop "mbmon").  Note that both
programs access SMBus or ISA-IO port so that they should sit in a
directory in the PATH variable with the "setuid root" permission.
An example of installation is written in Makefile.  If you put
"mbmon" in /usr/local/bin and "xmbmon" in /usr/X11R6/bin, then
just type

   # make install

and then they are installed properly.

  As I said, the programs access IO port directly, so even if
the program has a "setuid root" permission, they won't work on the
system where this IO port access is prohibited.  If the following
message,

   InitMBInfo: Operation not permitted
   This program needs "setuid root"!!

comes on FreeBSD, the system security level is too strict and
IO port access is not allowed (see kern_securelevel_enable,
kern_securelevel in /etc/rc.conf).  Make your security level lower,
or just give up to use the programs.

  As for the Linux platforms,  add -DLINUX option to the DEFS
variable in Makefile and compile.  I do not check that the programs
work at Linux platforms because I do not have Linux machines
available around me.  Maybe they will work or won't (if the ISA-IO
port access method works, they possibly will, since the previous
version 1.05 worked).


<< 5. A bit of more details >>

  This software are programmed mainly to use Winbond W86781D chip
as a hardware monitor chip of mother board.  This chip can handle
three temperatures (Temp0, Temp1, Temp2), seven voltages (V0 - V6),
and three FAN rotational speeds (Fan0, Fan1, Fan2).  The program,
"mbmon", shows all the information in text on tty's, and "xmbmon"
shows Temp0,1,2 and V0(Vcore) in graphic on X.  The units are degree in
centigrade (C) for temperatures, Volt (V) for voltages, and rotations
per minute (rpm) for Fan rotation speeds.  Other chips may not
support all of them.  For example, VIA's VI82C686 will report on
two temperatures, five voltages, and two fan speeds.  The items
which are not supported by chip are displayed by "0.0" or "0"
in the "mbmon" output.  The program "mbmon" can take a input of
interval (in seconds, default value is 5 seconds) for showing the
output monitor information:

   Usage: mbmon -[V|S|I] [-d (debug)]  (default 5 sec)

  In the case of "xmbmon", Temp0,1,2 are depicted with legends
"MB", "CPU", "chip", respectively.  They are X resources and can be
freely changed (see the included file, xmbmon.resources).  If these
legends are not appropriate for your mother board, please change them.
If you have no third temperature (Temp2) and/or your third temperature
is connected to nowhere, it may be better not to show the third
temperature itself.  In such a case, please add -DNO_TEMP3 option
to the DEFS variable in Makefile and recompile the programs.

  If you do not know what kind of hardware monitor chips your mother
board has, then by using the following "debug" option

   # mbmon -d
   # xmbmon -debug

information of the monitor chip would be detected.  You can judge,
more or less, whether these programs can run on your machine.
Among the supported hardware monitor chips, LM78/79 has only Temp0
(measuring the temperature of mother board), and W83783S does not
support Temp2.  Some mother board may not use all Temp0/1/2
functionalities even though the monitor chip has all.  Usually,
Temp0 is for measuring mother board's temperature, which is about
the room temperature and does not change.  Temp1,2 are only effective
when they are connected to external sensor chips explicitly in most
cases.  But in recent mother boards (like ASUS P3B-F) Temp1 is often
connected to the inner sensor of Pentium II/III CPU by default.
The mother boards I have tried to run the programs and the results
of run with the "debug" option are collected in the file DEBUG_info.

  Generally, recent mother boards provide two access methods to the
hardware monitor chip, namely those using the SMBus (System Management
Bus) and the old fashioned ISA-IO port.  New chips (like AS99127F
on ASUS P3B-F mother board) would only allow the SMBus access method.
The programs in the previous version (ver.1.05) access to this SMBus
through the power management device driver "intpm", which was
supported after FreeBSD 3.3R.  But this "intpm" driver is only for
the Intel 440BX south chipset PIIX4, and cannot be used for other
chipsets like VIA's ones, which are widely used for Athlon mother
boards[Note1].  In this new version, I have included new functions
in order to access the SMBus directly without any help of device
drivers supported by OS (FreeBSD).  Therefore, the programs DO
direct IO port access, if used the default compiling options, and
so they are "dangerous" programs.  However, if the proper device
driver, like the "intpm" driver, is available, the SMBus access
method by the ioctl function call, which is the defaults method
in the previous version (ver.1.05), can be used.  In order for this
possible, you have to add compiling option -DSMBUS_IOCTL to the
DEFS macro variable in the Makefile.  Then, if the "./configure"
process finds /dev/smb0, this safer access method (SMBus ioctl call)
is used in place of the newly implemented direct SMBus access
routines.

  The built-in hardware monitor in the VIA's south chipset
VT82C686A/B has an another access method to the chip, by using
a different ISA-IO port access from that of Winbond chips.
Thus, including this for VT82C686A/B, there are three methods to
talk to the supported hardware monitor chips.  I call this specific
method for the VIA's chip, method V, more general method using
SMBus, method S, and the old fashioned ISA-IO port method for the
LM78/79 or Winbond chips, method I.  One can impose the programs
to use one of these three methods by giving a method option;

   # mbmon -[V|S|I]
   # xmbmon -method [V|S|I]

for method, V, S, I, respectively.  To check your mother board
supports which access method, you just try to execute programs with
this and the debug option (-d).  If this method option is not put,
the programs try to check method V, S, I in this order, and
automatically choose the access method.  There are many more options
for "xmbmon", which will be denoted by execute it with a help option
(-h or -help).  They are explained in details in the place of
explanation of X resources.

  I have developed the programs in the environment of FreeBSD 3.5-
STABLE, but I have checked that they work on OS version 4.X.  As for
the Linux platform, I have checked that the program can be compiled
in the environment of "linux_devtools-6.1" of the FreeBSD ports.
I have asked someone to try the programs on some Linux platform,
and found they may work.  But, in any case, I can not guarantee
because I did not check them by myself.

  [Note1] Recently, power management device driver for the VIA's
   VT82C596/VT82C686 south chipset ("viapm" driver) has been
   developed.  Recent OS version (version 4.X? or 5.X?) of FreeBSD
   systems may be possible to include it.  Then, the safer SMBus ioctl
   access method may be used.  Just try to compile with compiling
   option "-DSMBUS_IOCTL", then.  A recent information on the "viapm"
   driver can be checked at

   http://people.freebsd.org/~nsouch/iicbus.html
   http://www.planet.kobe-u.ac.jp/~takawata/acpi/


<< 6. On X resources of "xmbmon" >>

  "xmbmon" is programmed with the X toolkit, and the standard X
resources (like geometry, font) can be used.  Other "xmbmon" specific
resources are the following:

XMBmon*count:   counts to check temp. etc in "sec" below (default:4)
XMBmon*sec:     period in seconds for plot one point (default:20)
XMBmon*wsec:    total period in seconds for window width (default:1800)
XMBmon*tmin:    lowest scale of temperature in degree C (default:10.0)
XMBmon*tmax:    highest scale of temperature in degree C (default:50.0)
XMBmon*vmin:    lowest scale of V-core voltage in V (default:1.80)
XMBmon*vmax:    highest scale of V-core voltage in V (default:2.20)
XMBmon*tick:    number of ticks for temp. and V-core (default:3)
XMBmon*cltmb:   color for plotting Temp0 (default:blue)
XMBmon*cltcpu:  color for plotting Temp1 (default:red)
XMBmon*cltcs:   color for plotting Temp2 (default:cyan)
XMBmon*clvc:    color for plotting Vcore (default:green)
XMBmon*cmtmb:   legend of Temp0 (default:\ MB)
XMBmon*cmtcpu:  legend of Temp1 (default:CPU)
XMBmon*cmtcs:   legend of Temp2 (default:chip)
XMBmon*cmvc:    legend of Vcore (default:Vc\ )
XMBmon*method:  access method (default:\ )

  The default behavior is that every 20(sec)/4(count)=5 seconds, the
timer interrupt occurs and then hardware monitor information is read.
The average value of four times' read-in is displayed as a colored
curve.  The width of the "xmbmon" window corresponds to 1800(wsec)
seconds, i.e. 30 minutes.  If time passes old plot data disappears
and renew the display (just like the "xload" program).  The resources
above can be specified as options with the same name at the execution
time.  The help option (-h or -help) shows these options like this:

   # xmbmon -help
X MotherBoard Monitor, ver.1.06pl1 by YRS
  options: -g   (100x140)  <geometry(Toolkit option)>
         : -count     (4)  <counts in an interval>
         : -sec      (20)  <seconds of an interval>
         : -wsec   (1800)  <total seconds shown>
         : -tmin   (10.0)  <min. temperature>
         : -tmax   (50.0)  <max. temperature>
         : -vmin   (1.80)  <min. voltage>
         : -vmax   (2.20)  <max. voltage>
         : -tick      (3)  <ticks in ordinate>
         : -cltmb  (blue)  <Temp1 color>
         : -cltcpu  (red)  <Temp2 color>
         : -cltcs  (cyan)  <Temp3 color>
         : -clvc  (green)  <Vcore color>
         : -cmtmb   ( MB)  <comment of Temp1>
         : -cmtcpu  (CPU)  <comment of Temp2>
         : -cmtcs  (chip)  <comment of Temp3>
         : -cmvc    (Vc )  <comment of Vcore>
         : -debug           for debug information
         : -method  (   )  <access method (V|S|I)>

  The "xmbmon" made with -DNO_TEMP3 compiling option does not use
the X resources, cltcs and cmtcs.


<< 7. Bugs >>

  A serious bug of version 1.06, xmbmon goes out of control while 
other processes keep opening /dev/io device file, is fixed by
version pl1 (patch level 1).  I hope there are no more serious
bugs (but maybe there are!).


<< 8. Those who want to support other hardware monitor chips >>

  One nice point of this new version is that own SMBus access
functions are implemented.  This means that one can access any
hardware monitor chips connected to the SMBus without the help
of any OS device drivers.  So, if one wishes, one can search the
monitor chips, which is connected to the SMBus power management
hardware, from the PCI device configuration.  If one can find
how to control the chip, then other hardware monitor chips rather
than those supported in this version of "mbmon/xmbmon", i.e.,

   National Semiconductor co.  LM78/LM79
   WinBond co.                 W83781D, W83782D, W83783S
   ASUSTek co.                 AS99127F
   VIA co. south chipset       VT82C686A/B built-in

would be possible to be supported by himself.  For this purpose,
a test program for checking the PCI Configuration is prepared as
testpci.c, for checking the SMBus power management as testsmb.c,
and for checking Winbond-like hardware monitor facilities as
testhwm.c; all these programs are included in this package.
Functions for getting information of the PCI Configuration is
collected in pci_hwm.c/h, and for the direct SMBus IO access, they
are in smb_io.c/h.  For those who want to support other hardware
monitor chips, I encourage them by providing these small tools.
But don't forget to prepare unexpected problems like OS crash,
because these tools are more dangerous than "mbmon/xmbmon"
themselves!

  One may be interested in which mother board uses what kind of
hardware monitor chips.  Such information is available at the
homepage of Alex van Kaam, who is a developer of a famous MBM
(Mother Board Monitor) program on Microsoft Windows platforms,

   http://mbm.livewiredev.com/

Or, in Japan, there is a useful information posted in the mailing-
list run by :p araffin.(Yoneya), who is a developer of other
famous monitoring software LM78mon on Windows platforms,

   http://homepage1.nifty.com/paraffin/

The technical information for Winbond chips are available as PDF
files at

   http://www.winbond.com.tw/sheet/w83781d.pdf
   http://www.winbond.com.tw/sheet/w83782d.pdf
   http://www.winbond.com.tw/sheet/w83783s.pdf

And there are many technical informations in the PDF forms are
collected at the hardware monitor homepage for Linux at

    http://www.netroedge.com/~lm78/pdfs.html

But the information on particular hardware monitor chip may not be
necessarily available, then it is very difficult to support such
a chip.

  [Note2] SMBus (System Management Bus) is one of general purpose
   bus connected on PCI bus, and the Power Management facilities,
   like ACPI, is installed on this bus architecture.  Usually,
   hardware monitor chips are connected on this.  Thus, if one
   wants to access the monitoring chip through SMBus, the following
   two steps are necessary: (1) check the power management chip
   (e.g. Intel PIIX4(440BX)), (2) find out which hardware monitoring
   chip (e.g. AUS AS99127F) is connected to it.  Here, VT82C686A/B
   chip contains hardware monitoring facility built-in in the south
   chipset itself.


<< 9. Acknowledgemen9ts >>

 * The first version opened to the public is ver.1.04, which only
  supports ISA-IO port access method for Winbond chips.  The actual
  access method to the chip was opened in the homepage of MBM by
  Alex van Kaam mentioned above (unfortunately, the information is
  not opened now).  If I cannot find this information the programs
  "mbmon/xmbmon" would not appear.  I appreciate that he opened
  this valuable information (which is now available at the Winbond
  homepage now, as shown above).

 * For the next version 1.05, I got a great help by Takanori Watanabe
 at Kobe University, who is a developer of "intpm" driver and
 contributed a lot to support the SMBus ioctl access method.  I have
 introduced other direct SMBus access method in this version, the
 SMBus ioctl method is still useful and even safer if there is a
 proper support of OS device drivers (like "intpm" or "viapm").  The
 separation of code for each access method is provided by him, and
 it is a great help for developing this new version.  I appreciate
 his help.  The (partial) support for Linux has been done from
 ver.1.05 with the help of Koji Okamoto at Kyushu University.  The
 information of ASUS AS99127F hardware monitor chip supported from
 ver.1.05 was provided by Noriyuki Yoneya (:p araffin.).  I also
 appreciate their help.

 * In this new version, I wanted to use "mbmon/xmbmon" for the Athlon
 machines, the number of which are increasing around me because of
 it's fast numeric computing ability.  Here all the Athlon machines
 I can use employ VIA's VT82C686A/B chipset, and it's information
 as a hardware monitor chip is not opened yet.  I got the information
 from, again, Noriyuki Yoneya (:p araffin.).  Furthermore, I found
 that the ASUS mother board uses their own monitor chip AS99127F,
 even though it employs VT82C686 south chipset.  Then, (since I cannot
 use "viapm" device driver on my old FreeBSD-3.X system) I need to
 access the SMBus directly without any OS device driver.  For this
 purpose, detailed technical information on the method for getting
 the PCI device configurations, and further, for accessing the SMBus
 directly, are totally provided by Noriyuki Yoneya (:p araffin.).
 Without his help, this new version cannot emerge in the present form.
 I very much appreciate his generosity of helping me on this matter.


<< 10. Finally >>

  The programs are completely free software.   Any modifications and
changes to the programs are welcome, and they are freely copied and
distributed.  The author is not at all responsible if anyone have
any problems or damages when using the programs.  The author won't
keep the development of the programs any further, at least now.  But
if someone develops any new better programs based on my own, I am
very glad if feedback is made to me (of course, it is not at all
the duties!).

   August 25, 2001       Yoshifumi R. Shimizu,
                         Department of Fundamental Physics,
                         Kyushu University

   e-mail : yrsh2scp@mbox.nc.kyushu-u.ac.jp
   http://www.nt.phys.kyushu-u.ac.jp/shimizu/index.html