[PATCH] I2C: documentation update 2/3

This patch adds missing documentation for system health monitoring chips.
I would like to thank all people, who helped me with this project.

Signed-off-by: Rudolf Marek <r.marek@sh.cvut.cz>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

1 files changed, 169 insertions, 0 deletions

diff --git a/Documentation/i2c/chips/fscher b/Documentation/i2c/chips/fscher
new file mode 100644
index 000000000000..64031659aff3
--- /dev/null
+++ b/Documentation/i2c/chips/fscher
@@ -0,0 +1,169 @@
+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.