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