uGuru datasheet

Reverse engineering 배경과 uGuru detection

이 문서의 uGuru 정보는 Abit의 도움, hint 또는 datasheet에 근거한 것이 아니라 reverse engineering으로 모은 결과입니다. Abit의 주장과 달리 uGuru는 Abit이 개발한 독립 chip이 아니라 Winbond microcontroller `W83L950D`입니다. 다만 실제 call에 응답하는 것은 microcontroller 안의 program이므로 해당 uC manual을 읽거나 Winbond에 문의해도 uGuru protocol 정보는 얻기 어렵습니다.

초기 reverse engineering은 Olle Sandberg가 수행했고 2005-05-25에 첫 내용을 기록했습니다. Hans de Goede는 명확성을 위해 거의 전부 다시 쓰고 write support와 추가 databank 정보를 더했습니다. Write protocol은 Olle가 다시 reverse engineering했고 추가 bank는 Hans가 분석했습니다.

Specification 부재로 이 문서는 uGuru의 sensor 부분만 설명하며 CPU·RAM 등의 voltage와 frequency control은 다루지 않습니다.

알려진 uGuru는 항상 ISA I/O port `0xE0`과 `0xE4`를 사용하므로 port range를 scan할 필요가 없습니다. Abit 명칭에 따라 `0xE0`을 `CMD` command port, `0xE4`를 `DATA` port라고 부릅니다.

DATA가 `0x00` 또는 `0x08`이고 CMD가 `0x00` 또는 `0xAC`이면 uGuru가 있을 수 있습니다. Reboot 직후 DATA는 `0x00`이지만 driver를 제거했다가 다시 attach하면 `0x08`이므로 두 값을 모두 확인합니다.

일부 variant는 CMD에 `0xAC` 대신 `0x00`을 유지합니다. 이 variant에서 DATA의 초기값은 `0x09`이며 CMD를 먼저 읽어야 `0x08`로 바뀝니다. 따라서 detection에서는 반드시 CMD를 먼저 읽어야 합니다. Presence를 확실히 하려면 하나 이상의 register set을 test-read해야 합니다.

===============
uGuru datasheet
===============

First of all, what I know about uGuru is no fact based on any help, hints or
datasheet from Abit. The data I have got on uGuru have I assembled through
my weak knowledge in "backwards engineering".
And just for the record, you may have noticed uGuru isn't a chip developed by
Abit, as they claim it to be. It's really just a microprocessor (uC) created by
Winbond (W83L950D). And no, reading the manual for this specific uC or
mailing Winbond for help won't give any useful data about uGuru, as it is
the program inside the uC that is responding to calls.

Olle Sandberg <ollebull@gmail.com>, 2005-05-25


Original version by Olle Sandberg who did the heavy lifting of the initial
reverse engineering. This version has been almost fully rewritten for clarity
and extended with write support and info on more databanks, the write support
is once again reverse engineered by Olle the additional databanks have been
reverse engineered by me. I would like to express my thanks to Olle, this
document and the Linux driver could not have been written without his efforts.

Note: because of the lack of specs only the sensors part of the uGuru is
described here and not the CPU / RAM / etc voltage & frequency control.

Hans de Goede <j.w.r.degoede@hhs.nl>, 28-01-2006


Detection
=========

As far as known the uGuru is always placed at and using the (ISA) I/O-ports
0xE0 and 0xE4, so we don't have to scan any port-range, just check what the two
ports are holding for detection. We will refer to 0xE0 as CMD (command-port)
and 0xE4 as DATA because Abit refers to them with these names.

If DATA holds 0x00 or 0x08 and CMD holds 0x00 or 0xAC a uGuru could be
present. We have to check for two different values at data-port, because
after a reboot uGuru will hold 0x00 here, but if the driver is removed and
later on attached again data-port will hold 0x08, more about this later.

