Documentation/hwmon/fscher

Kernel driver fscher
====================

Supported chips:
  * Fujitsu-Siemens Hermes chip
    Prefix: 'fscher'
    Addresses scanned: I2C 0x73

Authors:
        Reinhard Nissl <rnissl@gmx.de> based on work
        from Hermann Jung <hej@odn.de>,
        Frodo Looijaard <frodol@dds.nl>,
        Philip Edelbrock <phil@netroedge.com>

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

This driver implements support for the Fujitsu-Siemens Hermes chip. It is
described in the 'Register Set Specification BMC Hermes based Systemboard'
from Fujitsu-Siemens.

The Hermes chip implements a hardware-based system management, e.g. for
controlling fan speed and core voltage. There is also a watchdog counter on
the chip which can trigger an alarm and even shut the system down.

The chip provides three temperature values (CPU, motherboard and
auxiliary), three voltage values (+12V, +5V and battery) and three fans
(power supply, CPU and auxiliary).

Temperatures are measured in degrees Celsius. The resolution is 1 degree.

Fan rotation speeds are reported in RPM (rotations per minute). The value
can be divided by a programmable divider (1, 2 or 4) which is stored on
the chip.

Voltage sensors (also known as "in" sensors) report their values in volts.

All values are reported as final values from the driver. There is no need
for further calculations.


Detailed description
--------------------

Below you'll find a single line description of all the bit values. With
this information, you're able to decode e. g. alarms, wdog, etc. To make
use of the watchdog, you'll need to set the watchdog time and enable the
watchdog. After that it is necessary to restart the watchdog time within
the specified period of time, or a system reset will occur.

* revision
  READING & 0xff = 0x??: HERMES revision identification

* alarms
  READING & 0x80 = 0x80: CPU throttling active
  READING & 0x80 = 0x00: CPU running at full speed

  READING & 0x10 = 0x10: software event (see control:1)
  READING & 0x10 = 0x00: no software event

  READING & 0x08 = 0x08: watchdog event (see wdog:2)
  READING & 0x08 = 0x00: no watchdog event

  READING & 0x02 = 0x02: thermal event (see temp*:1)
  READING & 0x02 = 0x00: no thermal event

  READING & 0x01 = 0x01: fan event (see fan*:1)
  READING & 0x01 = 0x00: no fan event

  READING & 0x13 ! 0x00: ALERT LED is flashing

* control
  READING & 0x01 = 0x01: software event
  READING & 0x01 = 0x00: no software event

  WRITING & 0x01 = 0x01: set software event
  WRITING & 0x01 = 0x00: clear software event

* watchdog_control
  READING & 0x80 = 0x80: power off on watchdog event while thermal event
  READING & 0x80 = 0x00: watchdog power off disabled (just system reset enabled)

  READING & 0x40 = 0x40: watchdog timebase 60 seconds (see also wdog:1)
  READING & 0x40 = 0x00: watchdog timebase  2 seconds

  READING & 0x10 = 0x10: watchdog enabled
  READING & 0x10 = 0x00: watchdog disabled

  WRITING & 0x80 = 0x80: enable "power off on watchdog event while thermal event"
  WRITING & 0x80 = 0x00: disable "power off on watchdog event while thermal event"

  WRITING & 0x40 = 0x40: set watchdog timebase to 60 seconds
  WRITING & 0x40 = 0x00: set watchdog timebase to  2 seconds

  WRITING & 0x20 = 0x20: disable watchdog

  WRITING & 0x10 = 0x10: enable watchdog / restart watchdog time

* watchdog_state
  READING & 0x02 = 0x02: watchdog system reset occurred
  READING & 0x02 = 0x00: no watchdog system reset occurred

  WRITING & 0x02 = 0x02: clear watchdog event

* watchdog_preset
  READING & 0xff = 0x??: configured watch dog time in units (see wdog:3 0x40)

  WRITING & 0xff = 0x??: configure watch dog time in units

* in*     (0: +5V, 1: +12V, 2: onboard 3V battery)
  READING: actual voltage value

* temp*_status   (1: CPU sensor, 2: onboard sensor, 3: auxiliary sensor)
  READING & 0x02 = 0x02: thermal event (overtemperature)
  READING & 0x02 = 0x00: no thermal event

  READING & 0x01 = 0x01: sensor is working
  READING & 0x01 = 0x00: sensor is faulty

  WRITING & 0x02 = 0x02: clear thermal event

* temp*_input   (1: CPU sensor, 2: onboard sensor, 3: auxiliary sensor)
  READING: actual temperature value

* fan*_status   (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
  READING & 0x04 = 0x04: fan event (fan fault)
  READING & 0x04 = 0x00: no fan event

  WRITING & 0x04 = 0x04: clear fan event

* fan*_div (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
  	Divisors 2,4 and 8 are supported, both for reading and writing

* fan*_pwm   (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
  READING & 0xff = 0x00: fan may be switched off
  READING & 0xff = 0x01: fan must run at least at minimum speed (supply: 6V)
  READING & 0xff = 0xff: fan must run at maximum speed (supply: 12V)
  READING & 0xff = 0x??: fan must run at least at given speed (supply: 6V..12V)

  WRITING & 0xff = 0x00: fan may be switched off
  WRITING & 0xff = 0x01: fan must run at least at minimum speed (supply: 6V)
  WRITING & 0xff = 0xff: fan must run at maximum speed (supply: 12V)
  WRITING & 0xff = 0x??: fan must run at least at given speed (supply: 6V..12V)

* fan*_input   (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
  READING: actual RPM value


Limitations
-----------

* Measuring fan speed
It seems that the chip counts "ripples" (typical fans produce 2 ripples per
rotation while VERAX fans produce 18) in a 9-bit register. This register is
read out every second, then the ripple prescaler (2, 4 or 8) is applied and
the result is stored in the 8 bit output register. Due to the limitation of
the counting register to 9 bits, it is impossible to measure a VERAX fan
properly (even with a prescaler of 8). At its maximum speed of 3500 RPM the
fan produces 1080 ripples per second which causes the counting register to
overflow twice, leading to only 186 RPM.

* Measuring input voltages
in2 ("battery") reports the voltage of the onboard lithium battery and not
+3.3V from the power supply.

* Undocumented features
Fujitsu-Siemens Computers has not documented all features of the chip so
far. Their software, System Guard, shows that there are a still some
features which cannot be controlled by this implementation.