coredevice: Add _mu suffix to AD991x ref_time arguments

GitHub: Fixes #1243.

RELEASE_NOTES.rst

@@ -8,6 +8,11 @@ ARTIQ-5
 
 5.0
 ***
+
+* The :class:`~artiq.coredevice.ad9910.AD9910` and
+  :class:`~artiq.coredevice.ad9914.AD9914` phase reference timestamp parameters
+  have been renamed to ``ref_time_mu`` for consistency, as they are in machine
+  units.
 * :func:`~artiq.tools.verbosity_args` renamed to :func:`~artiq.tools.add_common_args`. New feature: adds an option to print the ARTIQ version.
 
 

artiq/coredevice/ad9910.py

@@ -371,11 +371,11 @@ class AD9910:
         self.set_cfr1(power_down=bits)
         self.cpld.io_update.pulse(1*us)
 
-    # KLUDGE: ref_time default argument is explicitly marked int64() to avoid
+    # KLUDGE: ref_time_mu default argument is explicitly marked int64() to avoid
     # silent truncation of explicitly passed timestamps. (Compiler bug?)
     @kernel
     def set_mu(self, ftw, pow_=0, asf=0x3fff, phase_mode=_PHASE_MODE_DEFAULT,
-               ref_time=int64(-1), profile=0):
+               ref_time_mu=int64(-1), profile=0):
         """Set profile 0 data in machine units.
 
         This uses machine units (FTW, POW, ASF). The frequency tuning word
@@ -393,7 +393,7 @@ class AD9910:
         :param asf: Amplitude scale factor: 14 bit unsigned.
         :param phase_mode: If specified, overrides the default phase mode set
             by :meth:`set_phase_mode` for this call.
-        :param ref_time: Fiducial time used to compute absolute or tracking
+        :param ref_time_mu: Fiducial time used to compute absolute or tracking
             phase updates. In machine units as obtained by `now_mu()`.
         :param profile: Profile number to set (0-7, default: 0).
         :return: Resulting phase offset word after application of phase
@@ -409,14 +409,14 @@ class AD9910:
             # Auto-clear phase accumulator on IO_UPDATE.
             # This is active already for the next IO_UPDATE
             self.set_cfr1(phase_autoclear=1)
-            if phase_mode == PHASE_MODE_TRACKING and ref_time < 0:
+            if phase_mode == PHASE_MODE_TRACKING and ref_time_mu < 0:
                 # set default fiducial time stamp
-                ref_time = 0
+                ref_time_mu = 0
-            if ref_time >= 0:
+            if ref_time_mu >= 0:
                 # 32 LSB are sufficient.
                 # Also no need to use IO_UPDATE time as this
                 # is equivalent to an output pipeline latency.
-                dt = int32(now_mu()) - int32(ref_time)
+                dt = int32(now_mu()) - int32(ref_time_mu)
                 pow_ += dt*ftw*self.sysclk_per_mu >> 16
         self.write64(_AD9910_REG_PROFILE0 + profile,
             (asf << 16) | (pow_ & 0xffff), ftw)
@@ -516,7 +516,7 @@ class AD9910:
 
     @kernel
     def set(self, frequency, phase=0.0, amplitude=1.0,
-            phase_mode=_PHASE_MODE_DEFAULT, ref_time=int64(-1), profile=0):
+            phase_mode=_PHASE_MODE_DEFAULT, ref_time_mu=int64(-1), profile=0):
         """Set profile 0 data in SI units.
 
         .. seealso:: :meth:`set_mu`
@@ -525,13 +525,13 @@ class AD9910:
         :param phase: Phase tuning word in turns
         :param amplitude: Amplitude in units of full scale
         :param phase_mode: Phase mode constant
-        :param ref_time: Fiducial time stamp in machine units
+        :param ref_time_mu: Fiducial time stamp in machine units
         :param profile: Profile to affect
         :return: Resulting phase offset in turns
         """
         return self.pow_to_turns(self.set_mu(
             self.frequency_to_ftw(frequency), self.turns_to_pow(phase),
-            self.amplitude_to_asf(amplitude), phase_mode, ref_time, profile))
+            self.amplitude_to_asf(amplitude), phase_mode, ref_time_mu, profile))
 
     @kernel
     def set_att_mu(self, att):

artiq/coredevice/ad9914.py

@@ -182,7 +182,7 @@ class AD9914:
 
     @kernel
     def set_mu(self, ftw, pow=0, phase_mode=_PHASE_MODE_DEFAULT,
-               asf=0x0fff, ref_time=-1):
+               asf=0x0fff, ref_time_mu=-1):
         """Sets the DDS channel to the specified frequency and phase.
 
         This uses machine units (FTW and POW). The frequency tuning word width
@@ -196,7 +196,7 @@ class AD9914:
         :param pow: adds an offset to the phase.
         :param phase_mode: if specified, overrides the default phase mode set
             by :meth:`set_phase_mode` for this call.
-        :param ref_time: reference time used to compute phase. Specifying this
+        :param ref_time_mu: reference time used to compute phase. Specifying this
             makes it easier to have a well-defined phase relationship between
             DDSes on the same bus that are updated at a similar time.
         :return: Resulting phase offset word after application of phase
@@ -205,8 +205,8 @@ class AD9914:
         """
         if phase_mode == _PHASE_MODE_DEFAULT:
             phase_mode = self.phase_mode
-        if ref_time < 0:
+        if ref_time_mu < 0:
-            ref_time = now_mu()
+            ref_time_mu = now_mu()
         delay_mu(-self.set_duration_mu)
 
         self.write(AD9914_GPIO,      (1 << self.channel) << 1)
@@ -225,9 +225,9 @@ class AD9914:
             # Enable autoclear phase accumulator and enables OSK.
             self.write(AD9914_REG_CFR1L, 0x2108)
             fud_time = now_mu() + 2 * self.write_duration_mu
-            pow -= int32((ref_time - fud_time) * self.sysclk_per_mu * ftw >> (32 - 16))
+            pow -= int32((ref_time_mu - fud_time) * self.sysclk_per_mu * ftw >> (32 - 16))
             if phase_mode == PHASE_MODE_TRACKING:
-                pow += int32(ref_time * self.sysclk_per_mu * ftw >> (32 - 16))
+                pow += int32(ref_time_mu * self.sysclk_per_mu * ftw >> (32 - 16))
 
         self.write(AD9914_REG_POW,  pow)
         self.write(AD9914_REG_ASF,  asf)