After wider testing of the Linux kernel driver some variants of the uGuru have
turned up which will hold 0x00 instead of 0xAC at the CMD port, thus we also
have to test CMD for two different values. On these uGuru's DATA will initially
hold 0x09 and will only hold 0x08 after reading CMD first, so CMD must be read
first!

To be really sure a uGuru is present a test read of one or more register
sets should be done.

Bank addressing과 ready handshake

uGuru에는 여러 addressing level이 있습니다. 첫 level은 bank이며 bank 하나가 sensor 하나 이상의 data를 보관합니다. Bank 안에서 sensor별 data는 한 byte 이상입니다.

Sensor당 byte 수는 bank별로 고정입니다. 항상 정확히 그 수만큼 읽거나 써야 합니다. 더 많이 전송하면 실패하고, 더 적게 쓸 때의 결과는 정의되어 있지 않습니다.

Bank 내부 주소를 문서와 kernel driver에서는 sensor라고 부르지만 완전히 정확한 표현은 아닙니다. 예를 들어 bank `0x24`의 내부 주소는 sensor가 아니라 PWM output을 선택합니다.

일부 bank에는 read address와 write address가 모두 있습니다. 이 주소로 uGuru가 read와 write를 구분하므로 읽을 때는 read address, 쓸 때는 write address를 사용해야 합니다. Write address는 언제나 read address보다 1 큽니다.

Read 또는 write 전에는 uGuru를 `ready` mode로 만들어야 합니다. 먼저 DATA에 `0x00`을 쓰고 DATA가 `0x09`가 될 때까지 최대 250 read cycle을 기다립니다.

다음에는 CMD를 반드시 읽어야 하며 값은 `0xAC`여야 합니다. 보통 첫 read에서 나오지만 늦을 수 있으므로 최대 50회 읽습니다. CMD를 읽은 뒤 DATA는 input-ready를 뜻하는 `0x08`이어야 합니다. 보통 첫 read에서 확인되지만 항상 그렇지는 않습니다. 이 검사를 생략할 수는 있으나 DATA가 아직 `0x08`을 report하지 않았는데 bank address를 쓰면 어떤 일이 생기는지 정의되어 있지 않습니다.

Bank와 sensor address를 보낼 때는 먼저 DATA `0x08` 상태에서 bank address를 DATA에 씁니다. 다시 DATA가 `0x08`이 될 때까지 최대 250회 읽어 추가 input 준비를 확인한 뒤 sensor address를 CMD에 씁니다.

Reading / Writing
=================

Addressing
----------

The uGuru has a number of different addressing levels. The first addressing
level we will call banks. A bank holds data for one or more sensors. The data
in a bank for a sensor is one or more bytes large.

The number of bytes is fixed for a given bank, you should always read or write
that many bytes, reading / writing more will fail, the results when writing
less then the number of bytes for a given bank are undetermined.

See below for all known bank addresses, numbers of sensors in that bank,
number of bytes data per sensor and contents/meaning of those bytes.

Although both this document and the kernel driver have kept the sensor
terminology for the addressing within a bank this is not 100% correct, in
bank 0x24 for example the addressing within the bank selects a PWM output not
a sensor.

Notice that some banks have both a read and a write address this is how the
uGuru determines if a read from or a write to the bank is taking place, thus
when reading you should always use the read address and when writing the
write address. The write address is always one (1) more than the read address.


uGuru ready
-----------

Before you can read from or write to the uGuru you must first put the uGuru
in "ready" mode.

To put the uGuru in ready mode first write 0x00 to DATA and then wait for DATA
to hold 0x09, DATA should read 0x09 within 250 read cycles.

Next CMD _must_ be read and should hold 0xAC, usually CMD will hold 0xAC the
first read but sometimes it takes a while before CMD holds 0xAC and thus it
has to be read a number of times (max 50).

After reading CMD, DATA should hold 0x08 which means that the uGuru is ready
for input. As above DATA will usually hold 0x08 the first read but not always.
This step can be skipped, but it is undetermined what happens if the uGuru has
not yet reported 0x08 at DATA and you proceed with writing a bank address.


