RFSoC MIMO Controller

This project holds the firmware designs for RFSoC based Many-In-Many-Output (MIMO) control applications, featuring:

• Supports 3 hardware platforms:
  • AMD ZCU208: with xczu48dr-2fsvg1517e
  • LBL LBL208: with xczu47dr-1fsvg1517e
  • AMD ZCU216: with xczu29dr-2ffvf1760e
• Low phase noise sampling clock from external reference:
  • ADC/DAC sampling frequencies can be generated by an external reference:
    • CLK0 of LMK04828 on CLK104 board at J11, through LMK PLL chips (jitter cleaner)
    • CLK1 of LMK04828, bypassing LMK PLL loops with optimal phase jitter
  • Phase noise characterizaiton and optimizations
• Multi-Tile Synchronization (MTS):
  • All available ADC/DAC channels are enabled with MTS
• RF mixers with aligned digital NCO phase:
  • All digital up/down mixers are enabled with aligned NCO phase with respect to SYSREF clock
• Deterministic Latency
  • Power-cycle deterministic latency on top of MTS
• MRF EVR interface
  • Optional MRF timing interface and event receiver, to provide trigger and timestamps for user applications
  • Power-cycle deterministic latency
  • Self reconfiguration of timing link after loss of signals
• DDR4 PL RAM for long term data acquisition
• Triggered arbitrary waveform generation
• Synchronous ADC waveform capturing
• Chassis and peripheral support

Applications

• LBNL ALS Linac and Buncher digital Low-Level RF control system

📄 Research

This work was presented as in the Low Level 2025 Radio Frequency Workshop, October 2025, Newport News, VA, USA.

🚀 Quick Start

1. Download board image from pynq.io, ZCU208-3.0.1.img. Unzip and get zcu208_v3.0.1.img.

2. Flash SD card:

   sudo umount /dev/sdb1
   sudo dd bs=4M if=zcu208_v3.0.1.img of=/dev/sdb status=progress

   See details.

3. Boot. Prepare environment on the board:

   SSH into the Linux:

   ssh xilinx@192.168.2.99

   Clone the repository into the /home/xilinx/jupyter_notebooks directory, then run install script:

    cd ~/jupyter_notebooks
    git clone --recursive https://github.com/BerkeleyLab/LBNL-DSLLRF.git dsllrf
    cd dsllrf
    ./install.sh

   LBNL has an updated version of CLK104 board, which requires a device tree update by this step:

    sudo cp mimo_mts/boot.py /boot/

4. Prepare Overlay:

   • Synthesize overlay image on a computer with Vivado 2022.1 installed. Clone this repo and:

     git clone --recursive https://github.com/BerkeleyLab/LBNL-DSLLRF.git dsllrf
     cd dsllrf/designs/<board>/<design>
     make

     where:

     • <board> is one of [zcu208, lbl208, zcu216]
     • <design> is one of the available directory names like mimo_mts.

     Copy over the overlay files (both bitstream file and hardware descripton file) on the SD card:

     scp _xilinx/mimo_mts.{bit,hwh} xilinx@192.168.2.99:~/jupyter_notebooks/pynq_llrf/mimo_mts/overlays/zcu208/

   • Alternatively, download the CI generated overlay from GitLab artifacts. This option is not available on github.

5. [Optional] Change hostname and/or IP address. ssh on the board, then:

• Change hostname

  sudo -E pynq_hostname.sh lbl208

• Change static IP address. Update 192.168.2.99 in /etc/network/interfaces.d/eth0.

6. Connect a 500MHz, 0dBm clock to CLK104 J11. Connect SSMP cables for ADC/DAC sampling clocks.

7. Run:

   • For testing, run jupyter notebooks in doc/, see details.

   • For production, run EPICS IOC:

   MIMO or LLRF IOC on 3 supported RFSoC boards are available.

   sudo -E <app>-<board>-ioc

   where:

   • <app> is one of [mimo, llrf].
   • <board> is one of [zcu208, lbl208, zcu216].

   For example, for LLRF application running on LBL208 board,

   sudo -E llrf-lbl208-ioc

📖 Citation

If you use this design in your research or projects, please cite our papers.

1. RFSoC based LLRF system design at ALS

   Presentation slides

2. Comparative Evaluation of Xilinx RFSoC Platform for Low-Level RF Systems

Code Style and Linting

This project uses Ruff for both linting and formatting.

Ruff checks the mimo_mts and designs directories. All configuration lives in pyproject.toml under [tool.ruff].

The pipeline runs ruff check and ruff format --check. Unformatted or failing code blocks the merge. The pre-commit hook and editor setup below catch nearly everything before a push.

Environment setup

Install the development dependencies, which include a pinned Ruff version:

pip install -e .

Then run these from the repository root:

# Check for lint violations (same as CI)
ruff check mimo_mts designs

# Apply all safe automatic fixes
ruff check --fix mimo_mts designs

# Format code
ruff format mimo_mts designs

To automatically format / check before a commit install the pre-commit hooks:

pre-commit install

From now on, every git commit runs Ruff on all staged files. If Ruff changes anything, the commit is stopped so the changes can be reviewed. Run git add on the modified files and commit again. If the hook reports something it can't fix, fix it manually and retry.

We recommend enabling format-on-save in your code editor, so most issues are fixed as you work. Whichever editor you use, make sure it uses the Ruff binary from your project's virtual environment, not a separately bundled copy, so your results match CI.

A note about git blame

During the migration to ruff, a large number of files were modified, making the output of git blame somewhat less useful.

To locally ignore the formatting commit and restore functionality, run this command once:

git config blame.ignoreRevsFile .git-blame-ignore-revs

The same can be achieved in gitlab by following these steps.