Wiitek vendor doc converted to English markdown: A2 Table 3 I2C-to-MDIO mailbox spec (official RollBall protocol confirmation) plus A2.250 part number and A2.120 link rate; embedded Visio register-map figure transcribed via libvisio

docs/modules/wiitek/10gbase-t-phy-register-operation.md

@@ -0,0 +1,68 @@
+# 10GBASE-T module PHY Register Access
+
+Converted from the Wiitek-provided Word file `10GBase-T PHY Register Operation .doc` in this directory (vendor document, last saved 2018-11-07). The original is bilingual, an English section and a Chinese section covering the same protocol; this document merges them, translated to English. Details that appear only in the Chinese section are folded in: the password is called PW2 and 0xFF 0xFF 0xFF 0xFF is the Wiitek (源拓) factory default, and the A2.120 link-rate register at the end is Chinese-section-only.
+
+A bridge from I2C to MDIO is designed into the 10GBASE-T module. The PHY's registers can be indirectly accessed through a set of I2C registers in A2 Table 3.
+
+## Register map
+
+The original "I2C table" is a Visio figure (identical in both sections): a box "switch table: A2.127 == 3" with an arrow labeled PW2 pointing into a "Table 3" stack of six registers, addressed 128–133, followed by "………" (further registers not shown):
+
+| A2 (Table 3) address | Field | Meaning |
+|---|---|---|
+| 128 | CMD | 0: idle; 1: write operation; 2: read operation; 3: operation in progress; 4: operation completed |
+| 129 | Device Addr | MDIO device address |
+| 130 | Reg High | MDIO register address, high byte |
+| 131 | Reg Low | MDIO register address, low byte |
+| 132 | Value High | MDIO data, high byte |
+| 133 | Value Low | MDIO data, low byte |
+
+Before accessing these indirect-control registers, switch tables by setting A2.127 = 3, then write the 4-byte PW2 password to A2.123~A2.126 to obtain PW2 permission. The Wiitek factory default password is 0xFF 0xFF 0xFF 0xFF.
+
+## Write operation (Device: 0x01, Register: 0xC001, value: 0xAA55)
+
+1. Change to Table 3: set A2.127 = 3
+2. Write password: set A2.123~A2.126 = 0xFF 0xFF 0xFF 0xFF
+3. Set MDIO device address: set A2.129 = 0x01
+4. Set MDIO register address high: set A2.130 = 0xC0
+5. Set MDIO register address low: set A2.131 = 0x01
+6. Set MDIO register data high: set A2.132 = 0xAA
+7. Set MDIO register data low: set A2.133 = 0x55
+8. Execute write operation: set A2.128 = 0x01
+9. Check A2.128 until the operation is completed (A2.128 = 0x4)
+
+## Read operation (Device: 1, Register: 0xC001)
+
+1. Change to Table 3: set A2.127 = 3
+2. Write password: set A2.123~A2.126 = 0xFF 0xFF 0xFF 0xFF
+3. Set MDIO device address: set A2.129 = 0x01
+4. Set MDIO register address high: set A2.130 = 0xC0
+5. Set MDIO register address low: set A2.131 = 0x01
+6. Execute read operation: set A2.128 = 0x02
+7. Check A2.128 until the operation is completed (A2.128 = 0x4)
+8. Get MDIO register data high: read A2.132
+9. Get MDIO register data low: read A2.133
+
+The Chinese section states the results explicitly: after CMD reads 4, A2.132 and A2.133 are the high and low bytes of register 1.0xC001.
+
+## PHY part number
+
+The part number of the PHY in the module can be read from I2C register A2.250 in Table 3:
+
+1. Change to Table 3: set A2.127 = 3
+2. Write password: set A2.123~A2.126 = 0xFF 0xFF 0xFF 0xFF
+3. Read A2.250. Value = 1: MV_88X3310; other values: to be defined in the future
+
+## Link rate (A2.120)
+
+Reads the copper-port link rate. Present on AQR and RTL8221 modules, and on firmware 377 v4.5 or later. (Chinese section only.)
+
+| Value | Rate |
+|---|---|
+| 0x0 | link down |
+| 0x1 | 100BASE-T |
+| 0x2 | 1000BASE-T |
+| 0x3 | 10G |
+| 0x4 | 2.5G |
+| 0x5 | 5G |
+| 0xA | 10M |

docs/modules/wiitek/README.md

@@ -45,3 +45,5 @@ Routes that do not risk the module:
 2. **Deliberate sacrifice** of a spare to test the QCA-CDT-start hypothesis, `rb_forensic.py` running — only if the capability is judged worth a module.
 
 The Marvell 88E151x datasheet PDF in this directory is family reference material.
+
+[10gbase-t-phy-register-operation.md](10gbase-t-phy-register-operation.md) (converted from the vendor `.doc` alongside it) is Wiitek's own spec of the A2 Table 3 I2C→MDIO mailbox — official confirmation of the RollBall protocol this project drives (A2.127=3 table switch, PW2 password at A2.123–126, CMD states at A2.128). It also documents two registers not covered elsewhere: A2.250 (PHY part number, 1 = 88X3310) and A2.120 (copper link rate; vendor-gated to AQR/RTL8221/firmware 377 v4.5+, unverified on the Marvell CUX3610 units).