doc: document core device driver. Closes #119

m-labs · Oct 6, 2015 · 5f89d1a · 5f89d1a
1 parent 3cf5366
commit 5f89d1a
Showing 2 changed files with 24 additions and 3 deletions.
diff --git a/artiq/coredevice/core.py b/artiq/coredevice/core.py
@@ -46,10 +46,22 @@ def _no_debug_unparse(label, node):
 
 
 class Core:
-    def __init__(self, dmgr, ref_period=8*ns, external_clock=False):
-        self.comm = dmgr.get("comm")
+    """Core device driver.
+
+    :param ref_period: period of the reference clock for the RTIO subsystem.
+        On platforms that use clock multiplication and SERDES-based PHYs,
+        this is the period after multiplication. For example, with a RTIO core
+        clocked at 125MHz and a SERDES multiplication factor of 8, the
+        reference period is 1ns.
+        The time machine unit is equal to this period.
+    :param external_clock: whether the core device should switch to its
+        external RTIO clock input instead of using its internal oscillator.
+    :param comm_device: name of the device used for communications.
+    """
+    def __init__(self, dmgr, ref_period=8*ns, external_clock=False, comm_device="comm"):
         self.ref_period = ref_period
         self.external_clock = external_clock
+        self.comm = dmgr.get(comm_device)
 
         self.first_run = True
         self.core = self
@@ -120,10 +132,13 @@ def run(self, k_function, k_args, k_kwargs):
 
     @kernel
     def get_rtio_counter_mu(self):
+        """Return the current value of the hardware RTIO counter."""
         return syscall("rtio_get_counter")
 
     @kernel
     def break_realtime(self):
+        """Set the timeline to the current value of the hardware RTIO counter
+        plus a margin of 125000 machine units."""
         min_now = syscall("rtio_get_counter") + 125000
         if now_mu() < min_now:
             at_mu(min_now)
diff --git a/doc/manual/core_drivers_reference.rst b/doc/manual/core_drivers_reference.rst
@@ -1,7 +1,13 @@
 Core drivers reference
 ======================
 
-These drivers are for peripherals closely integrated into the core device, which do not use the controller mechanism.
+These drivers are for the core device and the peripherals closely integrated into it, which do not use the controller mechanism.
+
+:mod:`artiq.coredevice.core` module
+-----------------------------------
+
+.. automodule:: artiq.coredevice.core
+    :members:
 
 :mod:`artiq.coredevice.ttl` module
 -----------------------------------