Documentation/hwmon/abituguru-datasheet.rst

   1 ===============
   2 uGuru datasheet
   3 ===============
   4
   5 First of all, what I know about uGuru is no fact based on any help, hints or
   6 datasheet from Abit. The data I have got on uGuru have I assembled through
   7 my weak knowledge in "backwards engineering".
   8 And just for the record, you may have noticed uGuru isn't a chip developed by
   9 Abit, as they claim it to be. It's really just an microprocessor (uC) created by
  10 Winbond (W83L950D). And no, reading the manual for this specific uC or
  11 mailing  Windbond for help won't give any useful data about uGuru, as it is
  12 the program inside the uC that is responding to calls.
  13
  14 Olle Sandberg <ollebull@gmail.com>, 2005-05-25
  15
  16
  17 Original version by Olle Sandberg who did the heavy lifting of the initial
  18 reverse engineering. This version has been almost fully rewritten for clarity
  19 and extended with write support and info on more databanks, the write support
  20 is once again reverse engineered by Olle the additional databanks have been
  21 reverse engineered by me. I would like to express my thanks to Olle, this
  22 document and the Linux driver could not have been written without his efforts.
  23
  24 Note: because of the lack of specs only the sensors part of the uGuru is
  25 described here and not the CPU / RAM / etc voltage & frequency control.
  26
  27 Hans de Goede <j.w.r.degoede@hhs.nl>, 28-01-2006
  28
  29
  30 Detection
  31 =========
  32
  33 As far as known the uGuru is always placed at and using the (ISA) I/O-ports
  34 0xE0 and 0xE4, so we don't have to scan any port-range, just check what the two
  35 ports are holding for detection. We will refer to 0xE0 as CMD (command-port)
  36 and 0xE4 as DATA because Abit refers to them with these names.
  37
  38 If DATA holds 0x00 or 0x08 and CMD holds 0x00 or 0xAC an uGuru could be
  39 present. We have to check for two different values at data-port, because
  40 after a reboot uGuru will hold 0x00 here, but if the driver is removed and
  41 later on attached again data-port will hold 0x08, more about this later.
  42
  43 After wider testing of the Linux kernel driver some variants of the uGuru have
  44 turned up which will hold 0x00 instead of 0xAC at the CMD port, thus we also
  45 have to test CMD for two different values. On these uGuru's DATA will initially
  46 hold 0x09 and will only hold 0x08 after reading CMD first, so CMD must be read
  47 first!
  48
  49 To be really sure an uGuru is present a test read of one or more register
  50 sets should be done.
  51
  52
  53 Reading / Writing
  54 =================
  55
  56 Addressing
  57 ----------
  58
  59 The uGuru has a number of different addressing levels. The first addressing
  60 level we will call banks. A bank holds data for one or more sensors. The data
  61 in a bank for a sensor is one or more bytes large.
  62
  63 The number of bytes is fixed for a given bank, you should always read or write
  64 that many bytes, reading / writing more will fail, the results when writing
  65 less then the number of bytes for a given bank are undetermined.
  66
  67 See below for all known bank addresses, numbers of sensors in that bank,
  68 number of bytes data per sensor and contents/meaning of those bytes.
  69
  70 Although both this document and the kernel driver have kept the sensor
  71 terminoligy for the addressing within a bank this is not 100% correct, in
  72 bank 0x24 for example the addressing within the bank selects a PWM output not
  73 a sensor.
  74
  75 Notice that some banks have both a read and a write address this is how the
  76 uGuru determines if a read from or a write to the bank is taking place, thus
  77 when reading you should always use the read address and when writing the
  78 write address. The write address is always one (1) more than the read address.
  79
  80
  81 uGuru ready
  82 -----------
  83
  84 Before you can read from or write to the uGuru you must first put the uGuru
  85 in "ready" mode.
  86
  87 To put the uGuru in ready mode first write 0x00 to DATA and then wait for DATA
  88 to hold 0x09, DATA should read 0x09 within 250 read cycles.
  89
  90 Next CMD _must_ be read and should hold 0xAC, usually CMD will hold 0xAC the
  91 first read but sometimes it takes a while before CMD holds 0xAC and thus it
  92 has to be read a number of times (max 50).
  93
  94 After reading CMD, DATA should hold 0x08 which means that the uGuru is ready
  95 for input. As above DATA will usually hold 0x08 the first read but not always.
  96 This step can be skipped, but it is undetermined what happens if the uGuru has
  97 not yet reported 0x08 at DATA and you proceed with writing a bank address.
  98
  99
 100 Sending bank and sensor addresses to the uGuru
 101 ----------------------------------------------
 102
 103 First the uGuru must be in "ready" mode as described above, DATA should hold
 104 0x08 indicating that the uGuru wants input, in this case the bank address.
 105
 106 Next write the bank address to DATA. After the bank address has been written
 107 wait for to DATA to hold 0x08 again indicating that it wants / is ready for
 108 more input (max 250 reads).
 109
 110 Once DATA holds 0x08 again write the sensor address to CMD.
 111
 112
 113 Reading
 114 -------
 115
 116 First send the bank and sensor addresses as described above.
 117 Then for each byte of data you want to read wait for DATA to hold 0x01
 118 which indicates that the uGuru is ready to be read (max 250 reads) and once
 119 DATA holds 0x01 read the byte from CMD.
 120
 121 Once all bytes have been read data will hold 0x09, but there is no reason to
 122 test for this. Notice that the number of bytes is bank address dependent see
 123 above and below.
 124
 125 After completing a successful read it is advised to put the uGuru back in
 126 ready mode, so that it is ready for the next read / write cycle. This way
 127 if your program / driver is unloaded and later loaded again the detection
 128 algorithm described above will still work.
 129
 130
 131
 132 Writing
 133 -------
 134
 135 First send the bank and sensor addresses as described above.
 136 Then for each byte of data you want to write wait for DATA to hold 0x00
 137 which indicates that the uGuru is ready to be written (max 250 reads) and
 138 once DATA holds 0x00 write the byte to CMD.
 139
 140 Once all bytes have been written wait for DATA to hold 0x01 (max 250 reads)
 141 don't ask why this is the way it is.
 142
 143 Once DATA holds 0x01 read CMD it should hold 0xAC now.
 144
 145 After completing a successful write it is advised to put the uGuru back in
 146 ready mode, so that it is ready for the next read / write cycle. This way
 147 if your program / driver is unloaded and later loaded again the detection
 148 algorithm described above will still work.
 149
 150
 151 Gotchas
 152 -------
 153
 154 After wider testing of the Linux kernel driver some variants of the uGuru have
 155 turned up which do not hold 0x08 at DATA within 250 reads after writing the
 156 bank address. With these versions this happens quite frequent, using larger
 157 timeouts doesn't help, they just go offline for a second or 2, doing some
 158 internal callibration or whatever. Your code should be prepared to handle
 159 this and in case of no response in this specific case just goto sleep for a
 160 while and then retry.
 161
 162
 163 Address Map
 164 ===========
 165
 166 Bank 0x20 Alarms (R)
 167 --------------------
 168 This bank contains 0 sensors, iow the sensor address is ignored (but must be
 169 written) just use 0. Bank 0x20 contains 3 bytes:
 170
 171 Byte 0:
 172   This byte holds the alarm flags for sensor 0-7 of Sensor Bank1, with bit 0
 173   corresponding to sensor 0, 1 to 1, etc.
 174
 175 Byte 1:
 176   This byte holds the alarm flags for sensor 8-15 of Sensor Bank1, with bit 0
 177   corresponding to sensor 8, 1 to 9, etc.
 178
 179 Byte 2:
 180   This byte holds the alarm flags for sensor 0-5 of Sensor Bank2, with bit 0
 181   corresponding to sensor 0, 1 to 1, etc.
 182
 183
 184 Bank 0x21 Sensor Bank1 Values / Readings (R)
 185 --------------------------------------------
 186 This bank contains 16 sensors, for each sensor it contains 1 byte.
 187 So far the following sensors are known to be available on all motherboards:
 188
 189 - Sensor  0 CPU temp
 190 - Sensor  1 SYS temp
 191 - Sensor  3 CPU core volt
 192 - Sensor  4 DDR volt
 193 - Sensor 10 DDR Vtt volt
 194 - Sensor 15 PWM temp
 195
 196 Byte 0:
 197   This byte holds the reading from the sensor. Sensors in Bank1 can be both
 198   volt and temp sensors, this is motherboard specific. The uGuru however does
 199   seem to know (be programmed with) what kindoff sensor is attached see Sensor
 200   Bank1 Settings description.
 201
 202 Volt sensors use a linear scale, a reading 0 corresponds with 0 volt and a
 203 reading of 255 with 3494 mV. The sensors for higher voltages however are
 204 connected through a division circuit. The currently known division circuits
 205 in use result in ranges of: 0-4361mV, 0-6248mV or 0-14510mV. 3.3 volt sources
 206 use the 0-4361mV range, 5 volt the 0-6248mV and 12 volt the 0-14510mV .
 207
 208 Temp sensors also use a linear scale, a reading of 0 corresponds with 0 degree
 209 Celsius and a reading of 255 with a reading of 255 degrees Celsius.
 210
 211
 212 Bank 0x22 Sensor Bank1 Settings (R) and Bank 0x23 Sensor Bank1 Settings (W)
 213 ---------------------------------------------------------------------------
 214
 215 Those banks contain 16 sensors, for each sensor it contains 3 bytes. Each
 216 set of 3 bytes contains the settings for the sensor with the same sensor
 217 address in Bank 0x21 .
 218
 219 Byte 0:
 220   Alarm behaviour for the selected sensor. A 1 enables the described
 221   behaviour.
 222
 223 Bit 0:
 224   Give an alarm if measured temp is over the warning threshold          (RW) [1]_
 225
 226 Bit 1:
 227   Give an alarm if measured volt is over the max threshold              (RW) [2]_
 228
 229 Bit 2:
 230   Give an alarm if measured volt is under the min threshold             (RW) [2]_
 231
 232 Bit 3:
 233   Beep if alarm                                                         (RW)
 234
 235 Bit 4:
 236   1 if alarm cause measured temp is over the warning threshold          (R)
 237
 238 Bit 5:
 239   1 if alarm cause measured volt is over the max threshold              (R)
 240
 241 Bit 6:
 242   1 if alarm cause measured volt is under the min threshold             (R)
 243
 244 Bit 7:
 245   - Volt sensor: Shutdown if alarm persist for more than 4 seconds      (RW)
 246   - Temp sensor: Shutdown if temp is over the shutdown threshold        (RW)
 247
 248 .. [1] This bit is only honored/used by the uGuru if a temp sensor is connected
 249
 250 .. [2] This bit is only honored/used by the uGuru if a volt sensor is connected
 251        Note with some trickery this can be used to find out what kinda sensor
 252        is detected see the Linux kernel driver for an example with many
 253        comments on how todo this.
 254
 255 Byte 1:
 256   - Temp sensor: warning threshold  (scale as bank 0x21)
 257   - Volt sensor: min threshold      (scale as bank 0x21)
 258
 259 Byte 2:
 260   - Temp sensor: shutdown threshold (scale as bank 0x21)
 261   - Volt sensor: max threshold      (scale as bank 0x21)
 262
 263
 264 Bank 0x24 PWM outputs for FAN's (R) and Bank 0x25 PWM outputs for FAN's (W)
 265 ---------------------------------------------------------------------------
 266
 267 Those banks contain 3 "sensors", for each sensor it contains 5 bytes.
 268   - Sensor 0 usually controls the CPU fan
 269   - Sensor 1 usually controls the NB (or chipset for single chip) fan
 270   - Sensor 2 usually controls the System fan
 271
 272 Byte 0:
 273   Flag 0x80 to enable control, Fan runs at 100% when disabled.
 274   low nibble (temp)sensor address at bank 0x21 used for control.
 275
 276 Byte 1:
 277   0-255 = 0-12v (linear), specify voltage at which fan will rotate when under
 278   low threshold temp (specified in byte 3)
 279
 280 Byte 2:
 281   0-255 = 0-12v (linear), specify voltage at which fan will rotate when above
 282   high threshold temp (specified in byte 4)
 283
 284 Byte 3:
 285   Low threshold temp  (scale as bank 0x21)
 286
 287 byte 4:
 288   High threshold temp (scale as bank 0x21)
 289
 290
 291 Bank 0x26 Sensors Bank2 Values / Readings (R)
 292 ---------------------------------------------
 293
 294 This bank contains 6 sensors (AFAIK), for each sensor it contains 1 byte.
 295
 296 So far the following sensors are known to be available on all motherboards:
 297   - Sensor 0: CPU fan speed
 298   - Sensor 1: NB (or chipset for single chip) fan speed
 299   - Sensor 2: SYS fan speed
 300
 301 Byte 0:
 302   This byte holds the reading from the sensor. 0-255 = 0-15300 (linear)
 303
 304
 305 Bank 0x27 Sensors Bank2 Settings (R) and Bank 0x28 Sensors Bank2 Settings (W)
 306 -----------------------------------------------------------------------------
 307
 308 Those banks contain 6 sensors (AFAIK), for each sensor it contains 2 bytes.
 309
 310 Byte 0:
 311   Alarm behaviour for the selected sensor. A 1 enables the described behaviour.
 312
 313 Bit 0:
 314   Give an alarm if measured rpm is under the min threshold      (RW)
 315
 316 Bit 3:
 317   Beep if alarm                                                 (RW)
 318
 319 Bit 7:
 320   Shutdown if alarm persist for more than 4 seconds             (RW)
 321
 322 Byte 1:
 323   min threshold (scale as bank 0x26)
 324
 325
 326 Warning for the adventurous
 327 ===========================
 328
 329 A word of caution to those who want to experiment and see if they can figure
 330 the voltage / clock programming out, I tried reading and only reading banks
 331 0-0x30 with the reading code used for the sensor banks (0x20-0x28) and this
 332 resulted in a _permanent_ reprogramming of the voltages, luckily I had the
 333 sensors part configured so that it would shutdown my system on any out of spec
 334 voltages which proprably safed my computer (after a reboot I managed to
 335 immediately enter the bios and reload the defaults). This probably means that
 336 the read/write cycle for the non sensor part is different from the sensor part.