assembly/src/hw/urukul.md

# Sinara 4410/4412 DDS Urukul (AD9910/AD9912)

* [Datasheet](https://m-labs.hk/docs/sinara-datasheets/4410-4412.pdf)
* [Wiki](https://github.com/sinara-hw/Urukul/wiki)
* [Firmware](https://github.com/quartiq/urukul)

## JSON

```json
{
    "type": "urukul",
    "dds": "<variant>", // ad9910/ad9912
    "ports": [<port num>, <port num>], // second port is optional
    "clk_sel": <clock num>,
    "synchronization": true/false, // for AD9910 only
    "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 respective to customer needs. Connect to the clocker source.

### Synchronization

Synchronization option in the JSON refers to the phase synchronization between the outputs, and can be used only on AD9910 variants and
only with 125 MHz clock source provided from Kasli/Kasli-SoC (may be relayed through the Clocker board).
The phase sync works only within one Urukul board, though the phase shift between Urukuls may be [predictable](https://github.com/m-labs/artiq/issues/1692#issuecomment-994439589). 
Even though it is widely-desirable feature, there are drawbacks of this preventing from enabling by default:
1. The resulting signal is more noisy, which can be observed [previously](https://github.com/sinara-hw/Urukul/issues/64).
2. Phase sync process takes time and sometimes fails
3. ???

## Testing

After running `artiq_sinara_test`:

```text
*** Testing Urukul DDSes.
urukul0_cpld: initializing CPLD...
urukul0_cpld: testing attenuator digital control...
urukul0_cpld: done
Calibrating inter-device synchronization...
urukul0_ch0	no EEPROM synchronization
urukul0_ch1	no EEPROM synchronization
urukul0_ch2	no EEPROM synchronization
urukul0_ch3	no EEPROM synchronization
...done
All urukul channels active.
Check each channel amplitude (~1.6Vpp/8dbm at 50ohm) and frequency.
Frequencies:
urukul0_ch0	10MHz
urukul0_ch1	11MHz
urukul0_ch2	12MHz
urukul0_ch3	13MHz
Press ENTER when done.

Testing RF switch control. Check LEDs at urukul RF ports.
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


## Common problems

### Urukul AD9912 product id mismatch or missing LEDs

```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). 

Another common symptom of no firmware is that no LEDs are lit up, besides Power Good - whereas if the firmware has been flashed, the RF channels will be lit red.

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 power 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.

### 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.

### Urukul proto_rev mismatch

```pycon
ValueError: Urukul proto_rev mismatch
```

Check the ports are connected respectively to the JSON description.

### PLL lock timeout

```pycon
ValueError: PLL lock timeout
```

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 and `EXT`/`INT` pin 
matches real clocker source.

### Urukul AD9910 AUX_DAC mismatch

```pycon
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.