From cfe1f56f733988e9b5c25306812326e3abbeb85e Mon Sep 17 00:00:00 2001
From: hartytp <thomas.harty@physics.ox.ac.uk>
Date: Fri, 17 May 2019 16:12:35 +0100
Subject: [PATCH] suservo: add some more comments to the RTServoMem to clarify
 the RTIO interface (#1323)

---
 artiq/gateware/rtio/phy/servo.py | 28 +++++++++++++++++++++++++---
 artiq/gateware/suservo/iir.py    |  2 +-
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/artiq/gateware/rtio/phy/servo.py b/artiq/gateware/rtio/phy/servo.py
index bebbabada..886b2afb5 100644
--- a/artiq/gateware/rtio/phy/servo.py
+++ b/artiq/gateware/rtio/phy/servo.py
@@ -25,7 +25,31 @@ class RTServoCtrl(Module):
 
 class RTServoMem(Module):
     """All-channel all-profile coefficient and state RTIO control
-    interface."""
+    interface.
+
+    Servo internal addresses are internal_address_width wide, which is
+    typically longer than the 8-bit RIO address space. We pack the overflow
+    onto the RTIO data word after the data.
+
+    Servo address space (from LSB):
+      - IIR coefficient/state memory address, (w.profile + w.channel + 2) bits.
+        If the state memory is selected, the lower bits are used directly as
+        the memory address. If the coefficient memory is selected, the LSB
+        (high_coeff) selects between the upper and lower halves of the memory
+        location, which is two coefficients wide, with the remaining bits used
+        as the memory address.
+      - config_sel (1 bit)
+      - state_sel (1 bit)
+      - we (1 bit)
+
+     destination    | config_sel | state_sel
+    ----------------|------------|----------
+     IIR coeff mem  |    0       |   0
+     IIR coeff mem  |    1       |   0
+     IIR state mem  |    0       |   1
+     config (write) |    1       |   1
+     status (read)  |    1       |   1
+    """
     def __init__(self, w, servo):
         m_coeff = servo.iir.m_coeff.get_port(write_capable=True,
                 mode=READ_FIRST,
@@ -44,8 +68,6 @@ class RTServoMem(Module):
         assert w.coeff >= w.word
 
         # coeff, profile, channel, 2 mems, rw
-        # this exceeds the 8-bit RTIO address, so we move the extra ("overflow")
-        # address bits into data.
         internal_address_width = 3 + w.profile + w.channel + 1 + 1
         rtlink_address_width = min(8, internal_address_width)
         overflow_address_width = internal_address_width - rtlink_address_width
diff --git a/artiq/gateware/suservo/iir.py b/artiq/gateware/suservo/iir.py
index ba00dd97e..f82c502b1 100644
--- a/artiq/gateware/suservo/iir.py
+++ b/artiq/gateware/suservo/iir.py
@@ -127,7 +127,7 @@ class IIR(Module):
     Each profile stores 8 values, each up to W.coeff bits wide, arranged as:
         [FTW1, B1, POW, CFG, OFFSET, A1, FTW0, B0]
     The lower 8 bits of CFG hold the ADC input channel index SEL.
-    The bits from bit 8 up hold the IIR activation delay DLY.
+    The subsequent 8 bits hold the IIR activation delay DLY.
     The back memory is 2*W.coeff bits wide and each value pair
     (even and odd address)
     are stored in a single location with the odd address value occupying the