fastino: documentation and eem pass-through

* Repeat information about matching log2_width a few times
  in the hope that people read it. #1518
* Pass through log2_width in kasli_generic json. close #1481
* Check DAC value range. #1518

artiq/coredevice/fastino.py

@@ -19,17 +19,17 @@ class Fastino:
     bit using :meth:`set_update`. Update is self-clearing. This enables atomic
     DAC updates synchronized to a frame edge.
 
-    The `log2_width=0` RTIO layout uses one DAC channel per RTIO address
+    The `log2_width=0` RTIO layout uses one DAC channel per RTIO address and a
-    and a dense RTIO address space. The RTIO words are narrow.
+    dense RTIO address space. The RTIO words are narrow. (32 bit) and
-    (32 bit compared to 512) and few-channel updates are efficient.
+    few-channel updates are efficient. There is the least amount of DAC state
-    There is the least amount of DAC state tracking in kernels,
+    tracking in kernels, at the cost of more DMA and RTIO data.
-    at the cost of more DMA and RTIO data.
+    The setting here and in the RTIO PHY (gateware) must match.
 
     Other `log2_width` (up to `log2_width=5`) settings pack multiple
     (in powers of two) DAC channels into one group and into one RTIO write.
     The RTIO data width increases accordingly. The `log2_width`
     LSBs of the RTIO address for a DAC channel write must be zero and the
-    address space is sparse.
+    address space is sparse. For `log2_width=5` the RTIO data is 512 bit wide.
 
     If `log2_width` is zero, the :meth:`set_dac`/:meth:`set_dac_mu` interface
     must be used. If non-zero, the :meth:`set_group`/:meth:`set_group_mu`
@@ -37,9 +37,8 @@ class Fastino:
 
     :param channel: RTIO channel number
     :param core_device: Core device name (default: "core")
-    :param log2_width: Width of DAC channel group (power of two,
+    :param log2_width: Width of DAC channel group (logarithm base 2).
-        see the RTIO PHY for details). Value must match the corresponding value
+        Value must match the corresponding value in the RTIO PHY (gateware).
-        in the RTIO PHY.
     """
     kernel_invariants = {"core", "channel", "width"}
 
@@ -113,7 +112,10 @@ class Fastino:
         :param voltage: Voltage in SI Volts.
         :return: DAC data word in machine units, 16 bit integer.
         """
-        return (int(round((0x8000/10.)*voltage)) + 0x8000) & 0xffff
+        data = int(round((0x8000/10.)*voltage)) + 0x8000
+        if data < 0 or data > 0xffff:
+            raise ValueError("DAC voltage out of bounds")
+        return data
 
     @portable
     def voltage_group_to_mu(self, voltage, data):

artiq/gateware/eem.py

@@ -618,11 +618,11 @@ class Fastino(_EEM):
             ) for pol in "pn"]
 
     @classmethod
-    def add_std(cls, target, eem, iostandard="LVDS_25"):
+    def add_std(cls, target, eem, log2_width, iostandard="LVDS_25"):
         cls.add_extension(target, eem, iostandard=iostandard)
 
         phy = fastino.Fastino(target.platform.request("fastino{}_ser_p".format(eem)),
             target.platform.request("fastino{}_ser_n".format(eem)),
-            log2_width=0)
+            log2_width=log2_width)
         target.submodules += phy
         target.rtio_channels.append(rtio.Channel.from_phy(phy, ififo_depth=4))

artiq/gateware/targets/kasli_generic.py

@@ -109,7 +109,8 @@ def peripheral_mirny(module, peripheral):
 def peripheral_fastino(module, peripheral):
     if len(peripheral["ports"]) != 1:
         raise ValueError("wrong number of ports")
-    eem.Fastino.add_std(module, peripheral["ports"][0])
+    eem.Fastino.add_std(module, peripheral["ports"][0],
+        peripheral.get("log2_width", 0))
 
 
 peripheral_processors = {