root/lm-sensors/branches/lm-sensors-2.10/doc/chips/bmcsensors

Kernel driver `bmcsensors.o'
==========================

Status: Alpha

Supported chips:
  * IPMI BMC
    Prefix: 'bmc'
        Requires dummy adapter i2c-ipmi;
        Driver will be registered as bmc-ipmi-0000.

Author: M. Studebaker <mdsxyz123@yahoo.com>

License: GPL


Module Parameters
-----------------

None.


Detection
---------

Registers only with i2c-ipmi.


Description
-----------

Together with the i2c-ipmi module, this provides high-level
access to sensors known by the BMC. For low-level access to
IPMB (I2C/SMBus) busses behind the BMC, use the i2c-ipmb module
and individual chip drivers.

This module REQUIRES the IPMI kernel patch by Corey Minyard,
v13 or higher, available at http://openipmi.sourceforge.net .
Other IPMI drivers are not supported.

See http://www.intel.com/design/servers/ipmi/ for
IPMI standards information.

You must configure the following features in your kernel
(under Character Devices):
        IPMI top-level message handler
        IPMI KCS handler
The IPMI device interface and IPMI watchdog handler are not required.

You must modprobe i2c-ipmi separately, it will not
load automatically when you modprobe bmcsensors.

If the KCS handler (ipmi_kcs_drv) is configured as a module,
you must also modprobe it separately, it will not load automatically
when you modprobe i2c-ipmi or ipmi_msghandler (unless you set up
/etc/modules.conf to load ipmi_kcs_drv when ipmi_msghandler is loaded).


/proc entries
-------------

The BMC SDR's (Sensor Data Records) are scanned and
the /proc table is built dynamically. Sensor types and quantities
depend on what the BMC supports.

        curr1-n         Currents. Max, min, and reading in amps.
        fan1-n          Fan speeds. Min and reading in RPM.
        in1-n           Voltages. Max, min, and reading in volts.
        temp1-n         Temps. Max, hysteresis or min, and reading in degrees C.
        
Thresholds will appear as 0 if unsupported or unreadable, as indicated
in the SDR.

If the thresholds are not settable (as indicated in the SDR), the
/proc permissions for that sensor will be 444.

After the SDR's are scanned, the module will print
the sensor names and bindings to syslog/dmesg.
Cut these messages out and paste them to /etc/sensors.conf
so that 'sensors' has correct labeling.


Issues
------
The module will not register in /proc/sys/dev/sensors until
the SDR's are scanned. This may take several seconds.

The driver uses a very simple state machine. It only sends
one message at a time and then waits for a response.
This makes the driver relatively slow.
If a response is an error or does not arrive, the driver
will probably be stuck.

/proc access kicks off an update but returns the old data,
not the new; need to wait for update to finish and then return.

Probably there are some locking issues.

Every attempt is made to present the sensor data in /proc in a
manner consistent with lm_sensors /proc standards, as defined
in doc/developers/proc. Given the wide variation in possible SDR definitions,
this may not generate expected or useful data.

IPMI supports up to 4 max and 4 min thresholds (non-recoverable, critical,
non-critical, and hysteresis) for each sensor. This driver
tries to pick out the best one and exports it as the max and min
to /proc.

ins start at 1, other modules start at in0.

Alarms and thresholds are not yet supported.

Threshold-only sensors are not supported.

Threshold setting is not yet supported.

1's and 2's complement formats not yet supported.

Non-linear conversions not supported, except for 1/x.

Fan divs are not supported (or required) - should the driver
export a fan_div entry (1 1 1 ...) for compatibility?

Supports only sensor types 1-4 (temp, voltage, current, and fan).

Libsensors can't handle dynamic /proc entries so the table
in lib/chips.c must be static and contain the max number of
each sensor. Bmcsensors can register more of a sensor type
than libsensors supports in its static table.

Only one BMC is supported - shouldn't be a problem.

Alpha!




**********************
The lm_sensors project gratefully acknowledges the support of
Hewlett Packard (Ft. Collins) in the development of this driver.