urukul: add note on clk_div with pll disabled

Signed-off-by: Egor Savkin <es@m-labs.hk>

src/SUMMARY.md

@@ -2,6 +2,7 @@
 
 - [Build and test firmware](./build_test_firmware.md)
 - [Hardware](./hw/hardware.md)
+  - [Sinara Kasli](./hw/kasli.md)
   - [Sinara Kasli-SOC](./hw/kasli_soc.md)
   - [Sinara 4624 AWG Phaser (Upconverter/Baseband)](./hw/phaser.md)
   - [Sinara 4456 synthesizer Mirny / Sinara 4457 Almazny Mezzanine card](./hw/mirny_almazny.md)

src/hw/kasli.md

@@ -0,0 +1,9 @@
+# Kasli
+
+## Mounting fan onto heatsink
+![](../img/kasli_fan.jpg)
+1. ⚠️ Verify the fan has the **correct polarity (powering on with wrong polarity will burn the MOSFET in series💥)**
+2. Place the fan on a heatsink
+3. Tap 3 threads on the heatsink using M2.5 pointy tapping screws (e.g. front panel screws)
+4. Replace the tapping screws with M2.5x14mm screws
+5. Verify the fan is secure

src/hw/kasli_soc.md

@@ -5,4 +5,12 @@
 Check the BOOT mode switches - they both should be at SD if the Kasli-SoC going to be shipped to customer.
 POR jumper needs only for JTAG mode.
 
-![](../img/kasli_soc.jpg)
+![](../img/kasli_soc.jpg)
+
+## Mounting fan onto heatsink
+![](../img/kasli_soc_fan.jpg)
+1. ⚠️ Verify the fan has the **correct polarity (powering on with wrong polarity will burn the MOSFET in series💥)**
+2. Place the fan on a heatsink
+3. Tap 3 threads on the heatsink using M2.5 pointy tapping screws (e.g. front panel screws)
+4. Replace the tapping screws with M2.5x14mm screws
+5. Verify the fan is secure

src/hw/urukul.md

@@ -30,6 +30,22 @@ Synchronization requires Kasli and Urukul to be clocked from the same oscillator
 why this feature is disabled by default.
 There is no intrinsic impact on Urukul output phase noise and the synchronization process is quick and reliable when done correctly.
 
+### One-EEM mode
+
+Users may choose to use only one EEM port, if they want more cards to be in their crate. However following features
+will become unavailable:
+ * SU-Servo
+ * Low-latency RF switch control
+ * Synchronization
+
+RF switches are still available but the commands need to go over the SPI bus so it's higher-latency and lower-resolution.
+
+### Urukul 4412
+
+Urukul 4412 has higher frequency resolution (47 bit against 32 at Urukul 4410), however lacks such features:
+ * SU-Servo
+ * Synchronization
+
 ## Testing
 
 After running `artiq_sinara_test`:
@@ -132,4 +148,25 @@ matches real clocker source.
 ValueError: Urukul AD9910 AUX_DAC mismatch
 ```
 
-Ensure it is the AD9910 and not the AD9912. Also check SUServo pins are set up respective to the JSON description.
+Ensure it is the AD9910 and not the AD9912. Also check SUServo pins are set up respective to the JSON description.
+
+### Jagged signal with 1GHz external clock on AD9910
+
+By default, on AD9910 external clock signal is divided by 4, while it should be not divided at all with PLL disabled.
+Change the ``clk_div`` parameter to the CPLD in the device_db file:
+
+```python
+device_db["urukulX_cpld"] = {
+    "type": "local",
+    "module": "artiq.coredevice.urukul",
+    "class": "CPLD",
+    "arguments": {
+        "spi_device": "spi_urukul0",
+        "sync_device": None,
+        "io_update_device": "ttl_urukul0_io_update",
+        "refclk": 1000000000.0,
+        "clk_sel": 1,
+        "clk_div" : 1 # <--- add this line
+    }
+}
+```

src/hw/zotino_fastino.md

@@ -55,4 +55,20 @@ Press ENTER when done.
 ### High-freq audible noise and output values all near -0.1 on Zotino v1.4.2
 
 This may happen when power-cycle is too short. Power down the crate, wait at least 30 seconds, and power up again.
-[Issue](https://github.com/sinara-hw/Zotino/issues/37).
+[Issue](https://github.com/sinara-hw/Zotino/issues/37).
+
+### Zero voltage output on Fastino
+
+Some Fastino may not output any voltage during testing, usually that means it has no gateware.
+
+Another common symptom of no gateware is that no LEDs are lit up. Whereas if the gateware has been flashed, the PG and FD LEDs will be lit green.
+
+You can flash the gateware with a standalone Kasli/Kasli-SoC:
+
+1. Download the latest `fastino.bin` release from [quartiq/fastino](https://github.com/quartiq/fastino/releases)
+2. Run `git clone https://github.com/quartiq/kasli-i2c.git` and place `fastino.bin` in the kasli-i2c directory
+2. Connect the Fastino's EEM0 to any available Kasli/Kasli-SoC EEM port (**do not hot-plug**)
+3. Power on the standalone Kasli/Kasli-SoC
+4. Run `nix-shell -p python311Packages.pyftdi`
+5. Run `cd kasli-i2c; python flash_fastino.py 0 EEM<number> write fastino.bin` where `<number>` is the EEM port number on the Kasli/Kasli-SoC side
+6. If PG and FD LEDs are lit green, the Fastino is ready.