From 9368c26d1c37d10215e6972aa6652aa562067d41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20J=C3=B6rdens?= <rj@quartiq.de>
Date: Mon, 20 Jan 2020 13:07:20 +0100
Subject: [PATCH] mirny: add to manual

---
 artiq/coredevice/adf5355.py           |  4 ++--
 artiq/coredevice/mirny.py             | 21 ++++++++++++++++++---
 doc/manual/core_drivers_reference.rst | 12 ++++++++++++
 3 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/artiq/coredevice/adf5355.py b/artiq/coredevice/adf5355.py
index 26c71db69..59c3531ff 100644
--- a/artiq/coredevice/adf5355.py
+++ b/artiq/coredevice/adf5355.py
@@ -1,5 +1,5 @@
-""""RTIO driver for the Analog Devices ADF[45]35[56] family of GHz PLLs
-on Mirny-style prefixed SPI buses
+"""RTIO driver for the Analog Devices ADF[45]35[56] family of GHz PLLs
+on Mirny-style prefixed SPI buses.
 """
 
 # https://github.com/analogdevicesinc/linux/blob/master/Documentation/devicetree/bindings/iio/frequency/adf5355.txt
diff --git a/artiq/coredevice/mirny.py b/artiq/coredevice/mirny.py
index f0605eed2..813e72bcb 100644
--- a/artiq/coredevice/mirny.py
+++ b/artiq/coredevice/mirny.py
@@ -1,3 +1,6 @@
+"""RTIO driver for Mirny (4 channel GHz PLLs)
+"""
+
 from artiq.language.core import kernel, delay
 from artiq.language.units import us
 
@@ -17,9 +20,16 @@ SPIT_RD = 16
 
 SPI_CS = 1
 
+WE = 1 << 24
+
+
 class Mirny:
-    WE = 1 << 24
-    kernel_invariants = {"bus", "core", "WE"}
+    """Mirny PLL-based RF generator.
+
+    :param spi_device: SPI bus device
+    :param core_device: Core device name (default: "core")
+    """
+    kernel_invariants = {"bus", "core"}
 
     def __init__(self, dmgr, spi_device, core_device="core"):
         self.core = dmgr.get(core_device)
@@ -27,6 +37,7 @@ class Mirny:
 
     @kernel
     def read_reg(self, addr):
+        """Read a register"""
         self.bus.set_config_mu(SPI_CONFIG | spi.SPI_INPUT | spi.SPI_END, 24,
                                SPIT_RD, SPI_CS)
         self.bus.write((addr << 25))
@@ -34,11 +45,14 @@ class Mirny:
 
     @kernel
     def write_reg(self, addr, data):
+        """Write a register"""
         self.bus.set_config_mu(SPI_CONFIG | spi.SPI_END, 24, SPIT_WR, SPI_CS)
-        self.bus.write((addr << 25) | self.WE | ((data & 0xffff) << 8))
+        self.bus.write((addr << 25) | WE | ((data & 0xffff) << 8))
 
     @kernel
     def init(self):
+        """Initialize Mirny by reading the status register and verifying
+        compatible hardware and protocol revisions"""
         reg0 = self.read_reg(0)
         if reg0 & 0b11 != 0b11:
             raise ValueError("Mirny HW_REV mismatch")
@@ -57,6 +71,7 @@ class Mirny:
 
     @kernel
     def write_ext(self, addr, length, data):
+        """Perform SPI write to a prefixed address"""
         self.bus.set_config_mu(SPI_CONFIG, 8, SPIT_WR, SPI_CS)
         self.bus.write(addr << 25)
         self.bus.set_config_mu(SPI_CONFIG | spi.SPI_END, length,
diff --git a/doc/manual/core_drivers_reference.rst b/doc/manual/core_drivers_reference.rst
index bcdcd1a00..17e4909c9 100644
--- a/doc/manual/core_drivers_reference.rst
+++ b/doc/manual/core_drivers_reference.rst
@@ -99,6 +99,18 @@ RF generation drivers
 .. automodule:: artiq.coredevice.ad9914
     :members:
 
+:mod:`artiq.coredevice.mirny` module
++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: artiq.coredevice.mirny
+    :members:
+
+:mod:`artiq.coredevice.adf5355` module
++++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: artiq.coredevice.adf5355
+    :members:
+
 :mod:`artiq.coredevice.spline` module
 +++++++++++++++++++++++++++++++++++++