Sending bank and sensor addresses to the uGuru
----------------------------------------------

First the uGuru must be in "ready" mode as described above, DATA should hold
0x08 indicating that the uGuru wants input, in this case the bank address.

Next write the bank address to DATA. After the bank address has been written
wait for to DATA to hold 0x08 again indicating that it wants / is ready for
more input (max 250 reads).

Once DATA holds 0x08 again write the sensor address to CMD.

Data read·write cycle과 offline variant

Read는 앞 절의 bank·sensor address 전송 뒤 시작합니다. 읽을 byte마다 DATA가 read-ready를 뜻하는 `0x01`이 될 때까지 최대 250회 기다리고, `0x01`이면 CMD에서 한 byte를 읽습니다.

모든 byte를 읽으면 DATA는 `0x09`가 되지만 굳이 검사할 필요는 없습니다. 읽을 byte 수는 bank address에 따라 달라집니다. 성공적인 read 뒤 uGuru를 다시 ready mode로 돌려놓는 것이 권장됩니다. 그러면 program이나 driver가 unload되었다가 다시 load되어도 detection algorithm이 계속 동작합니다.

Write도 먼저 bank·sensor address를 보냅니다. 쓸 byte마다 DATA가 write-ready를 뜻하는 `0x00`이 될 때까지 최대 250회 기다린 뒤 CMD에 byte를 씁니다.

모든 byte를 쓴 뒤에는 이유가 명확하지 않지만 DATA가 `0x01`이 될 때까지 최대 250회 기다려야 합니다. 그 상태에서 CMD를 읽으면 `0xAC`여야 합니다. 성공적인 write 뒤에도 다음 cycle과 재attach detection을 위해 ready mode로 되돌리는 것이 권장됩니다.

일부 uGuru variant는 bank address를 쓴 뒤 250회 이내에 DATA `0x08`을 반환하지 않는 일이 자주 발생합니다. Timeout을 늘려도 도움이 되지 않으며 내부 calibration 등으로 1~2초 offline 상태가 됩니다. 이 특정 무응답은 잠시 sleep한 뒤 retry하도록 처리해야 합니다.

Reading
-------

First send the bank and sensor addresses as described above.
Then for each byte of data you want to read wait for DATA to hold 0x01
which indicates that the uGuru is ready to be read (max 250 reads) and once
DATA holds 0x01 read the byte from CMD.

Once all bytes have been read data will hold 0x09, but there is no reason to
test for this. Notice that the number of bytes is bank address dependent see
above and below.

After completing a successful read it is advised to put the uGuru back in
ready mode, so that it is ready for the next read / write cycle. This way
if your program / driver is unloaded and later loaded again the detection
algorithm described above will still work.



Writing
-------

First send the bank and sensor addresses as described above.
Then for each byte of data you want to write wait for DATA to hold 0x00
which indicates that the uGuru is ready to be written (max 250 reads) and
once DATA holds 0x00 write the byte to CMD.

Once all bytes have been written wait for DATA to hold 0x01 (max 250 reads)
don't ask why this is the way it is.

Once DATA holds 0x01 read CMD it should hold 0xAC now.

After completing a successful write it is advised to put the uGuru back in
ready mode, so that it is ready for the next read / write cycle. This way
if your program / driver is unloaded and later loaded again the detection
algorithm described above will still work.


Gotchas
-------

After wider testing of the Linux kernel driver some variants of the uGuru have
turned up which do not hold 0x08 at DATA within 250 reads after writing the
bank address. With these versions this happens quite frequent, using larger
timeouts doesn't help, they just go offline for a second or 2, doing some
internal calibration or whatever. Your code should be prepared to handle
this and in case of no response in this specific case just goto sleep for a
while and then retry.

Alarm bank와 Sensor Bank1 reading

Read-only bank `0x20`은 alarm flag를 담습니다. Sensor 수는 0으로 취급되어 sensor address가 무시되지만 반드시 써야 하므로 0을 사용합니다. Payload는 3 bytes입니다.

