From 3aab77d7a0c334094fa063ca407ea139cb9459f6 Mon Sep 17 00:00:00 2001 From: Sebastien Bourdeauducq Date: Sun, 12 Jun 2016 13:05:54 +0800 Subject: [PATCH] doc: precisions about time cursor interaction --- artiq/coredevice/dds.py | 9 ++++- artiq/coredevice/ttl.py | 85 ++++++++++++++++++++++++++++++----------- 2 files changed, 69 insertions(+), 25 deletions(-) diff --git a/artiq/coredevice/dds.py b/artiq/coredevice/dds.py index 9d2fd29e9..fc9952980 100644 --- a/artiq/coredevice/dds.py +++ b/artiq/coredevice/dds.py @@ -65,8 +65,8 @@ class CoreDDS: """Starts a DDS command batch. All DDS commands are buffered after this call, until ``batch_exit`` is called. - The time of execution of the DDS commands is the time of entering the - batch (as closely as hardware permits).""" + The time of execution of the DDS commands is the time cursor position + when the batch is entered.""" dds_batch_enter(now_mu()) @kernel @@ -84,6 +84,8 @@ class _DDSGeneric: This class should not be used directly, instead, use the chip-specific drivers such as ``AD9858`` and ``AD9914``. + The time cursor is not modified by any function in this class. + :param bus: name of the DDS bus device that this DDS is connected to. :param channel: channel number of the DDS device to control. """ @@ -179,6 +181,9 @@ class _DDSGeneric: chip and can be retrieved via the ``pow_width`` attribute. The amplitude width is 12. + The "frequency update" pulse is sent to the DDS with a fixed latency + with respect to the current position of the time cursor. + :param frequency: frequency to generate. :param phase: adds an offset, in turns, to the phase. :param phase_mode: if specified, overrides the default phase mode set diff --git a/artiq/coredevice/ttl.py b/artiq/coredevice/ttl.py index 34c7d1edf..2052e4dc3 100644 --- a/artiq/coredevice/ttl.py +++ b/artiq/coredevice/ttl.py @@ -37,18 +37,26 @@ class TTLOut: @kernel def on(self): - """Sets the output to a logic high state.""" + """Sets the output to a logic high state at the current position + of the time cursor. + + The time cursor is not modified by this function.""" self.set_o(True) @kernel def off(self): - """Set the output to a logic low state.""" + """Set the output to a logic low state at the current position + of the time cursor. + + The time cursor is not modified by this function.""" self.set_o(False) @kernel def pulse_mu(self, duration): """Pulse the output high for the specified duration - (in machine units).""" + (in machine units). + + The time cursor is advanced by the specified duration.""" self.on() delay_mu(duration) self.off() @@ -56,7 +64,9 @@ class TTLOut: @kernel def pulse(self, duration): """Pulse the output high for the specified duration - (in seconds).""" + (in seconds). + + The time cursor is advanced by the specified duration.""" self.on() delay(duration) self.off() @@ -100,7 +110,8 @@ class TTLInOut: @kernel def output(self): - """Set the direction to output. + """Set the direction to output at the current position of the time + cursor. There must be a delay of at least one RTIO clock cycle before any other command can be issued.""" @@ -108,7 +119,8 @@ class TTLInOut: @kernel def input(self): - """Set the direction to input. + """Set the direction to input at the current position of the time + cursor. There must be a delay of at least one RTIO clock cycle before any other command can be issued.""" @@ -128,22 +140,30 @@ class TTLInOut: @kernel def on(self): - """Set the output to a logic high state. + """Set the output to a logic high state at the current position of the + time cursor. - The channel must be in output mode.""" + The channel must be in output mode. + + The time cursor is not modified by this function.""" self.set_o(True) @kernel def off(self): - """Set the output to a logic low state. + """Set the output to a logic low state at the current position of the + time cursor. - The channel must be in output mode.""" + The channel must be in output mode. + + The time cursor is not modified by this function.""" self.set_o(False) @kernel def pulse_mu(self, duration): """Pulses the output high for the specified duration - (in machine units).""" + (in machine units). + + The time cursor is advanced by the specified duration.""" self.on() delay_mu(duration) self.off() @@ -151,7 +171,9 @@ class TTLInOut: @kernel def pulse(self, duration): """Pulses the output high for the specified duration - (in seconds).""" + (in seconds). + + The time cursor is advanced by the specified duration.""" self.on() delay(duration) self.off() @@ -164,7 +186,9 @@ class TTLInOut: @kernel def gate_rising_mu(self, duration): """Register rising edge events for the specified duration - (in machine units).""" + (in machine units). + + The time cursor is advanced by the specified duration.""" self._set_sensitivity(1) delay_mu(duration) self._set_sensitivity(0) @@ -172,7 +196,9 @@ class TTLInOut: @kernel def gate_falling_mu(self, duration): """Register falling edge events for the specified duration - (in machine units).""" + (in machine units). + + The time cursor is advanced by the specified duration.""" self._set_sensitivity(2) delay_mu(duration) self._set_sensitivity(0) @@ -180,7 +206,9 @@ class TTLInOut: @kernel def gate_both_mu(self, duration): """Register both rising and falling edge events for the specified - duration (in machine units).""" + duration (in machine units). + + The time cursor is advanced by the specified duration.""" self._set_sensitivity(3) delay_mu(duration) self._set_sensitivity(0) @@ -188,7 +216,9 @@ class TTLInOut: @kernel def gate_rising(self, duration): """Register rising edge events for the specified duration - (in seconds).""" + (in seconds). + + The time cursor is advanced by the specified duration.""" self._set_sensitivity(1) delay(duration) self._set_sensitivity(0) @@ -196,7 +226,9 @@ class TTLInOut: @kernel def gate_falling(self, duration): """Register falling edge events for the specified duration - (in seconds).""" + (in seconds). + + The time cursor is advanced by the specified duration.""" self._set_sensitivity(2) delay(duration) self._set_sensitivity(0) @@ -204,7 +236,9 @@ class TTLInOut: @kernel def gate_both(self, duration): """Register both rising and falling edge events for the specified - duration (in seconds).""" + duration (in seconds). + + The time cursor is advanced by the specified duration.""" self._set_sensitivity(3) delay(duration) self._set_sensitivity(0) @@ -212,7 +246,9 @@ class TTLInOut: @kernel def count(self): """Poll the RTIO input during all the previously programmed gate - openings, and returns the number of registered events.""" + openings, and returns the number of registered events. + + This function does not interact with the time cursor.""" count = 0 while rtio_input_timestamp(self.i_previous_timestamp, self.channel) >= 0: count += 1 @@ -224,7 +260,8 @@ class TTLInOut: units), according to the gating. If the gate is permanently closed, returns a negative value. - """ + + This function does not interact with the time cursor.""" return rtio_input_timestamp(self.i_previous_timestamp, self.channel) @@ -234,6 +271,8 @@ class TTLClockGen: This should be used with TTL channels that have a clock generator built into the gateware (not compatible with regular TTL channels). + The time cursor is not modified by any function in this class. + :param channel: channel number """ kernel_invariants = {"core", "channel", "acc_width"} @@ -262,7 +301,8 @@ class TTLClockGen: @kernel def set_mu(self, frequency): - """Set the frequency of the clock, in machine units. + """Set the frequency of the clock, in machine units, at the current + position of the time cursor. This also sets the phase, as the time of the first generated rising edge corresponds to the time of the call. @@ -276,8 +316,7 @@ class TTLClockGen: Due to the way the clock generator operates, frequency tuning words that are not powers of two cause jitter of one RTIO clock cycle at the - output. - """ + output.""" rtio_output(now_mu(), self.channel, 0, frequency) self.previous_timestamp = now_mu()