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)
@@ -17,6 +18,7 @@
   - [Sinara 8452 DSP Stabilizer](./hw/stabilizer.md)
   - [Sinara 9805 RF Power Amplifier Booster](./hw/booster.md)
   - [Sinara 8451 Thermostat](./hw/thermostat.md)
+  - [Sinara 2245 LVDS DIO](./hw/lvds_dio.md)
 - [Software/Support](./sw_sup/software_support.md)
   - [Building legacy firmware](./sw_sup/artiq_legacy.md)
   - [Networking](./sw_sup/networking.md)

src/hw/booster.md

@@ -8,9 +8,40 @@
 
 ### Flashing
 
+#### Easier way
+
+Download and unpack the [booster firmware](../extra/booster/booster0.5.0.tar.xz), and then:
+```shell
+nix-shell -p dfu-util
+dfu-util -a 0 -s 0x08000000:leave --download booster0.5.0.bin
+```
+
+#### Build from source on Fedora 38
+
+Creating proper Nix shell for updated Rust is quite troublesome, so the faster way is actually to use any
+classic Linux distribution:
+
+```shell
+git clone https://github.com/quartiq/booster.git # download sources
+sudo dnf install clang dfu-util
+cd booster/
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # install Rust, we need rustup
+rustup target add thumbv7em-none-eabihf
+cargo install cargo-binutils
+rustup component add llvm-tools-preview
+cargo build --release
+cargo objcopy --release -- -O binary booster.bin
+# enter dfu mode by either serial terminal or
+# press `DFU Bootloader` button while rebooting
+dfu-util -a 0 -s 0x08000000:leave --download booster.bin
+```
+
+#### For version before September 2023 on NixOS
+
 ```shell
 git clone git@github.com:quartiq/booster.git
 cd booster
+git checkout a1f83b63180511ecd68f88a04621624941d17a41 # or earlier
 nix-shell -p rustup cargo rustc dfu-util
 rustup target add thumbv7em-none-eabihf
 cargo install cargo-binutils
@@ -32,7 +63,7 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
     ```
 3. `mosquitto -c mosquitto.conf -d`
 4. Run `cutecom`
-5. Connect to the Booster via `/dev/ttyACMX` port, baud 9600
+5. Connect to the Booster via `/dev/ttyACMX` port, baud 9600, switch from LF to CR on newer version
 6. Send `help` command to check if it works
 7. Enter commands (change details if necessary):
     ```shell
@@ -44,6 +75,13 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
     # apply changes and wait until it fully rebooted
     reset
     ```
+   Newer version:
+   ```shell
+    write broker "192.168.1.123"
+    write ip "192.168.1.75"
+    # apply changes and wait until it fully rebooted
+    reset
+    ```
 8. Check the Booster connects to your broker.
 9. Download AppImage from [MQTT Explorer](https://mqtt-explorer.com/)
 10. Run it with `appimage-run /path/to/MQTT-Explorer-XXX.AppImage`
@@ -52,15 +90,20 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
 
 ## Calibration
 
-1. Assemble Kasli with one Urukul, build and flash firmware for it with [booster.json](../extra/booster.json)
-2. Run [dds_for_booster.py](../extra/dds_for_booster.py) experiment once
+1. Assemble Kasli with one Urukul, build and flash firmware for it with [booster.json](../extra/booster/booster.json)
+2. Run [dds_for_booster.py](../extra/booster/dds_for_booster.py) experiment once
 3. Attach parallel 50 Ohm load to the oscilloscope, as shown on the picture: ![](../img/50ohm_parallel_load.jpg),
 4. Configure oscilloscope for 1M Ohm impedance
 5. Attach attenuator to the Urukul's RF2
 6. `cd py/`
-7. You may also need to download or install python's `gmqtt` and `miniconf`
+7. You may also need to download or install python's `gmqtt` and `miniconf`:
+   ```shell
+   python -m venv env
+   source env/bin/activate.fish
+   pip install git+https://github.com/quartiq/miniconf.git@84cc9046bf504cc2d0d33b84d2f3133f2faf2248#subdirectory=py/miniconf-mqtt
+   ```
 8. Enable channels: `python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N tune=0.1`
-9. Using [booster_template](../extra/booster_template.ods) fill in `y0`, `y1`, `m`, `c`, values using instructions below
+9. Using [booster_template](../extra/booster/booster_template.ods) fill in `y0`, `y1`, `m`, `c`, values using instructions below
 10. Update settings with the adjusted values
 11. Save settings with `python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N save`
 12. Reboot and check settings are applied

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/lvds_dio.md

@@ -0,0 +1,38 @@
+# Sinara 2245 LVDS DIO card
+
+* [Wiki](https://github.com/sinara-hw/DIO_LVDS_RJ45/wiki)
+* [Datasheet](https://m-labs.hk/docs/sinara-datasheets/2245.pdf)
+
+## JSON
+
+Be aware of the reversed EEM order on the card:
+
+```json
+[
+  {
+    "type": "dio",
+    "board": "DIO_LVDS",
+    "ports": [1],
+    "bank_direction_low": "input",
+    "bank_direction_high": "input",
+    "edge_counter": false // or true
+  }, 
+  {
+    "type": "dio",
+    "board": "DIO_LVDS",
+    "ports": [0],
+    "bank_direction_low": "output",
+    "bank_direction_high": "output"
+  }
+]
+```
+
+## Setup
+
+Switch DIPs in required position per each channel individually. Each RJ45 have 4 channels.
+
+## Testing
+
+You can test channels by connecting Ethernet RJ45 cable. Since the artiq_sinara_tester allows to choose only one DIO
+port, you will need to run the test 4 times and choose different output source and track that every 4th is passing the test. 
+It is also incompatible with other TTL cards, so you will need to use same or other LVDS card for proper testing.

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.

src/sw_sup/clocking.md

@@ -3,8 +3,7 @@
 This page describes ways to set up clocking. Official documentation references:
 
 * [Carrier configuration](https://m-labs.hk/artiq/manual/installing.html#miscellaneous-configuration-of-the-core-device)
-*
-Devices' [available options](https://m-labs.hk/artiq/manual/core_drivers_reference.html), [Urukul example](https://m-labs.hk/artiq/manual/core_drivers_reference.html#artiq.coredevice.urukul.CPLD)
+* Devices' [available options](https://m-labs.hk/artiq/manual/core_drivers_reference.html), [Urukul example](https://m-labs.hk/artiq/manual/core_drivers_reference.html#artiq.coredevice.urukul.CPLD)
 
 In general, any RF card and Carriers require some clock source. Most of them have both internal clock signal generator
 and external MMCX and/or SMA connectors to accept the signal. By default the internal clock is used for Carriers,
@@ -60,7 +59,11 @@ so Urukul entry may look like this:
 
 ```json
 {
-  "type": "urukul", "dds": "ad9910", "ports": [1, 2], "refclk": 10e6, "clk_sel": 1
+  "type": "urukul", 
+  "dds": "ad9910", 
+  "ports": [1, 2], 
+  "refclk": 10e6, 
+  "clk_sel": 1
 }
 ```