Byte 0의 각 bit는 Sensor Bank1 sensor 0~7의 alarm flag이고 bit 0이 sensor 0에 대응합니다. Byte 1은 Bank1 sensor 8~15이며 bit 0이 sensor 8에 대응합니다. Byte 2는 Sensor Bank2 sensor 0~5의 alarm flag이며 bit 0이 sensor 0에 대응합니다.

Read-only bank `0x21`은 Sensor Bank1 value를 담습니다. Sensor 16개 각각에 1 byte가 있습니다. 모든 motherboard에서 알려진 항목은 sensor 0 CPU temperature, 1 system temperature, 3 CPU core voltage, 4 DDR voltage, 10 DDR Vtt voltage, 15 PWM temperature입니다.

Bank1 sensor 한 개의 byte 0이 실제 reading입니다. Bank1에는 voltage와 temperature sensor가 섞일 수 있으며 구체적 배치는 motherboard별로 다릅니다. 다만 uGuru에는 연결 sensor 종류가 program되어 있는 것으로 보이며 이는 Bank1 Settings에서 확인할 수 있습니다.

Voltage sensor는 linear scale입니다. Reading 0은 0V, 255는 3494mV입니다. 더 높은 voltage source는 divider circuit을 거치며 알려진 range는 `0-4361mV`, `0-6248mV`, `0-14510mV`입니다. 3.3V source는 4361mV range, 5V는 6248mV, 12V는 14510mV range를 사용합니다.

Temperature sensor도 linear scale이며 reading 0은 0°C, 255는 255°C입니다.

Address Map
===========

Bank 0x20 Alarms (R)
--------------------
This bank contains 0 sensors, iow the sensor address is ignored (but must be
written) just use 0. Bank 0x20 contains 3 bytes:

Byte 0:
  This byte holds the alarm flags for sensor 0-7 of Sensor Bank1, with bit 0
  corresponding to sensor 0, 1 to 1, etc.

Byte 1:
  This byte holds the alarm flags for sensor 8-15 of Sensor Bank1, with bit 0
  corresponding to sensor 8, 1 to 9, etc.

Byte 2:
  This byte holds the alarm flags for sensor 0-5 of Sensor Bank2, with bit 0
  corresponding to sensor 0, 1 to 1, etc.


Bank 0x21 Sensor Bank1 Values / Readings (R)
--------------------------------------------
This bank contains 16 sensors, for each sensor it contains 1 byte.
So far the following sensors are known to be available on all motherboards:

- Sensor  0 CPU temp
- Sensor  1 SYS temp
- Sensor  3 CPU core volt
- Sensor  4 DDR volt
- Sensor 10 DDR Vtt volt
- Sensor 15 PWM temp

Byte 0:
  This byte holds the reading from the sensor. Sensors in Bank1 can be both
  volt and temp sensors, this is motherboard specific. The uGuru however does
  seem to know (be programmed with) what kindoff sensor is attached see Sensor
  Bank1 Settings description.

Volt sensors use a linear scale, a reading 0 corresponds with 0 volt and a
reading of 255 with 3494 mV. The sensors for higher voltages however are
connected through a division circuit. The currently known division circuits
in use result in ranges of: 0-4361mV, 0-6248mV or 0-14510mV. 3.3 volt sources
use the 0-4361mV range, 5 volt the 0-6248mV and 12 volt the 0-14510mV .

Temp sensors also use a linear scale, a reading of 0 corresponds with 0 degree
Celsius and a reading of 255 with a reading of 255 degrees Celsius.

Sensor Bank1 alarm setting

Bank `0x22`는 Sensor Bank1 Settings read address이고 `0x23`은 write address입니다. Sensor 16개 각각에 3 bytes가 있으며 같은 sensor address의 bank `0x21` reading에 대응합니다.

