From 2770d9c729df0abf0c63283f399e9ec84acad1f7 Mon Sep 17 00:00:00 2001
From: Sebastien Bourdeauducq <sb@m-labs.hk>
Date: Sat, 5 Mar 2016 19:02:03 +0800
Subject: [PATCH] doc: I2C/QC2

---
 artiq/coredevice/i2c.py               | 23 +++++++++++++++++++++++
 doc/manual/core_device.rst            | 20 ++++++++++++++++++++
 doc/manual/core_drivers_reference.rst |  6 ++++++
 3 files changed, 49 insertions(+)

diff --git a/artiq/coredevice/i2c.py b/artiq/coredevice/i2c.py
index 074a9aabe..2f9342ca9 100644
--- a/artiq/coredevice/i2c.py
+++ b/artiq/coredevice/i2c.py
@@ -29,6 +29,11 @@ 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
@@ -36,6 +41,12 @@ class PCA9548:
 
     @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:
@@ -61,6 +72,10 @@ class PCA9548:
 
 
 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
@@ -84,5 +99,13 @@ class TCA6424A:
 
     @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/doc/manual/core_device.rst b/doc/manual/core_device.rst
index c0369b184..c53ccbe23 100644
--- 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
index afc41aee0..e174930e4 100644
--- 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
 -----------------------------------------