devices/rtio_core: rename RTIOCounter to RTIOIn and document

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

doc/manual/drivers_reference.rst

@@ -0,0 +1,8 @@
+Drivers reference
+=================
+
+:mod:`artiq.devices.rtio_core` module
+-------------------------------------
+
+.. automodule:: artiq.devices.rtio_core
+    :members:

doc/manual/index.rst

@@ -9,3 +9,4 @@ Contents:
    installing
    tutorial
    core_reference
+   drivers_reference

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
         )

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.i.gate_rising(10*us)
-        self.report(self.i.sync())
+        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
             )