Byte 0은 선택 sensor의 alarm behavior bit field이며 1이 해당 동작을 enable합니다. Bit 0은 temperature가 warning threshold보다 높을 때 alarm, bit 1은 voltage가 max threshold보다 높을 때 alarm, bit 2는 voltage가 min threshold보다 낮을 때 alarm입니다. Bit 3은 alarm beep를 enable합니다.

Bit 4는 현재 alarm 원인이 temperature warning 초과이면 1, bit 5는 voltage max 초과이면 1, bit 6은 voltage min 미만이면 1인 read-only cause flag입니다.

Bit 7은 voltage sensor에서 alarm이 4초 넘게 지속되면 shutdown하도록 하고, temperature sensor에서는 temperature가 shutdown threshold를 넘으면 shutdown하도록 합니다.

Bit 0은 temperature sensor가 연결되었을 때만 uGuru가 사용하고, bit 1·2는 voltage sensor일 때만 사용합니다. 이 차이를 이용하면 어느 sensor 종류가 감지되었는지 알아낼 수 있으며 Linux kernel driver에 자세한 예가 있습니다.

Byte 1은 temperature sensor라면 warning threshold, voltage sensor라면 minimum threshold입니다. Byte 2는 temperature sensor의 shutdown threshold 또는 voltage sensor의 maximum threshold입니다. 두 threshold byte의 scale은 bank `0x21`과 같습니다.

Bank 0x22 Sensor Bank1 Settings (R) and Bank 0x23 Sensor Bank1 Settings (W)
---------------------------------------------------------------------------

Those banks contain 16 sensors, for each sensor it contains 3 bytes. Each
set of 3 bytes contains the settings for the sensor with the same sensor
address in Bank 0x21 .

Byte 0:
  Alarm behaviour for the selected sensor. A 1 enables the described
  behaviour.

Bit 0:
  Give an alarm if measured temp is over the warning threshold                (RW) [1]_

Bit 1:
  Give an alarm if measured volt is over the max threshold                (RW) [2]_

Bit 2:
  Give an alarm if measured volt is under the min threshold                (RW) [2]_

Bit 3:
  Beep if alarm                                                                (RW)

Bit 4:
  1 if alarm cause measured temp is over the warning threshold                (R)

Bit 5:
  1 if alarm cause measured volt is over the max threshold                (R)

Bit 6:
  1 if alarm cause measured volt is under the min threshold                (R)

Bit 7:
  - Volt sensor: Shutdown if alarm persist for more than 4 seconds        (RW)
  - Temp sensor: Shutdown if temp is over the shutdown threshold        (RW)

.. [1] This bit is only honored/used by the uGuru if a temp sensor is connected

.. [2] This bit is only honored/used by the uGuru if a volt sensor is connected
       Note with some trickery this can be used to find out what kinda sensor
       is detected see the Linux kernel driver for an example with many
       comments on how todo this.

Byte 1:
  - Temp sensor: warning threshold  (scale as bank 0x21)
  - Volt sensor: min threshold      (scale as bank 0x21)

Byte 2:
  - Temp sensor: shutdown threshold (scale as bank 0x21)
  - Volt sensor: max threshold      (scale as bank 0x21)

PWM output과 Sensor Bank2 fan setting

Bank `0x24`는 fan PWM output read address이고 `0x25`는 write address입니다. 세 개의 항목이 있으며 각각 5 bytes입니다. Sensor 0은 보통 CPU fan, sensor 1은 NB 또는 single-chip chipset fan, sensor 2는 system fan을 제어합니다.

Byte 0의 flag `0x80`은 control enable입니다. Disable하면 fan은 100%로 돕니다. Low nibble은 control에 사용할 bank `0x21` temperature sensor address입니다.

Byte 1은 low-threshold temperature 아래에서 fan에 줄 voltage이고 byte 2는 high-threshold 위의 voltage입니다. 둘 다 raw 0~255가 0~12V에 선형 대응합니다. Byte 3은 low temperature threshold, byte 4는 high temperature threshold이며 bank `0x21` temperature scale을 사용합니다.

