Kernel driver `gl518sm.o'
=========================

Status: Complete and well-tested

Supported chips:
  * Genesys Logic GL518SM release 0x00
    Prefix `gl518sm-r00'
    Addresses scanned: I2C 0x2c and 0x2d
    Datasheet: Not openly available
  * Genesys Logic GL518SM release 0x80
    Prefix `gl518sm-r80'
    Addresses scanned: I2C 0x2c and 0x2d
    Datasheet: Not available at all, as far as we know

Author: Frodo Looijaard <frodol@dds.nl>


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

* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* force_gl518sm_r00: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `gl518sm_r00' chip
* force_gl518sm_r80: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `gl518sm_r80' chip
* 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
* 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
* readall: int
  Enable the experimental code, which tries to find the voltages of
  revision zero chips by slow (10 seconds) interpolation


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

This driver supports the Genesys Logic GL518SM chip. There are at least
two revision of this chip, which we call revision 0x00 and 0x80. Revision
0x80 chips support the reading of voltages directly, 0x00 only for VIN3.

The GL518SM implements one temperature sensor, two FAN rotation speed
sensors, and four voltage sensors. It can report alarms through the
computer speakers.

Temperatures are measured in degrees Celcius. An alarm goes off while the
temperature is above the over temperature limit, and has not yet dropped
below the hysteris limit. The alarm always reflects the current situation.
Measurements are guaranteed between -40 degrees and +125 degrees, with
a resolution of 1 degree.

FAN rotation speeds are reported in RPM (rotations per minute). An alarm is
triggered if the rotation speed has dropped below a programmable limit. FAN 
readings can be divided by a programmable divider (1, 2, 4 or 8) to give
the readings more range or accuracy. This is important because some FANs
report only one 'tick' each rotation, while others report two - making
all readings twice as high. Not all RPM values can accurately be represented,
so some rounding is done. With a divider of 2, the lowest representable
value is around 1900 RPM.

Voltage sensors (also known as VIN sensors) report their values in volts.
An alarm is triggered if the voltage has crossed a programmable minimum 
or maximum limit. Note that minimum in this case always means 'closest to
zero'; this is important for negative voltage measurements. The VDD input
measures voltages between 0.000 and 5.865 volt, with a resolution of 0.023
volt. The other inputs measure voltages between 0.000 and 4.845 volt, with
a resolution of 0.019 volt. Note that revision 0x00 chips do not support
reading the current voltage of any input except for VIN3; limit setting
and alarms work fine, though. Yes, this is weird. There is experimental
code to compute them by interpolation; see the 'readall' module parameter.

When an alarm goes off, you can be warned by a beeping signal through
your computer speaker. It is possible to enable all beeping globally,
or only the beeping for some alarms.

If an alarm triggers, it will remain triggered until the hardware register
is read at least once (except for temperature alarms). This means that the 
cause for the alarm may already have disappeared!  Note that in the current 
implementation, all hardware registers are read whenever any data is read 
(unless it is less than 1.5 seconds since the last update). This means that 
you can easily miss once-only alarms.

The GL518SM only updates its values each 1.5 seconds; reading it more often
will do no harm, but will return 'old' values.

Not supported is the option to use only one fan, and to enable/disable the 
speed of that fan automatically as function of the current temperature.


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

Chip `gl518sm-r00'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
               vdd               NONE               NONE     R     2
              vin1               NONE               NONE     R     2
              vin2               NONE               NONE     R     2
              vin3               NONE               NONE     R     2
           vdd_min                vdd                vdd     RW    2
          vin1_min               vin1               vin1     RW    2
          vin2_min               vin2               vin2     RW    2
          vin3_min               vin3               vin3     RW    2
           vdd_max                vdd                vdd     RW    2
          vin1_max               vin1               vin1     RW    2
          vin2_max               vin2               vin2     RW    2
          vin3_max               vin3               vin3     RW    2
              fan1               NONE               NONE     R     0
              fan2               NONE               NONE     R     0
          fan1_min               fan1               fan1     RW    0
          fan2_min               fan2               fan2     RW    0
              temp               NONE               NONE     R     1
         temp_hyst               temp               temp     RW    1
         temp_over               temp               temp     RW    1
          fan1_div               fan1               NONE     RW    0
          fan2_div               fan2               NONE     RW    0
            alarms               NONE               NONE     R     0
       beep_enable             alarms               NONE     RW    0
             beeps             alarms             alarms     RW    0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
               vdd                    SENSORS_GL518R00_VDD                vdd:3
              vin1                   SENSORS_GL518R00_VIN1               vin1:3
              vin2                   SENSORS_GL518R00_VIN2               vin2:3
              vin3                   SENSORS_GL518R00_VIN3               vin3:3
           vdd_min                SENSORS_GL518R00_VDD_MIN                vdd:1
          vin1_min               SENSORS_GL518R00_VIN1_MIN               vin1:1
          vin2_min               SENSORS_GL518R00_VIN2_MIN               vin2:1
          vin3_min               SENSORS_GL518R00_VIN3_MIN               vin3:1
           vdd_max                SENSORS_GL518R00_VDD_MAX                vdd:2
          vin1_max               SENSORS_GL518R00_VIN1_MAX               vin1:2
          vin2_max               SENSORS_GL518R00_VIN2_MAX               vin2:2
          vin3_max               SENSORS_GL518R00_VIN3_MAX               vin3:2
              fan1                   SENSORS_GL518R00_FAN1               fan1:2
              fan2                   SENSORS_GL518R00_FAN2               fan2:2
          fan1_min               SENSORS_GL518R00_FAN1_MIN               fan1:1
          fan2_min               SENSORS_GL518R00_FAN2_MIN               fan2:1
              temp                   SENSORS_GL518R00_TEMP               temp:3
         temp_hyst              SENSORS_GL518R00_TEMP_HYST               temp:2
         temp_over              SENSORS_GL518R00_TEMP_OVER               temp:1
          fan1_div               SENSORS_GL518R00_FAN1_DIV            fan_div:1
          fan2_div               SENSORS_GL518R00_FAN2_DIV            fan_div:2
            alarms                 SENSORS_GL518R00_ALARMS             alarms:1
       beep_enable            SENSORS_GL518R00_BEEP_ENABLE               beep:1
             beeps                  SENSORS_GL518R00_BEEPS               beep:2


