ad53xx improvements (#1445)

* ad53xx: voltage_to_mu() validation & documentation (closes #1443, #1444)
The voltage input (float) is checked for validity. If we need more
speed, we may want to check the DAC-code for over/underflow instead.

Signed-off-by: Marius Weber <marius.weber@physics.ox.ac.uk>

* ad53xx documentation: voltage_to_mu is only valid for 16-bit DACs

Signed-off-by: Marius Weber <marius.weber@physics.ox.ac.uk>

* AD53xx: add voltage_to_mu method (closes #1341)

Signed-off-by: Marius Weber <marius.weber@physics.ox.ac.uk>

* ad53xx: improve voltage_to_mu performance
Interger comparison is faster than floating point math.

Signed-off-by: Marius Weber <marius.weber@physics.ox.ac.uk>

* AD53xx: voltage_to_mu method now uses attribute values

Signed-off-by: Marius Weber <marius.weber@physics.ox.ac.uk>

* Fixup RELEASE_NOTES.rst

Signed-off-by: Marius Weber <marius.weber@physics.ox.ac.uk>

* ad53xx: documentation improvements

voltage_to_mu return value
14-bit DAC support

Signed-off-by: Marius Weber <marius.weber@physics.ox.ac.uk>

RELEASE_NOTES.rst

@@ -11,6 +11,7 @@ Highlights:
 * Performance improvements:
   - #1432: SERDES TTL inputs can now detect edges on pulses that are shorter
     than the RTIO period
+* Zotino now exposes `voltage_to_mu()`
 
 Breaking changes:
 

artiq/coredevice/ad53xx.py

@@ -80,21 +80,30 @@ def ad53xx_cmd_read_ch(channel, op):
     return AD53XX_CMD_SPECIAL | AD53XX_SPECIAL_READ | (op + (channel << 7))
 
 
+# maintain function definition for backward compatibility
 @portable
 def voltage_to_mu(voltage, offset_dacs=0x2000, vref=5.):
-    """Returns the DAC register value required to produce a given output
+    """Returns the 16-bit DAC register value required to produce a given output
     voltage, assuming offset and gain errors have been trimmed out.
 
+    The 16-bit register value may also be used with 14-bit DACs. The additional
+    bits are disregarded by 14-bit DACs.
+
     Also used to return offset register value required to produce a given
     voltage when the DAC register is set to mid-scale.
     An offset of V can be used to trim out a DAC offset error of -V.
 
-    :param voltage: Voltage
+    :param voltage: Voltage in SI units.
+        Valid voltages are: [-2*vref, + 2*vref - 1 LSB] + voltage offset.
     :param offset_dacs: Register value for the two offset DACs
       (default: 0x2000)
     :param vref: DAC reference voltage (default: 5.)
+    :return: The 16-bit DAC register value
     """
-    return int(round(0x10000*(voltage/(4.*vref)) + offset_dacs*0x4))
+    code = int(round((1 << 16) * (voltage / (4. * vref)) + offset_dacs * 0x4))
+    if code < 0x0 or code > 0xffff:
+        raise ValueError("Invalid DAC voltage!")
+    return code
 
 
 class _DummyTTL:
@@ -366,3 +375,17 @@ class AD53xx:
         self.core.break_realtime()
         self.write_offset_mu(channel, 0x8000-offset_err)
         self.write_gain_mu(channel, 0xffff-gain_err)
+
+    @portable
+    def voltage_to_mu(self, voltage):
+        """Returns the 16-bit DAC register value required to produce a given
+        output voltage, assuming offset and gain errors have been trimmed out.
+
+        The 16-bit register value may also be used with 14-bit DACs. The
+        additional bits are disregarded by 14-bit DACs.
+
+        :param voltage: Voltage in SI units.
+            Valid voltages are: [-2*vref, + 2*vref - 1 LSB] + voltage offset.
+        :return: The 16-bit DAC register value
+        """
+        return voltage_to_mu(voltage, self.offset_dacs, self.vref)