Read-only bank `0x26`은 Sensor Bank2 value를 담으며 알려진 바로는 sensor 6개 각각에 1 byte가 있습니다. 모든 motherboard에서 알려진 sensor는 0 CPU fan speed, 1 NB 또는 chipset fan speed, 2 system fan speed입니다. Raw 0~255는 0~15300에 선형 대응합니다.

Bank `0x27`은 Sensor Bank2 Settings read address이고 `0x28`은 write address입니다. Sensor 6개 각각에 2 bytes가 있습니다. Byte 0 bit 0은 measured RPM이 minimum threshold 아래일 때 alarm, bit 3은 beep, bit 7은 alarm이 4초 넘게 지속될 때 shutdown을 enable합니다. Byte 1은 bank `0x26` scale의 minimum threshold입니다.

Bank 0x24 PWM outputs for FAN's (R) and Bank 0x25 PWM outputs for FAN's (W)
---------------------------------------------------------------------------

Those banks contain 3 "sensors", for each sensor it contains 5 bytes.
  - Sensor 0 usually controls the CPU fan
  - Sensor 1 usually controls the NB (or chipset for single chip) fan
  - Sensor 2 usually controls the System fan

Byte 0:
  Flag 0x80 to enable control, Fan runs at 100% when disabled.
  low nibble (temp)sensor address at bank 0x21 used for control.

Byte 1:
  0-255 = 0-12v (linear), specify voltage at which fan will rotate when under
  low threshold temp (specified in byte 3)

Byte 2:
  0-255 = 0-12v (linear), specify voltage at which fan will rotate when above
  high threshold temp (specified in byte 4)

Byte 3:
  Low threshold temp  (scale as bank 0x21)

byte 4:
  High threshold temp (scale as bank 0x21)


Bank 0x26 Sensors Bank2 Values / Readings (R)
---------------------------------------------

This bank contains 6 sensors (AFAIK), for each sensor it contains 1 byte.

So far the following sensors are known to be available on all motherboards:
  - Sensor 0: CPU fan speed
  - Sensor 1: NB (or chipset for single chip) fan speed
  - Sensor 2: SYS fan speed

Byte 0:
  This byte holds the reading from the sensor. 0-255 = 0-15300 (linear)


Bank 0x27 Sensors Bank2 Settings (R) and Bank 0x28 Sensors Bank2 Settings (W)
-----------------------------------------------------------------------------

Those banks contain 6 sensors (AFAIK), for each sensor it contains 2 bytes.

Byte 0:
  Alarm behaviour for the selected sensor. A 1 enables the described behaviour.

Bit 0:
  Give an alarm if measured rpm is under the min threshold        (RW)

Bit 3:
  Beep if alarm                                                        (RW)

Bit 7:
  Shutdown if alarm persist for more than 4 seconds                (RW)

Byte 1:
  min threshold (scale as bank 0x26)

비 sensor bank 실험 경고

Voltage 또는 clock programming을 알아내려는 실험에는 강한 주의가 필요합니다. 저자는 sensor bank `0x20-0x28`용 read code로 bank `0-0x30`을 읽기만 했는데도 voltage가 영구적으로 재program되는 일을 겪었습니다.

다행히 sensor alarm이 규격 밖 voltage에서 system을 shutdown하도록 설정되어 있어 computer를 보호했고, reboot 직후 BIOS에 들어가 default를 다시 load할 수 있었습니다. 이는 비 sensor 영역의 read/write cycle이 sensor 영역과 다르다는 뜻일 가능성이 큽니다.

Warning for the adventurous
===========================

A word of caution to those who want to experiment and see if they can figure
the voltage / clock programming out, I tried reading and only reading banks
0-0x30 with the reading code used for the sensor banks (0x20-0x28) and this
resulted in a _permanent_ reprogramming of the voltages, luckily I had the
sensors part configured so that it would shutdown my system on any out of spec
voltages which probably safed my computer (after a reboot I managed to
immediately enter the bios and reload the defaults). This probably means that
the read/write cycle for the non sensor part is different from the sensor part.