Documentation/hwmon/adm9240.rst

   1 Kernel driver adm9240
   2 =====================
   3
   4 Supported chips:
   5
   6   * Analog Devices ADM9240
   7
   8     Prefix: 'adm9240'
   9
  10     Addresses scanned: I2C 0x2c - 0x2f
  11
  12     Datasheet: Publicly available at the Analog Devices website
  13
  14         http://www.analog.com/UploadedFiles/Data_Sheets/79857778ADM9240_0.pdf
  15
  16   * Dallas Semiconductor DS1780
  17
  18     Prefix: 'ds1780'
  19
  20     Addresses scanned: I2C 0x2c - 0x2f
  21
  22     Datasheet: Publicly available at the Dallas Semiconductor (Maxim) website
  23
  24         http://pdfserv.maxim-ic.com/en/ds/DS1780.pdf
  25
  26   * National Semiconductor LM81
  27
  28     Prefix: 'lm81'
  29
  30     Addresses scanned: I2C 0x2c - 0x2f
  31
  32     Datasheet: Publicly available at the National Semiconductor website
  33
  34         http://www.national.com/ds.cgi/LM/LM81.pdf
  35
  36 Authors:
  37     - Frodo Looijaard <frodol@dds.nl>,
  38     - Philip Edelbrock <phil@netroedge.com>,
  39     - Michiel Rook <michiel@grendelproject.nl>,
  40     - Grant Coady <gcoady.lk@gmail.com> with guidance
  41       from Jean Delvare <jdelvare@suse.de>
  42
  43 Interface
  44 ---------
  45 The I2C addresses listed above assume BIOS has not changed the
  46 chip MSB 5-bit address. Each chip reports a unique manufacturer
  47 identification code as well as the chip revision/stepping level.
  48
  49 Description
  50 -----------
  51 [From ADM9240] The ADM9240 is a complete system hardware monitor for
  52 microprocessor-based systems, providing measurement and limit comparison
  53 of up to four power supplies and two processor core voltages, plus
  54 temperature, two fan speeds and chassis intrusion. Measured values can
  55 be read out via an I2C-compatible serial System Management Bus, and values
  56 for limit comparisons can be programmed in over the same serial bus. The
  57 high speed successive approximation ADC allows frequent sampling of all
  58 analog channels to ensure a fast interrupt response to any out-of-limit
  59 measurement.
  60
  61 The ADM9240, DS1780 and LM81 are register compatible, the following
  62 details are common to the three chips. Chip differences are described
  63 after this section.
  64
  65
  66 Measurements
  67 ------------
  68 The measurement cycle
  69
  70 The adm9240 driver will take a measurement reading no faster than once
  71 each two seconds. User-space may read sysfs interface faster than the
  72 measurement update rate and will receive cached data from the most
  73 recent measurement.
  74
  75 ADM9240 has a very fast 320us temperature and voltage measurement cycle
  76 with independent fan speed measurement cycles counting alternating rising
  77 edges of the fan tacho inputs.
  78
  79 DS1780 measurement cycle is about once per second including fan speed.
  80
  81 LM81 measurement cycle is about once per 400ms including fan speed.
  82 The LM81 12-bit extended temperature measurement mode is not supported.
  83
  84 Temperature
  85 -----------
  86 On chip temperature is reported as degrees Celsius as 9-bit signed data
  87 with resolution of 0.5 degrees Celsius. High and low temperature limits
  88 are 8-bit signed data with resolution of one degree Celsius.
  89
  90 Temperature alarm is asserted once the temperature exceeds the high limit,
  91 and is cleared when the temperature falls below the temp1_max_hyst value.
  92
  93 Fan Speed
  94 ---------
  95 Two fan tacho inputs are provided, the ADM9240 gates an internal 22.5kHz
  96 clock via a divider to an 8-bit counter. Fan speed (rpm) is calculated by:
  97
  98 rpm = (22500 * 60) / (count * divider)
  99
 100 Automatic fan clock divider
 101
 102   * User sets 0 to fan_min limit
 103
 104     - low speed alarm is disabled
 105     - fan clock divider not changed
 106     - auto fan clock adjuster enabled for valid fan speed reading
 107
 108   * User sets fan_min limit too low
 109
 110     - low speed alarm is enabled
 111     - fan clock divider set to max
 112     - fan_min set to register value 254 which corresponds
 113       to 664 rpm on adm9240
 114     - low speed alarm will be asserted if fan speed is
 115       less than minimum measurable speed
 116     - auto fan clock adjuster disabled
 117
 118   * User sets reasonable fan speed
 119
 120     - low speed alarm is enabled
 121     - fan clock divider set to suit fan_min
 122     - auto fan clock adjuster enabled: adjusts fan_min
 123
 124   * User sets unreasonably high low fan speed limit
 125
 126     - resolution of the low speed limit may be reduced
 127     - alarm will be asserted
 128     - auto fan clock adjuster enabled: adjusts fan_min
 129
 130   * fan speed may be displayed as zero until the auto fan clock divider
 131     adjuster brings fan speed clock divider back into chip measurement
 132     range, this will occur within a few measurement cycles.
 133
 134 Analog Output
 135 -------------
 136 An analog output provides a 0 to 1.25 volt signal intended for an external
 137 fan speed amplifier circuit. The analog output is set to maximum value on
 138 power up or reset. This doesn't do much on the test Intel SE440BX-2.
 139
 140 Voltage Monitor
 141
 142 ^^^^^^^^^^^^^^^
 143
 144 Voltage (IN) measurement is internally scaled:
 145
 146     === =========== =========== ========= ==========
 147     nr  label       nominal     maximum   resolution
 148                       mV          mV         mV
 149     === =========== =========== ========= ==========
 150     0   +2.5V        2500        3320       13.0
 151     1   Vccp1        2700        3600       14.1
 152     2   +3.3V        3300        4380       17.2
 153     3     +5V        5000        6640       26.0
 154     4    +12V       12000       15940       62.5
 155     5   Vccp2        2700        3600       14.1
 156     === =========== =========== ========= ==========
 157
 158 The reading is an unsigned 8-bit value, nominal voltage measurement is
 159 represented by a reading of 192, being 3/4 of the measurement range.
 160
 161 An alarm is asserted for any voltage going below or above the set limits.
 162
 163 The driver reports and accepts voltage limits scaled to the above table.
 164
 165 VID Monitor
 166 -----------
 167 The chip has five inputs to read the 5-bit VID and reports the mV value
 168 based on detected CPU type.
 169
 170 Chassis Intrusion
 171 -----------------
 172 An alarm is asserted when the CI pin goes active high. The ADM9240
 173 Datasheet has an example of an external temperature sensor driving
 174 this pin. On an Intel SE440BX-2 the Chassis Intrusion header is
 175 connected to a normally open switch.
 176
 177 The ADM9240 provides an internal open drain on this line, and may output
 178 a 20 ms active low pulse to reset an external Chassis Intrusion latch.
 179
 180 Clear the CI latch by writing value 0 to the sysfs intrusion0_alarm file.
 181
 182 Alarm flags reported as 16-bit word
 183
 184     ===     =============       ==========================
 185     bit     label               comment
 186     ===     =============       ==========================
 187      0      +2.5 V_Error        high or low limit exceeded
 188      1      VCCP_Error          high or low limit exceeded
 189      2      +3.3 V_Error        high or low limit exceeded
 190      3      +5 V_Error          high or low limit exceeded
 191      4      Temp_Error          temperature error
 192      6      FAN1_Error          fan low limit exceeded
 193      7      FAN2_Error          fan low limit exceeded
 194      8      +12 V_Error         high or low limit exceeded
 195      9      VCCP2_Error         high or low limit exceeded
 196     12      Chassis_Error       CI pin went high
 197     ===     =============       ==========================
 198
 199 Remaining bits are reserved and thus undefined. It is important to note
 200 that alarm bits may be cleared on read, user-space may latch alarms and
 201 provide the end-user with a method to clear alarm memory.