hv.spmi: document the other registers

(especially interrupts)

proxyclient/m1n1/hw/spmi.py

@@ -38,11 +38,90 @@ class R_STATUS(Register32):
     TX_EMPTY    = 8
     TX_COUNT    = 7, 0
 
+class IRQs(Register32):
+    RX_DATA     = 0  # there's data in the RX FIFO
+
+    # marked as 'other-interrupts' in ADT
+    READ_FAIL_1 = 6  # read command failed
+    ACK_FAIL    = 7  # command was not ACKed
+    READ_FAIL_2 = 11 # read command failed
+
+    # marked as 'error-interrupts' in ADT
+    UNK_4       = 4
+    UNK_5       = 5
+    UNK_8       = 8
+    UNK_9       = 9
+    UNK_10      = 10
+    UNK_12      = 12
+    UNK_13      = 13
+    UNK_27      = 27 # i've only been able to get this set once, when messing around
+    UNK_16      = 16
+    UNK_17      = 17
+
+    # marked as 'error-interrupts' in ADT, but not settable/seen in T6031
+    #UNK_23      = 23
+    #UNK_24      = 24
+    #UNK_26      = 26
+    #UNK_28      = 28
+    #UNK_29      = 29
+
+class R_COUNTERS(Register32):
+    COUNTER3    = 29, 24
+    COUNTER2    = 21, 16
+    COUNTER1    = 13,  8
+    COUNTER0    =  5,  0
+
 class SPMIRegs(RegMap):
-    STATUS      = 0x00, R_STATUS
-    CMD         = 0x04, R_CMD
-    REPLY       = 0x08, R_REPLY
-    IRQ_FLAG    = 0x80, Register32
+    STATUS            = 0x00, R_STATUS
+    ''' [RO] status about the RX and TX FIFOs '''
+    CMD               = 0x04, R_CMD
+    ''' [WO] write 32 bits to the TX FIFO '''
+    REPLY             = 0x08, R_REPLY
+    ''' [RO] consume 32 bits from the RX FIFO '''
+
+    # setting a bit in one of these registers causes the IRQ line
+    # to be asserted whenever the same bit at the register at
+    # address +0x40 (see below) is set. clearing a bit only masks
+    # the interrupt, but doesn't prevent the bit from being set or
+    # cleared in register +0x40. these are zero on boot.
+    BUS_EVENTS_0_MASK = 0x20, Register32
+    BUS_EVENTS_1_MASK = 0x24, Register32
+    BUS_EVENTS_2_MASK = 0x28, Register32
+    BUS_EVENTS_3_MASK = 0x2c, Register32
+    BUS_EVENTS_4_MASK = 0x30, Register32
+    BUS_EVENTS_5_MASK = 0x34, Register32
+    BUS_EVENTS_6_MASK = 0x38, Register32
+    BUS_EVENTS_7_MASK = 0x3c, Register32
+    IRQ_MASK          = 0x40, IRQs
+
+    # bits in these registers are set in response to an event
+    # and can be cleared by writing a 1 to them. IRQ_FLAG is
+    # for events of the SPMI peripheral itself, while
+    # BUS_EVENTS_* is for generic events that can be triggered
+    # by other devices in the bus using (I presume) master
+    # commands against us, and allow the SPMI peripheral to
+    # also act as an interrupt controller
+    BUS_EVENTS_0_FLAG = 0x60, Register32
+    BUS_EVENTS_1_FLAG = 0x64, Register32
+    BUS_EVENTS_2_FLAG = 0x68, Register32
+    BUS_EVENTS_3_FLAG = 0x6c, Register32
+    BUS_EVENTS_4_FLAG = 0x70, Register32
+    BUS_EVENTS_5_FLAG = 0x74, Register32
+    BUS_EVENTS_6_FLAG = 0x78, Register32
+    BUS_EVENTS_7_FLAG = 0x7c, Register32
+    IRQ_FLAG          = 0x80, IRQs
+
+    CONFIG_0          = 0xa0, Register32
+    ''' [RW] unknown, bits 2..0 settable in T6031, set to 0x6 or 0x7 on boot. master address? '''
+
+    COUNTERS_1        = 0xb0, R_COUNTERS
+    ''' [RO] each of the 4 bytes holds a counter in bits 5..0 '''
+    CONFIG_1          = 0xb4, Register32
+    ''' [RW] unknown, bits 21..16, 8 settable in T6031, set to 0 on boot '''
+    UNK_1             = 0xb8, Register32
+    ''' [RO] unknown, seems to measure a bunch of things, is affected by CONFIG_1 '''
+    STATUS_2          = 0xbc, Register32
+    ''' [RO] only bit 0 seen, seems to indicate inability to talk on the bus '''
 
 class SPMI:
     def __init__(self, u, adt_path):
@@ -73,7 +152,7 @@ def raw_command(self, slave: int, cmd: int, extra=0, data=b"", size=0, active=Tr
         reply = R_REPLY(self.raw_read())
         assert reply.SLAVE_ID == slave and reply.CMD == cmd
         if reply.FRAME_PARITY != (1 << size) - 1:
-            raise Exception(f'some response frames failed parity check: {reply.FRAME_PARITY:b}')
+            raise Exception(f'some response frames were not received correctly: {reply.FRAME_PARITY:b}')
 
         buf = b""
         left = size