From 767471689ea36eb7271d601c9a16c012250258fb Mon Sep 17 00:00:00 2001
From: Egor Savkin <es@m-labs.hk>
Date: Wed, 22 Feb 2023 15:27:39 +0800
Subject: [PATCH] Add two common fails on Urukul, and one hint to Fastino

Signed-off-by: Egor Savkin <es@m-labs.hk>
---
 src/hw/urukul.md         | 36 +++++++++++++++++++++++++++++++++++-
 src/hw/zotino_fastino.md |  3 +++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/hw/urukul.md b/src/hw/urukul.md
index 095c9c3..0d7e101 100644
--- a/src/hw/urukul.md
+++ b/src/hw/urukul.md
@@ -49,4 +49,38 @@ Press ENTER when done.
 1. Setup oscilloscope's impedance at 50 ohm
 2. Touch each connector with oscilloscope, setup time- and voltage- scale and trigger, so that you can see sine waves
 3. Measure frequencies and amplitudes on each connector, check with `artiq_sinara_test`'s respective values
-4. When done, proceed with `artiq_sinara_test` and check LEDs are lighting up one after another
\ No newline at end of file
+4. When done, proceed with `artiq_sinara_test` and check LEDs are lighting up one after another
+
+
+## Common problems
+
+### Urukul AD9912 product id mismatch
+
+```pycon
+ValueError: Urukul AD9912 product id mismatch
+```
+
+Some Urukuls may fail with this error during testing, usually meaning that the Urukul has not been flashed with the 
+firmware, especially if the ID is `65535` (you will need to edit the code to check this).
+
+You can flash the firmware yourself with a JTAG adapter:
+
+1. Download the latest binary release from [quartiq/urukul](https://github.com/quartiq/urukul) and extract the `urukul.jed` file.
+2. Connect the Urukul with the JTAG adapter to the PC and connect its EEM0 to any available Kasli/Kasli-SoC (do not hot-plug), then turn on the Kasli/Kasli-SoC.
+3. Run `nix-shell -p xc3sprog`.
+4. Run `xc3sprog -c jtaghs2 urukul.jed -m /opt/Xilinx/Vivado/<available version>/data/xicom/cable_data/digilent/lnx64/xbr/`.
+5. If the last command outputs Verify: Success, then your Urukul is ready. It can also output the message 
+   ```shell
+   *** buffer overflow detected ***: terminated
+   Aborted (core dumped)
+   ```
+   , which is okay if `Verify: Success` was also emitted.
+
+### no valid window/delay
+
+```pycon
+ValueError: no valid window/delay
+```
+
+Check with the customer to see if synchronization is necessary, and disable it if it is not. 
+In any case, simply restart the test.
\ No newline at end of file
diff --git a/src/hw/zotino_fastino.md b/src/hw/zotino_fastino.md
index c0c6235..b8b6405 100644
--- a/src/hw/zotino_fastino.md
+++ b/src/hw/zotino_fastino.md
@@ -20,6 +20,9 @@
 }
 ```
 
+Fastino uses two physical EEM channels, but in the JSON file there should be only one channel specified, 
+and it should be the one connected to Fastino's EEM0.
+
 ## Setup
 
 Connect the BNC/SMA-IDC adapters to the Zotino/Fastino with 26-pin cable if needed by customer. Be aware of the ports order -