Kernel driver `fscher.o'
=======================

Status: Stable
   Tested with motherboard D1562
   
   Think twice before you're using the write mode of some
   variables, especially the watchdog
	

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

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

License: GPL


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

* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* force_fscher: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `fscher' chip
* probe: short array (min = 1, max = 48)
  List of adapter,address pairs to scan additionally
* probe_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples to scan additionally
* ignore: short array (min = 1, max = 48)
  List of adapter,address pairs not to scan
* ignore_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples not to scan


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.

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

* alarms:1
  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:1     
  READING & 0x01 = 0x01: software event
  READING & 0x01 = 0x00: no software event

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

* wdog:3
  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

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

  WRITING & 0x02 = 0x02: clear watchdog event 

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

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

* temp*:1   (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*:2   (1: CPU sensor, 2: onboard sensor, 3: auxiliary sensor) 
  READING: actual temperature value
  
* fan*:1   (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*:2   (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
  READING & 0x03 = 0x03: 8 ripples are one fan turn
  READING & 0x03 = 0x02: 4 ripples are one fan turn
  READING & 0x03 = 0x01: 2 ripples are one fan turn

  WRITING & 0x03 = 0x03: set prescaler to "8 ripples are one fan turn"
  WRITING & 0x03 = 0x02: set prescaler to "4 ripples are one fan turn"
  WRITING & 0x03 = 0x01: set prescaler to "2 ripples are one fan turn"

* fan*:3   (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*:4   (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 controled by this implementation.


Chip Features
-------------

Chip 'fscher'

LABEL                 LABEL CLASS           COMPUTE CLASS          MODE  MAGN
rev                   -                     -                       R-     0
alarms                -                     -                       R-     0
control               -                     -                       RW     0
in0                   -                     -                       R-     2
in1                   -                     -                       R-     2
in2                   -                     -                       R-     2
temp1                 -                     -                       R-     0
temp2                 -                     -                       R-     0
temp3                 -                     -                       R-     0
temp1_state           temp1                 temp1                   RW     0
temp2_state           temp2                 temp2                   RW     0
temp3_state           temp3                 temp3                   RW     0
fan1                  -                     -                       R-     0
fan2                  -                     -                       R-     0
fan3                  -                     -                       R-     0
fan1_min              fan1                  fan1                    RW     0
fan2_min              fan2                  fan2                    RW     0
fan3_min              fan3                  fan3                    RW     0
fan1_state            fan1                  fan1                    RW     0
fan2_state            fan2                  fan2                    RW     0
fan3_state            fan3                  fan3                    RW     0
fan1_ripple           fan1                  fan1                    RW     0
fan2_ripple           fan2                  fan2                    RW     0
fan3_ripple           fan3                  fan3                    RW     0
wdog_preset           -                     -                       RW     0
wdog_state            wdog_preset           wdog_preset             RW     0
wdog_control          wdog_preset           wdog_preset             RW     0
	
LABEL                 FEATURE SYMBOL                              SYSCTL FILE:N
rev                   SENSORS_FSCHER_REV                                  rev:1
alarms                SENSORS_FSCHER_EVENT                             alarms:1
control               SENSORS_FSCHER_CONTROL                          control:1
in0                   SENSORS_FSCHER_VOLTAGE1                             in0:1
in1                   SENSORS_FSCHER_VOLTAGE2                             in1:1
in2                   SENSORS_FSCHER_VOLTAGE3                             in2:1
temp1                 SENSORS_FSCHER_TEMP1                              temp1:2
temp2                 SENSORS_FSCHER_TEMP2                              temp2:2
temp3                 SENSORS_FSCHER_TEMP3                              temp3:2
temp1_state           SENSORS_FSCHER_TEMP1_STATE                        temp1:1
temp2_state           SENSORS_FSCHER_TEMP2_STATE                        temp2:1
temp3_state           SENSORS_FSCHER_TEMP3_STATE                        temp3:1
fan1                  SENSORS_FSCHER_FAN1                                fan1:4
fan2                  SENSORS_FSCHER_FAN2                                fan2:4
fan3                  SENSORS_FSCHER_FAN3                                fan3:4
fan1_min              SENSORS_FSCHER_FAN1_MIN                            fan1:2
fan2_min              SENSORS_FSCHER_FAN2_MIN                            fan2:2
fan3_min              SENSORS_FSCHER_FAN3_MIN                            fan3:2
fan1_state            SENSORS_FSCHER_FAN1_STATE                          fan1:1
fan2_state            SENSORS_FSCHER_FAN2_STATE                          fan2:1
fan3_state            SENSORS_FSCHER_FAN3_STATE                          fan3:1
fan1_ripple           SENSORS_FSCHER_FAN1_RIPPLE                         fan1:3
fan2_ripple           SENSORS_FSCHER_FAN2_RIPPLE                         fan2:3
fan3_ripple           SENSORS_FSCHER_FAN3_RIPPLE                         fan3:3
wdog_preset           SENSORS_FSCHER_WDOG_PRESET                         wdog:1
wdog_state            SENSORS_FSCHER_WDOG_STATE                          wdog:2
wdog_control          SENSORS_FSCHER_WDOG_CONTROL                        wdog:3
