From 5099643f84f8413c63f3fa64438ff33227fa496c Mon Sep 17 00:00:00 2001 From: Sebastien Bourdeauducq Date: Tue, 30 Sep 2014 16:42:07 +0800 Subject: [PATCH] devices/rtio_core: rename RTIOCounter to RTIOIn and document --- artiq/devices/rtio_core.py | 64 +++++++++++++++++++++++++++++--- doc/manual/core_reference.rst | 4 +- doc/manual/drivers_reference.rst | 8 ++++ doc/manual/index.rst | 1 + examples/photon_histogram.py | 6 +-- test/full_stack.py | 6 +-- 6 files changed, 76 insertions(+), 13 deletions(-) create mode 100644 doc/manual/drivers_reference.rst diff --git a/artiq/devices/rtio_core.py b/artiq/devices/rtio_core.py index a998629ce..8a646419d 100644 --- a/artiq/devices/rtio_core.py +++ b/artiq/devices/rtio_core.py @@ -26,54 +26,108 @@ class _RTIOBase(AutoContext): class RTIOOut(_RTIOBase): + """RTIO output driver. + + This driver configures the corresponding RTIO channel as output on the core + device and provides functions to set its level. + + This driver supports zero-length transition suppression. For example, if + two pulses are emitted back-to-back with no delay between them, they will + be merged into a single pulse with a duration equal to the sum of the + durations of the original pulses. + + :param core: core device + :param channel: channel number + + """ def build(self): _RTIOBase.build(self) self._set_oe(1) @kernel def sync(self): + """Busy-waits until all programmed level switches have been effected. + + This function is useful to synchronize CPU-controlled devices (such as + the AD9858 DDS bus) with related RTIO controls (such as RF switches at + the output of the DDS). + + """ syscall("rtio_sync", self.channel) @kernel def on(self): + """Sets the output to a logic high state. + + """ self._set_value(1) @kernel def off(self): + """Sets the output to a logic low state. + + """ self._set_value(0) @kernel def pulse(self, duration): + """Pulses the output high for the specified duration. + + """ self.on() delay(duration) self.off() -class RTIOCounter(_RTIOBase): +class RTIOIn(_RTIOBase): + """RTIO input driver. + + This driver configures the corresponding RTIO channel as input on the core + device and provides functions to analyze the incoming signal, with + real-time gating to prevent overflows. + + :param core: core device + :param channel: channel number + + """ def build(self): _RTIOBase.build(self) self._set_oe(0) @kernel - def count_rising(self, duration): + def gate_rising(self, duration): + """Register rising edge events for the specified duration. + + """ self._set_value(1) delay(duration) self._set_value(0) @kernel - def count_falling(self, duration): + def gate_falling(self, duration): + """Register falling edge events for the specified duration. + + """ self._set_value(2) delay(duration) self._set_value(0) @kernel - def count_both_edges(self, duration): + def gate_both(self, duration): + """Register both rising and falling edge events for the specified + duration. + + """ self._set_value(3) delay(duration) self._set_value(0) @kernel - def sync(self): + def count(self): + """Poll the RTIO input during all the previously programmed gate + openings, and returns the number of registered events. + + """ count = 0 while syscall("rtio_get", self.channel) >= 0: count += 1 diff --git a/doc/manual/core_reference.rst b/doc/manual/core_reference.rst index 5d089b25a..11a640fc8 100644 --- a/doc/manual/core_reference.rst +++ b/doc/manual/core_reference.rst @@ -5,10 +5,10 @@ Core language reference --------------------------------- .. automodule:: artiq.language.core - :members: + :members: :mod:`artiq.language.units` module --------------------------------- .. automodule:: artiq.language.units - :members: + :members: diff --git a/doc/manual/drivers_reference.rst b/doc/manual/drivers_reference.rst new file mode 100644 index 000000000..cf133913f --- /dev/null +++ b/doc/manual/drivers_reference.rst @@ -0,0 +1,8 @@ +Drivers reference +================= + +:mod:`artiq.devices.rtio_core` module +------------------------------------- + +.. automodule:: artiq.devices.rtio_core + :members: diff --git a/doc/manual/index.rst b/doc/manual/index.rst index b7774eeb2..cfc04ef52 100644 --- a/doc/manual/index.rst +++ b/doc/manual/index.rst @@ -9,3 +9,4 @@ Contents: installing tutorial core_reference + drivers_reference diff --git a/examples/photon_histogram.py b/examples/photon_histogram.py index 54a61c2c4..ace0b03fa 100644 --- a/examples/photon_histogram.py +++ b/examples/photon_histogram.py @@ -16,10 +16,10 @@ class PhotonHistogram(AutoContext): self.bd.pulse(210*MHz, 100*us) with parallel: self.bd.pulse(220*MHz, 100*us) - self.pmt.count_rising(100*us) + self.pmt.gate_rising(100*us) self.bd.on(200*MHz) self.bdd.on(300*MHz) - return self.pmt.sync() + return self.pmt.count() @kernel def run(self): @@ -44,7 +44,7 @@ if __name__ == "__main__": reg_channel=0, rtio_channel=1), bdd=dds_core.DDS(core=coredev, dds_sysclk=1*GHz, reg_channel=1, rtio_channel=2), - pmt=rtio_core.RTIOCounter(core=coredev, channel=0), + pmt=rtio_core.RTIOIn(core=coredev, channel=0), repeats=100, nbins=100 ) diff --git a/test/full_stack.py b/test/full_stack.py index a3e3839b0..88c029c5c 100644 --- a/test/full_stack.py +++ b/test/full_stack.py @@ -150,8 +150,8 @@ class _RTIOLoopback(AutoContext): for i in range(self.npulses): delay(25*ns) self.o.pulse(25*ns) - self.i.count_rising(10*us) - self.report(self.i.sync()) + self.i.gate_rising(10*us) + self.report(self.i.count()) class _RTIOUnderflow(AutoContext): @@ -171,7 +171,7 @@ class RTIOCase(unittest.TestCase): coredev = core.Core(com) uut = _RTIOLoopback( core=coredev, - i=rtio_core.RTIOCounter(core=coredev, channel=0), + i=rtio_core.RTIOIn(core=coredev, channel=0), o=rtio_core.RTIOOut(core=coredev, channel=1), npulses=npulses )