add songbird

src/hw/songbird.md

@@ -0,0 +1,107 @@
+# Songbird DDS
+
+## JSON
+
+```json
+{
+   "type": "songbird",
+   "ports": [<port num>],
+   "drtio_destination": <drtio destination>  // optional
+}
+```
+
+## Assembly
+
+Songbird uses the Analog Devices DC2303-A demo board, which is built around the LTC2000 DAC.
+
+To work with the EFC, it must be configured:
+1. Power: either provide 5V from an external, low-noise power supply to the on-board turrets, or to use 12V from the FMC connector, short **L6** or include a properly spec 0603 power inductor if power dropout issue is experienced.
+2. Jumpers: **JP1** must be in **RUN** position to enable the DAC, **JP2** in **WP** position.
+3. 2.5GHz Sample clock (SMA port marked **J4 CK**): must be provided. More on that in the [section below](#ltc2000-sample-clock).
+
+## Setup
+
+### Building
+
+```
+python -m artiq.gateware.targets.efc [--efc-hw-rev v1.0] songbird
+```
+
+Provide the EFC hardware revision if necessary.
+
+### Flashing
+
+Config erase steps are common with [Shuttler](shuttler.md). Check them out first if you need to.
+
+Connect the Digilent HS2 JTAG adapter to the JTAG port on the EFC. Flash with:
+
+```
+artiq_flash -t {efc1v0, efc1v1} --srcbuild -d artiq_efc/songbird/
+```
+
+Choose the board type appropriately. 
+
+### EFC UART log access
+
+UART is exposed as 4 pin header **W3** on the EFC board next to the power status LEDs. You can use an USB UART adapter to such as an FTDI FT232H to connect to PC.
+
+### EEM Cable Connection
+
+Only the EEM0 port on the EFC board is used. The EEM Cable provides power. You can ignore the barrel jack at
+the back of the board if it is placed.
+
+### EFC CLK Input
+
+The EFC requires a **common** clock source with the connected device.
+
+### EFC VADJ
+
+Configure **W1** and **W2** accordingly for 1.8V. Refer to the instructions on the board's silkscreen.
+
+### LTC2000 Sample Clock
+
+Songbird requires a sample clock, phase-locked with Kasli, so either a clock that Kasli uses for RTIO, or something generated from Kasli.
+
+In the perfect world, this clock should be high quality, with low jitter. However, Mirny output at 2.5GHz can also work relatively well.
+
+For RTIO clock of 125MHz (default), 2.5GHz is needed. For 100MHz, it's 2.4GHz.
+
+See the example experiment below for generating a suitable clock with Mirny. Connect Mirny's RF0 to J6 on the DC2303-A board.
+
+```python
+from artiq.experiment import *
+
+class SongbirdClockGen(EnvExperiment):
+    def build(self):
+        self.setattr_device("core")
+        self.setattr_device("mirny0_ch0")
+
+    @kernel
+    def run(self):
+        self.core.reset()
+        self.mirny0_ch0.init()
+        freq = 2.5 * GHz  # replace with 2.4 for 100MHz RTIO clk
+        self.mirny0_ch0.set_frequency(freq)
+        self.mirny0_ch0.set_att(0.0)
+        self.mirny0_ch0.sw.on()
+
+```
+
+## Testing
+
+With the sample clock provided, run `artiq_sinara_test`:
+
+```text
+*** Testing Songbird.
+Note: Songbird requires an appropriate sample clock. Connect it before testing.
+```
+
+The test generates a sine wave on each of the 4 DDS channels with a constant amplitude and different frequencies.
+
+Connect both differential outputs of DC2303-A to the oscilloscope and set these two channels to math substract.
+
+On the oscilloscope screen, you should see a constantly shifting signal. If you use the FFT function, the peaks should be at the frequencies shown by the testing tool.
+
+## Common issues
+
+Check [shuttler.md](shuttler.md) for these, as the EFC board is common.