m-labs · Sep 29, 2014 · Sep 30, 2014 · Sep 30, 2014 · Sep 30, 2014
diff --git a/artiq/devices/rtio_core.py b/artiq/devices/rtio_core.py
@@ -26,54 +26,108 @@ def _set_value(self, value):
 
 
 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/artiq/language/core.py b/artiq/language/core.py
@@ -2,6 +2,7 @@
 
 from collections import namedtuple as _namedtuple
 from copy import copy as _copy
+from functools import wraps as _wraps
 
 
 class int64(int):
@@ -104,10 +105,10 @@ class AutoContext:
     At the top-level, it is possible to have a MVS that issues requests to a
     database and hardware management system.
 
-    :param parameters: A string containing the parameters that the object must
+    :var parameters: A string containing the parameters that the object must
         have. It must be a space-separated list of valid Python identifiers.
         Default: empty.
-    :param implicit_core: Automatically adds ``core`` to the parameter list.
+    :var implicit_core: Automatically adds ``core`` to the parameter list.
         Default: True.
 
     Example:
@@ -204,13 +205,15 @@ def kernel(arg):
     """
     if isinstance(arg, str):
         def real_decorator(k_function):
+            @_wraps(k_function)
             def run_on_core(exp, *k_args, **k_kwargs):
                 getattr(exp, arg).run(k_function, ((exp,) + k_args), k_kwargs)
             run_on_core.k_function_info = _KernelFunctionInfo(
                 core_name=arg, k_function=k_function)
             return run_on_core
         return real_decorator
     else:
+        @_wraps(arg)
         def run_on_core(exp, *k_args, **k_kwargs):
             exp.core.run(arg, ((exp,) + k_args), k_kwargs)
         run_on_core.k_function_info = _KernelFunctionInfo(

diff --git a/artiq/transforms/inline.py b/artiq/transforms/inline.py
@@ -218,6 +218,10 @@ def visit_Return(self, node):
             node)
 
     def visit_Expr(self, node):
+        if isinstance(node.value, ast.Str):
+            # Strip docstrings. This also removes strings appearing in the
+            # middle of the code, but they are nops.
+            return None
         self.generic_visit(node)
         if isinstance(node.value, ast.Name):
             # Remove Expr nodes that contain only a name, likely due to

diff --git 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
@@ -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
@@ -9,3 +9,4 @@ Contents:
    installing
    tutorial
    core_reference
+   drivers_reference
diff --git a/examples/photon_histogram.py b/examples/photon_histogram.py
@@ -16,10 +16,10 @@ def cool_detect(self):
         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 @@ def run(self):
                             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
@@ -150,8 +150,8 @@ def run(self):
                 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 @@ def test_loopback(self):
             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
             )