Documentation/hwmon/pc87360.rst

   1 Kernel driver pc87360
   2 =====================
   3
   4 Supported chips:
   5
   6   * National Semiconductor PC87360, PC87363, PC87364, PC87365 and PC87366
   7
   8     Prefixes: 'pc87360', 'pc87363', 'pc87364', 'pc87365', 'pc87366'
   9
  10     Addresses scanned: none, address read from Super I/O config space
  11
  12     Datasheets: No longer available
  13
  14 Authors: Jean Delvare <jdelvare@suse.de>
  15
  16 Thanks to Sandeep Mehta, Tonko de Rooy and Daniel Ceregatti for testing.
  17
  18 Thanks to Rudolf Marek for helping me investigate conversion issues.
  19
  20
  21 Module Parameters
  22 -----------------
  23
  24 * init int
  25     Chip initialization level:
  26
  27     - 0: None
  28     - **1**: Forcibly enable internal voltage and temperature channels,
  29       except in9
  30     - 2: Forcibly enable all voltage and temperature channels, except in9
  31     - 3: Forcibly enable all voltage and temperature channels, including in9
  32
  33 Note that this parameter has no effect for the PC87360, PC87363 and PC87364
  34 chips.
  35
  36 Also note that for the PC87366, initialization levels 2 and 3 don't enable
  37 all temperature channels, because some of them share pins with each other,
  38 so they can't be used at the same time.
  39
  40
  41 Description
  42 -----------
  43
  44 The National Semiconductor PC87360 Super I/O chip contains monitoring and
  45 PWM control circuitry for two fans. The PC87363 chip is similar, and the
  46 PC87364 chip has monitoring and PWM control for a third fan.
  47
  48 The National Semiconductor PC87365 and PC87366 Super I/O chips are complete
  49 hardware monitoring chipsets, not only controlling and monitoring three fans,
  50 but also monitoring eleven voltage inputs and two (PC87365) or up to four
  51 (PC87366) temperatures.
  52
  53   =========== ======= ======= ======= ======= =====
  54   Chip        #vin    #fan    #pwm    #temp   devid
  55   =========== ======= ======= ======= ======= =====
  56   PC87360     -       2       2       -       0xE1
  57   PC87363     -       2       2       -       0xE8
  58   PC87364     -       3       3       -       0xE4
  59   PC87365     11      3       3       2       0xE5
  60   PC87366     11      3       3       3-4     0xE9
  61   =========== ======= ======= ======= ======= =====
  62
  63 The driver assumes that no more than one chip is present, and one of the
  64 standard Super I/O addresses is used (0x2E/0x2F or 0x4E/0x4F)
  65
  66 Fan Monitoring
  67 --------------
  68
  69 Fan rotation speeds are reported in RPM (revolutions per minute). An alarm
  70 is triggered if the rotation speed has dropped below a programmable limit.
  71 A different alarm is triggered if the fan speed is too low to be measured.
  72
  73 Fan readings are affected by a programmable clock divider, giving the
  74 readings more range or accuracy. Usually, users have to learn how it works,
  75 but this driver implements dynamic clock divider selection, so you don't
  76 have to care no more.
  77
  78 For reference, here are a few values about clock dividers:
  79
  80     =========== =============== =============== ===========
  81                 slowest         accuracy        highest
  82                 measurable      around 3000     accurate
  83     divider     speed (RPM)     RPM (RPM)       speed (RPM)
  84     =========== =============== =============== ===========
  85          1        1882              18           6928
  86          2         941              37           4898
  87          4         470              74           3464
  88          8         235             150           2449
  89     =========== =============== =============== ===========
  90
  91 For the curious, here is how the values above were computed:
  92
  93  * slowest measurable speed: clock/(255*divider)
  94  * accuracy around 3000 RPM: 3000^2/clock
  95  * highest accurate speed: sqrt(clock*100)
  96
  97 The clock speed for the PC87360 family is 480 kHz. I arbitrarily chose 100
  98 RPM as the lowest acceptable accuracy.
  99
 100 As mentioned above, you don't have to care about this no more.
 101
 102 Note that not all RPM values can be represented, even when the best clock
 103 divider is selected. This is not only true for the measured speeds, but
 104 also for the programmable low limits, so don't be surprised if you try to
 105 set, say, fan1_min to 2900 and it finally reads 2909.
 106
 107
 108 Fan Control
 109 -----------
 110
 111 PWM (pulse width modulation) values range from 0 to 255, with 0 meaning
 112 that the fan is stopped, and 255 meaning that the fan goes at full speed.
 113
 114 Be extremely careful when changing PWM values. Low PWM values, even
 115 non-zero, can stop the fan, which may cause irreversible damage to your
 116 hardware if temperature increases too much. When changing PWM values, go
 117 step by step and keep an eye on temperatures.
 118
 119 One user reported problems with PWM. Changing PWM values would break fan
 120 speed readings. No explanation nor fix could be found.
 121
 122
 123 Temperature Monitoring
 124 ----------------------
 125
 126 Temperatures are reported in degrees Celsius. Each temperature measured has
 127 associated low, high and overtemperature limits, each of which triggers an
 128 alarm when crossed.
 129
 130 The first two temperature channels are external. The third one (PC87366
 131 only) is internal.
 132
 133 The PC87366 has three additional temperature channels, based on
 134 thermistors (as opposed to thermal diodes for the first three temperature
 135 channels). For technical reasons, these channels are held by the VLM
 136 (voltage level monitor) logical device, not the TMS (temperature
 137 measurement) one. As a consequence, these temperatures are exported as
 138 voltages, and converted into temperatures in user-space.
 139
 140 Note that these three additional channels share their pins with the
 141 external thermal diode channels, so you (physically) can't use them all at
 142 the same time. Although it should be possible to mix the two sensor types,
 143 the documents from National Semiconductor suggest that motherboard
 144 manufacturers should choose one type and stick to it. So you will more
 145 likely have either channels 1 to 3 (thermal diodes) or 3 to 6 (internal
 146 thermal diode, and thermistors).
 147
 148
 149 Voltage Monitoring
 150 ------------------
 151
 152 Voltages are reported relatively to a reference voltage, either internal or
 153 external. Some of them (in7:Vsb, in8:Vdd and in10:AVdd) are divided by two
 154 internally, you will have to compensate in sensors.conf. Others (in0 to in6)
 155 are likely to be divided externally. The meaning of each of these inputs as
 156 well as the values of the resistors used for division is left to the
 157 motherboard manufacturers, so you will have to document yourself and edit
 158 sensors.conf accordingly. National Semiconductor has a document with
 159 recommended resistor values for some voltages, but this still leaves much
 160 room for per motherboard specificities, unfortunately. Even worse,
 161 motherboard manufacturers don't seem to care about National Semiconductor's
 162 recommendations.
 163
 164 Each voltage measured has associated low and high limits, each of which
 165 triggers an alarm when crossed.
 166
 167 When available, VID inputs are used to provide the nominal CPU Core voltage.
 168 The driver will default to VRM 9.0, but this can be changed from user-space.
 169 The chipsets can handle two sets of VID inputs (on dual-CPU systems), but
 170 the driver will only export one for now. This may change later if there is
 171 a need.
 172
 173
 174 General Remarks
 175 ---------------
 176
 177 If an alarm triggers, it will remain triggered until the hardware register
 178 is read at least once. This means that the cause for the alarm may already
 179 have disappeared! Note that all hardware registers are read whenever any
 180 data is read (unless it is less than 2 seconds since the last update, in
 181 which case cached values are returned instead). As a consequence, when
 182 a once-only alarm triggers, it may take 2 seconds for it to show, and 2
 183 more seconds for it to disappear.
 184
 185 Monitoring of in9 isn't enabled at lower init levels (<3) because that
 186 channel measures the battery voltage (Vbat). It is a known fact that
 187 repeatedly sampling the battery voltage reduces its lifetime. National
 188 Semiconductor smartly designed their chipset so that in9 is sampled only
 189 once every 1024 sampling cycles (that is every 34 minutes at the default
 190 sampling rate), so the effect is attenuated, but still present.
 191
 192
 193 Limitations
 194 -----------
 195
 196 The datasheets suggests that some values (fan mins, fan dividers)
 197 shouldn't be changed once the monitoring has started, but we ignore that
 198 recommendation. We'll reconsider if it actually causes trouble.