Chip `gl518sm-r80'
             LABEL        LABEL CLASS      COMPUTE CLASS ACCESS MAGNITUDE
               vdd               NONE               NONE     R     2
              vin1               NONE               NONE     R     2
              vin2               NONE               NONE     R     2
              vin3               NONE               NONE     R     2
           vdd_min                vdd                vdd     RW    2
          vin1_min               vin1               vin1     RW    2
          vin2_min               vin2               vin2     RW    2
          vin3_min               vin3               vin3     RW    2
           vdd_max                vdd                vdd     RW    2
          vin1_max               vin1               vin1     RW    2
          vin2_max               vin2               vin2     RW    2
          vin3_max               vin3               vin3     RW    2
              fan1               NONE               NONE     R     0
              fan2               NONE               NONE     R     0
          fan1_min               fan1               fan1     RW    0
          fan2_min               fan2               fan2     RW    0
              temp               NONE               NONE     R     1
         temp_hyst               temp               temp     RW    1
         temp_over               temp               temp     RW    1
          fan1_div               fan1               NONE     RW    0
          fan2_div               fan2               NONE     RW    0
            alarms               NONE               NONE     R     0
       beep_enable             alarms               NONE     RW    0
             beeps             alarms             alarms     RW    0

             LABEL                          FEATURE SYMBOL        SYSCTL FILE:NR
               vdd                    SENSORS_GL518R80_VDD                vdd:3
              vin1                   SENSORS_GL518R80_VIN1               vin1:3
              vin2                   SENSORS_GL518R80_VIN2               vin2:3
              vin3                   SENSORS_GL518R80_VIN3               vin3:3
           vdd_min                SENSORS_GL518R80_VDD_MIN                vdd:1
          vin1_min               SENSORS_GL518R80_VIN1_MIN               vin1:1
          vin2_min               SENSORS_GL518R80_VIN2_MIN               vin2:1
          vin3_min               SENSORS_GL518R80_VIN3_MIN               vin3:1
           vdd_max                SENSORS_GL518R80_VDD_MAX                vdd:2
          vin1_max               SENSORS_GL518R80_VIN1_MAX               vin1:2
          vin2_max               SENSORS_GL518R80_VIN2_MAX               vin2:2
          vin3_max               SENSORS_GL518R80_VIN3_MAX               vin3:2
              fan1                   SENSORS_GL518R80_FAN1               fan1:2
              fan2                   SENSORS_GL518R80_FAN2               fan2:2
          fan1_min               SENSORS_GL518R80_FAN1_MIN               fan1:1
          fan2_min               SENSORS_GL518R80_FAN2_MIN               fan2:1
              temp                   SENSORS_GL518R80_TEMP               temp:3
         temp_hyst              SENSORS_GL518R80_TEMP_HYST               temp:2
         temp_over              SENSORS_GL518R80_TEMP_OVER               temp:1
          fan1_div               SENSORS_GL518R80_FAN1_DIV            fan_div:1
          fan2_div               SENSORS_GL518R80_FAN2_DIV            fan_div:2
            alarms                 SENSORS_GL518R80_ALARMS             alarms:1
       beep_enable            SENSORS_GL518R80_BEEP_ENABLE               beep:1
             beeps                  SENSORS_GL518R80_BEEPS               beep:2


