Add MCX TTL instructions

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

src/SUMMARY.md

@@ -6,6 +6,7 @@
   - [Sinara 4456 synthesizer Mirny / Sinara 4457 Almazny Mezzanine card](./hw/mirny_almazny.md)
   - [SUServo (Sampler + Urukul)](./hw/suservo.md)
   - [Sinara 2118 BNC-TTL / 2128 SMA-TTL](./hw/bnc_sma_ttl.md)
+  - [Sinara 2138 MCX-TTL](./hw/mcx_ttl.md)
   - [Sinara 5432 DAC Zotino / Sinara 5632 DAC Fastino](./hw/zotino_fastino.md)
   - [Sinara 5518 BNC-IDC / 5528 SMA-IDC adapter](./hw/bnc_sma_idc_adapter.md)
   - [Sinara 4410/4412 DDS Urukul (AD9910/AD9912)](./hw/urukul.md)

src/build_test_firmware.md

@@ -55,6 +55,8 @@ nix build -L --impure --expr 'let fl = builtins.getFlake "git+file://<path to ar
 # copy `results/boot.bin` to the SD card
 # insert SD card to the Kasli-SoC and boot
 artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75
+# update firmware
+artiq_coremgmt config write -f boot result/boot.bin
 # reboot via power supply
 artiq_sinara_tester
 ```

src/hw/clocker.md

@@ -4,7 +4,7 @@
 
 ## JSON
 
-Put the `ext_ref_frequency` field into the JSON description if the Clocker is going to use an external frequency:
+Put the `ext_ref_frequency` field into the JSON description if the Kasli is going to use an external frequency:
 
 ```json
 {
@@ -38,14 +38,16 @@ Here is example setup for SynthNV RF signal generator:
 
 ### Setup the Clocker
 
-1. Connect MMCx cables according to the customer needs and boards specifications (see image below for reference)
-2. Connect the Clocker to the Kasli via 30-pin ports
+1. Switch `CLK SEL` pin to `EXT`/`INT` according to customer needs
+2. Connect MMCx cables according to the customer needs and boards specifications (see image below for reference): 
+   if the `INT` source is chosen, connect MMCx cable to `INT CLK`, otherwise connect external clocker to SMA `EXT CLK` 
+3. Connect the Clocker to the Kasli via 30-pin ports
    ![](../img/clocker_ref.jpg)
-3. Connect the Clocker's SMA output to the Kasli's `CLK`/`CLK IN` SMA pin
-4. After assembling the crates and flashing the firmware, start Kasli and write config as follows:
+4. Connect the Clocker's SMA output to the Kasli's `CLK`/`CLK IN` SMA pin
+5. After assembling the crates and flashing the firmware, start Kasli and write config as follows:
    `artiq_coremgmt config write -s rtio_clock ext0_bypass`. Please refer to the [official manual](https://m-labs.hk/artiq/manual/installing.html#miscellaneous-configuration-of-the-core-device)
    for the details and available options
-5. Reboot either via `artiq_coremgmt reboot` or via power supply if the board's firmware doesn't have such command
+6. Reboot either via `artiq_coremgmt reboot` or via power supply if the board's firmware doesn't have such command
 
 ## Testing
 

src/hw/mcx_ttl.md

@@ -0,0 +1,41 @@
+# Sinara 2238 MCX TTL card
+
+[Wiki](https://github.com/sinara-hw/DIO_MCX/wiki)
+[Datasheet](https://m-labs.hk/docs/sinara-datasheets/2238.pdf)
+
+# JSON
+
+```json
+[
+    {
+        "type": "dio",
+        "board": "DIO_MCX",
+        "ports": [0],
+        "edge_counter": true, // optional
+        "bank_direction_low": "input",
+        "bank_direction_high": "output"
+    },
+    {
+        "type": "dio",
+        "board": "DIO_MCX",
+        "ports": [1],
+        "bank_direction_low": "output",
+        "bank_direction_high": "output"
+    }
+]
+```
+
+Since MCX TTL has twice as much as BNC/SMA cards, it is treated as two cards - there are 2 ports to be connected
+and 2 entries in the JSON.
+
+## Setup
+
+Switch the direction switches (shown on the picture below) according to customer requests.
+Remember, that you can only switch directions in groups of four.
+
+![](../img/ttl_mcx.jpg)
+
+## Test
+
+Refer to the [BNC/SMA TTL instructions](bnc_sma_ttl.md) for testing, but chose appropriate connector, 
+and respect increased number of channels.

src/hw/urukul.md

@@ -10,13 +10,15 @@
     "type": "urukul",
     "dds": "<variant>", // ad9910/ad9912
     "ports": [<port num>, <port num>],
-    "clk_sel": <clock num>
+    "clk_sel": <clock num>,
+    "refclk": <freq>, // for external clock signal
+    "pll_en": <0 or 1, default 1> // PLL bypass, to allow higher external clocker frequencies (1e9 for example)
 }
 ```
 
 ## Setup
 
-Check if [SUServo](./suservo.md) is enabled/disabled on customer needs.
+Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs. Connect to the clocker source.
 
 ## Testing
 
@@ -84,3 +86,12 @@ 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.
+
+### Noise instead of signal
+
+It may be due to misconfiguration of SUServo. Check that both firmware and pins enable/disable the SUServo mode.
+
+### Improper frequency
+
+This can happen due to lack/bad clock source connection. Check that clock source is connected respective to the customer needs,
+and if it is connected to the [Clocker](clocker.md), check that clocker receives clock signal properly.