m-labs · Mar 5, 2016 · Mar 5, 2016 · Mar 5, 2016 · Mar 5, 2016
Showing with 94 additions and 1 deletion.

+36 −0 artiq/coredevice/i2c.py

+1 −1 artiq/runtime/i2c.c

+25 −0 artiq/test/coredevice/test_i2c.py

+20 −0 doc/manual/core_device.rst

+6 −0 doc/manual/core_drivers_reference.rst

+6 −0 examples/master/device_db.pyon
diff --git a/artiq/coredevice/i2c.py b/artiq/coredevice/i2c.py
@@ -29,13 +29,24 @@ def i2c_read(busno: TInt32, ack: TBool) -> TInt32:
 
 
 class PCA9548:
+    """Driver for the PCA9548 I2C bus switch.
+
+    On the KC705, this chip is used for selecting the I2C buses on the two FMC
+    connectors. HPC=1, LPC=2.
+    """
     def __init__(self, dmgr, busno=0, address=0xe8):
         self.core = dmgr.get("core")
         self.busno = busno
         self.address = address
 
     @kernel
     def set(self, channel):
+        """Select one channel.
+
+        Selecting multiple channels is not supported by this driver.
+
+        :param channel: channel number (0-7)
+        """
         i2c_init(self.busno)
         i2c_start(self.busno)
         try:
@@ -46,8 +57,25 @@ def set(self, channel):
         finally:
             i2c_stop(self.busno)
 
+    @kernel
+    def readback(self):
+        i2c_init(self.busno)
+        i2c_start(self.busno)
+        r = 0
+        try:
+            if not i2c_write(self.busno, self.address | 1):
+                raise I2CError("PCA9548 failed to ack address")
+            r = i2c_read(self.busno, False)
+        finally:
+            i2c_stop(self.busno)
+        return r
+
 
 class TCA6424A:
+    """Driver for the TCA6424A I2C I/O expander.
+
+    On the NIST QC2 hardware, this chip is used for switching the directions
+    of TTL buffers."""
     def __init__(self, dmgr, busno=0, address=0x44):
         self.core = dmgr.get("core")
         self.busno = busno
@@ -71,5 +99,13 @@ def _write24(self, command, value):
 
     @kernel
     def set(self, outputs):
+        """Drive all pins of the chip to the levels given by the
+        specified 24-bit word.
+
+        On the QC2 hardware, the LSB of the word determines the direction of
+        TTL0 (on a given FMC card) and the MSB that of TTL23.
+
+        A bit set to 1 means the TTL is an output.
+        """
         self._write24(0x8c, 0)  # set all directions to output
         self._write24(0x84, output)  # set levels
diff --git a/artiq/runtime/i2c.c b/artiq/runtime/i2c.c
@@ -160,7 +160,7 @@ int i2c_write(int busno, int b)
 int i2c_read(int busno, int ack)
 {
     int i;
-    char b;
+    unsigned char b;
 
     /* Set SCL low first, otherwise setting SDA as input may cause a transition
      * on SDA with SCL high which will be interpreted as START/STOP condition.

diff --git a/artiq/test/coredevice/test_i2c.py b/artiq/test/coredevice/test_i2c.py
@@ -0,0 +1,25 @@
+import os, unittest
+
+from artiq.experiment import *
+from artiq.test.hardware_testbench import ExperimentCase
+
+
+class I2CSwitch(EnvExperiment):
+    def build(self):
+        self.setattr_device("core")
+        self.setattr_device("i2c_switch")
+
+    @kernel
+    def run(self):
+        passed = True
+        for i in range(8):
+            self.i2c_switch.set(i)
+            if self.i2c_switch.readback() != 1 << i:
+                passed = False
+        self.set_dataset("passed", passed)
+
+
+class I2CTest(ExperimentCase):
+    def test_i2c_switch(self):
+        self.execute(I2CSwitch)
+        self.assertTrue(self.dataset_mgr.get("passed"))
diff --git a/doc/manual/core_device.rst b/doc/manual/core_device.rst
@@ -29,6 +29,9 @@ KC705
 
 The main target board for the ARTIQ core device is the KC705 development board from Xilinx. It supports the NIST QC1 hardware via an adapter, and the NIST CLOCK and QC2 hardware (FMC).
 
+NIST QC1
+++++++++
+
 With the QC1 hardware, the TTL lines are mapped as follows:
 
 +--------------+------------+--------------+
@@ -47,6 +50,9 @@ With the QC1 hardware, the TTL lines are mapped as follows:
 | 19           | TTL15      | Clock        |
 +--------------+------------+--------------+
 
+NIST CLOCK
+++++++++++
+
 With the CLOCK hardware, the TTL lines are mapped as follows:
 
 +--------------------+-----------------------+--------------+
@@ -70,6 +76,20 @@ With the CLOCK hardware, the TTL lines are mapped as follows:
 +--------------------+-----------------------+--------------+
 
 
+NIST QC2
+++++++++
+
+With the QC2 hardware, the TTL lines are mapped as follows:
+
+TODO
+
+The QC2 hardware uses TCA6424A I2C I/O expanders to define the directions of its TTL buffers. There is one such expander per FMC card, and they are selected using the PCA9548 on the KC705.
+
+To avoid I/O contention, the startup kernel should first program the TCA6424A expanders and then call ``output()`` on all ``TTLInOut`` channels that should be configured as outputs.
+
+See :mod:`artiq.coredevice.i2c` for more details.
+
+
 Pipistrello
 -----------
 

diff --git a/doc/manual/core_drivers_reference.rst b/doc/manual/core_drivers_reference.rst
@@ -36,6 +36,12 @@ These drivers are for the core device and the peripherals closely integrated int
 .. automodule:: artiq.coredevice.ad5360
     :members:
 
+:mod:`artiq.coredevice.i2c` module
+----------------------------------
+
+.. automodule:: artiq.coredevice.i2c
+    :members:
+
 :mod:`artiq.coredevice.exceptions` module
 -----------------------------------------
 

diff --git a/examples/master/device_db.pyon b/examples/master/device_db.pyon
@@ -15,6 +15,12 @@
         "arguments": {"ref_period": 1e-9}
     },
 
+    "i2c_switch": {
+        "type": "local",
+        "module": "artiq.coredevice.i2c",
+        "class": "PCA9548"
+    },
+
     "ttl0": {
         "type": "local",
         "module": "artiq.coredevice.ttl",