doc: precisions about time cursor interaction

This commit is contained in:
Sebastien Bourdeauducq 2016-06-12 13:05:54 +08:00
parent 7dff446932
commit 3aab77d7a0
2 changed files with 69 additions and 25 deletions

View File

@ -65,8 +65,8 @@ class CoreDDS:
"""Starts a DDS command batch. All DDS commands are buffered """Starts a DDS command batch. All DDS commands are buffered
after this call, until ``batch_exit`` is called. after this call, until ``batch_exit`` is called.
The time of execution of the DDS commands is the time of entering the The time of execution of the DDS commands is the time cursor position
batch (as closely as hardware permits).""" when the batch is entered."""
dds_batch_enter(now_mu()) dds_batch_enter(now_mu())
@kernel @kernel
@ -84,6 +84,8 @@ class _DDSGeneric:
This class should not be used directly, instead, use the chip-specific This class should not be used directly, instead, use the chip-specific
drivers such as ``AD9858`` and ``AD9914``. 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 bus: name of the DDS bus device that this DDS is connected to.
:param channel: channel number of the DDS device to control. :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 chip and can be retrieved via the ``pow_width`` attribute. The amplitude
width is 12. 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 frequency: frequency to generate.
:param phase: adds an offset, in turns, to the phase. :param phase: adds an offset, in turns, to the phase.
:param phase_mode: if specified, overrides the default phase mode set :param phase_mode: if specified, overrides the default phase mode set

View File

@ -37,18 +37,26 @@ class TTLOut:
@kernel @kernel
def on(self): 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) self.set_o(True)
@kernel @kernel
def off(self): 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) self.set_o(False)
@kernel @kernel
def pulse_mu(self, duration): def pulse_mu(self, duration):
"""Pulse the output high for the specified 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() self.on()
delay_mu(duration) delay_mu(duration)
self.off() self.off()
@ -56,7 +64,9 @@ class TTLOut:
@kernel @kernel
def pulse(self, duration): def pulse(self, duration):
"""Pulse the output high for the specified duration """Pulse the output high for the specified duration
(in seconds).""" (in seconds).
The time cursor is advanced by the specified duration."""
self.on() self.on()
delay(duration) delay(duration)
self.off() self.off()
@ -100,7 +110,8 @@ class TTLInOut:
@kernel @kernel
def output(self): 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 There must be a delay of at least one RTIO clock cycle before any
other command can be issued.""" other command can be issued."""
@ -108,7 +119,8 @@ class TTLInOut:
@kernel @kernel
def input(self): 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 There must be a delay of at least one RTIO clock cycle before any
other command can be issued.""" other command can be issued."""
@ -128,22 +140,30 @@ class TTLInOut:
@kernel @kernel
def on(self): 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) self.set_o(True)
@kernel @kernel
def off(self): 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) self.set_o(False)
@kernel @kernel
def pulse_mu(self, duration): def pulse_mu(self, duration):
"""Pulses the output high for the specified 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() self.on()
delay_mu(duration) delay_mu(duration)
self.off() self.off()
@ -151,7 +171,9 @@ class TTLInOut:
@kernel @kernel
def pulse(self, duration): def pulse(self, duration):
"""Pulses the output high for the specified duration """Pulses the output high for the specified duration
(in seconds).""" (in seconds).
The time cursor is advanced by the specified duration."""
self.on() self.on()
delay(duration) delay(duration)
self.off() self.off()
@ -164,7 +186,9 @@ class TTLInOut:
@kernel @kernel
def gate_rising_mu(self, duration): def gate_rising_mu(self, duration):
"""Register rising edge events for the specified 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) self._set_sensitivity(1)
delay_mu(duration) delay_mu(duration)
self._set_sensitivity(0) self._set_sensitivity(0)
@ -172,7 +196,9 @@ class TTLInOut:
@kernel @kernel
def gate_falling_mu(self, duration): def gate_falling_mu(self, duration):
"""Register falling edge events for the specified 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) self._set_sensitivity(2)
delay_mu(duration) delay_mu(duration)
self._set_sensitivity(0) self._set_sensitivity(0)
@ -180,7 +206,9 @@ class TTLInOut:
@kernel @kernel
def gate_both_mu(self, duration): def gate_both_mu(self, duration):
"""Register both rising and falling edge events for the specified """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) self._set_sensitivity(3)
delay_mu(duration) delay_mu(duration)
self._set_sensitivity(0) self._set_sensitivity(0)
@ -188,7 +216,9 @@ class TTLInOut:
@kernel @kernel
def gate_rising(self, duration): def gate_rising(self, duration):
"""Register rising edge events for the specified 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) self._set_sensitivity(1)
delay(duration) delay(duration)
self._set_sensitivity(0) self._set_sensitivity(0)
@ -196,7 +226,9 @@ class TTLInOut:
@kernel @kernel
def gate_falling(self, duration): def gate_falling(self, duration):
"""Register falling edge events for the specified 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) self._set_sensitivity(2)
delay(duration) delay(duration)
self._set_sensitivity(0) self._set_sensitivity(0)
@ -204,7 +236,9 @@ class TTLInOut:
@kernel @kernel
def gate_both(self, duration): def gate_both(self, duration):
"""Register both rising and falling edge events for the specified """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) self._set_sensitivity(3)
delay(duration) delay(duration)
self._set_sensitivity(0) self._set_sensitivity(0)
@ -212,7 +246,9 @@ class TTLInOut:
@kernel @kernel
def count(self): def count(self):
"""Poll the RTIO input during all the previously programmed gate """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 count = 0
while rtio_input_timestamp(self.i_previous_timestamp, self.channel) >= 0: while rtio_input_timestamp(self.i_previous_timestamp, self.channel) >= 0:
count += 1 count += 1
@ -224,7 +260,8 @@ class TTLInOut:
units), according to the gating. units), according to the gating.
If the gate is permanently closed, returns a negative value. 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) 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 This should be used with TTL channels that have a clock generator
built into the gateware (not compatible with regular TTL channels). 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 :param channel: channel number
""" """
kernel_invariants = {"core", "channel", "acc_width"} kernel_invariants = {"core", "channel", "acc_width"}
@ -262,7 +301,8 @@ class TTLClockGen:
@kernel @kernel
def set_mu(self, frequency): 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 This also sets the phase, as the time of the first generated rising
edge corresponds to the time of the call. 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 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 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) rtio_output(now_mu(), self.channel, 0, frequency)
self.previous_timestamp = now_mu() self.previous_timestamp = now_mu()